Initial commit

2026-04-23 23:58:59 -05:00
commit 47b9e3c159
257 changed files with 18913 additions and 0 deletions
@@ -0,0 +1,176 @@
+# Generation
+
+## GenerateText
+
+Simplest form. Returns a string.
+
+```go
+text, err := genkit.GenerateText(ctx, g,
+	ai.WithModelName("googleai/gemini-flash-latest"),
+	ai.WithPrompt("Tell me a joke about %s", topic),
+)
+```
+
+## Generate
+
+Returns a full `*ModelResponse` with metadata, usage stats, and history.
+
+```go
+resp, err := genkit.Generate(ctx, g,
+	ai.WithModelName("googleai/gemini-flash-latest"),
+	ai.WithSystem("You are a helpful assistant."),
+	ai.WithPrompt("Explain %s", topic),
+)
+fmt.Println(resp.Text())         // concatenated text
+fmt.Println(resp.FinishReason)   // ai.FinishReasonStop, etc.
+fmt.Println(resp.Usage)          // token counts
+```
+
+## GenerateData (Structured Output)
+
+Returns a typed Go value parsed from the model's JSON output.
+
+```go
+type Joke struct {
+	Setup     string `json:"setup" jsonschema:"description=The setup of the joke"`
+	Punchline string `json:"punchline" jsonschema:"description=The punchline"`
+}
+
+joke, resp, err := genkit.GenerateData[Joke](ctx, g,
+	ai.WithModelName("googleai/gemini-flash-latest"),
+	ai.WithPrompt("Tell me a joke about %s", topic),
+)
+// joke is *Joke, resp is *ModelResponse
+```
+
+## Streaming
+
+### GenerateStream
+
+Returns an iterator. Each value has `.Done`, `.Chunk`, and `.Response`.
+
+```go
+stream := genkit.GenerateStream(ctx, g,
+	ai.WithModelName("googleai/gemini-flash-latest"),
+	ai.WithPrompt("Tell me a long story about %s", topic),
+)
+for result, err := range stream {
+	if err != nil {
+		return err
+	}
+	if result.Done {
+		finalText := result.Response.Text()
+		break
+	}
+	fmt.Print(result.Chunk.Text()) // incremental text
+}
+```
+
+### GenerateDataStream (Structured Streaming)
+
+Streams typed partial objects as they arrive.
+
+```go
+stream := genkit.GenerateDataStream[Joke](ctx, g,
+	ai.WithModelName("googleai/gemini-flash-latest"),
+	ai.WithPrompt("Tell me a joke about %s", topic),
+)
+for result, err := range stream {
+	if err != nil {
+		return err
+	}
+	if result.Done {
+		finalJoke := result.Output // *Joke
+		break
+	}
+	partialJoke := result.Chunk // *Joke (partial)
+}
+```
+
+### Callback-Based Streaming
+
+Use `ai.WithStreaming` with `Generate` for callback-style streaming. The callback receives `*ai.ModelResponseChunk`:
+
+```go
+resp, err := genkit.Generate(ctx, g,
+	ai.WithModelName("googleai/gemini-flash-latest"),
+	ai.WithPrompt("Tell me a story"),
+	ai.WithStreaming(func(ctx context.Context, chunk *ai.ModelResponseChunk) error {
+		fmt.Print(chunk.Text()) // extract text from chunk
+		return nil
+	}),
+)
+// resp contains the final complete response
+```
+
+## Common Options
+
+```go
+// Model selection
+ai.WithModel(googlegenai.ModelRef("googleai/gemini-flash-latest", nil))  // model reference
+ai.WithModelName("googleai/gemini-flash-latest")                         // by name string
+
+// Content
+ai.WithPrompt("Tell me about %s", topic)    // user message (supports fmt verbs)
+ai.WithSystem("You are a pirate.")          // system instructions
+ai.WithMessages(msg1, msg2)                 // conversation history
+ai.WithDocs(doc1, doc2)                     // context documents
+ai.WithTextDocs("context 1", "context 2")   // context as strings
+
+// Model config (provider-specific)
+ai.WithConfig(map[string]any{"temperature": 0.7})
+```
+
+## Output Formats
+
+Control how the model structures its output.
+
+### By Go Type
+
+```go
+// Automatically uses JSON format and instructs model to match the type
+ai.WithOutputType(MyStruct{})
+```
+
+### By Format String
+
+```go
+ai.WithOutputFormat(ai.OutputFormatJSON)   // single JSON object
+ai.WithOutputFormat(ai.OutputFormatJSONL)  // JSON Lines (one object per line)
+ai.WithOutputFormat(ai.OutputFormatArray)  // JSON array
+ai.WithOutputFormat(ai.OutputFormatEnum)   // constrained enum value
+ai.WithOutputFormat(ai.OutputFormatText)   // plain text (default)
+```
+
+### Enum Output
+
+```go
+type Color string
+const (
+	Red   Color = "red"
+	Green Color = "green"
+	Blue  Color = "blue"
+)
+
+text, err := genkit.GenerateText(ctx, g,
+	ai.WithPrompt("What color is the sky?"),
+	ai.WithOutputEnums(Red, Green, Blue),
+)
+```
+
+### Custom Output Instructions
+
+```go
+ai.WithOutputInstructions("Return a JSON object with fields: name (string), age (number)")
+```
+
+### Combining Format + Schema
+
+```go
+// JSONL with a typed schema (useful for streaming lists)
+genkit.DefinePrompt(g, "characters",
+	ai.WithPrompt("Generate 5 story characters"),
+	ai.WithOutputType([]StoryCharacter{}),
+	ai.WithOutputFormat(ai.OutputFormatJSONL),
+)
+```