[ai] Add StreamText with an example (#510)

## Summary
Adds StreamText and StreamTextStr to the top-level `ai` package. These
are the streaming counterparts to GenerateText and GenerateTextStr.

Adds an example showing the streaming case.

## How was it tested?
Ran the example successfully.

## Community Contribution License

All community contributions in this pull request are licensed to the
project maintainers under the terms of the [Apache 2
License](https://www.apache.org/licenses/LICENSE-2.0).

By creating this pull request I represent that I have the right to
license the contributions to the project maintainers under the Apache 2
License as stated in the [Community Contribution
License](https://github.com/jetify-com/opensource/blob/main/CONTRIBUTING.md#community-contribution-license).

Author: loreto

aisdk/ai/ai.go

@@ -61,3 +61,59 @@ func GenerateTextStr(ctx context.Context, prompt string, opts ...GenerateOption)
 func generate(ctx context.Context, prompt []api.Message, opts GenerateOptions) (api.Response, error) {
 	return opts.Model.Generate(ctx, prompt, opts.CallOptions)
 }
+
+// StreamText uses a language model to generate a streaming text response from a given prompt.
+//
+// This function streams its output as a sequence of events.
+//
+// It returns a [api.StreamResponse] containing a stream of events from the model,
+// including partial text, tool calls, and additional information.
+//
+// A prompt is a sequence of [api.Message]s:
+//
+//	StreamText(ctx, []api.Message{
+//		&api.UserMessage{
+//			Content: []api.ContentBlock{
+//				&api.TextBlock{Text: "Show me a picture of a cat"},
+//			},
+//		},
+//		&api.AssistantMessage{
+//			Content: []api.ContentBlock{
+//				&api.TextBlock{Text: "Here is a picture of a cat"},
+//				&api.ImageBlock{URL: "https://example.com/cat.png"},
+//			},
+//		},
+//	})
+//
+// The last argument can optionally be a series of [GenerateOption] arguments:
+//
+//	StreamText(ctx, messages, WithMaxTokens(100))
+func StreamText(ctx context.Context, prompt []api.Message, opts ...GenerateOption) (api.StreamResponse, error) {
+	config := buildGenerateConfig(opts)
+	return stream(ctx, prompt, config)
+}
+
+// StreamTextStr uses a language model to generate a streaming text response from a given string prompt.
+//
+// It is a convenience wrapper around StreamText for simple string-based prompts.
+//
+// Example usage:
+//
+//	StreamTextStr(ctx, "Write a brief summary of the benefits of renewable energy")
+//
+// The function can optionally take [GenerateOption] arguments:
+//
+//	StreamTextStr(ctx, "Explain the key differences between REST and GraphQL APIs", WithMaxTokens(500))
+//
+// The string prompt is automatically converted to a [api.UserMessage] before
+// being passed to StreamText.
+func StreamTextStr(ctx context.Context, prompt string, opts ...GenerateOption) (api.StreamResponse, error) {
+	msg := api.UserMessage{
+		Content: []api.ContentBlock{api.TextBlock{Text: prompt}},
+	}
+	return StreamText(ctx, []api.Message{msg}, opts...)
+}
+
+func stream(ctx context.Context, prompt []api.Message, opts GenerateOptions) (api.StreamResponse, error) {
+	return opts.Model.Stream(ctx, prompt, opts.CallOptions)
+}

aisdk/ai/examples/README.md

@@ -20,11 +20,11 @@ Get your API keys from:
 | Example | Description |
 |---------|-------------|
 | [**simple-text**](basic/simple-text/) | Generate text from a simple string prompt |
+| [**streaming-text**](basic/streaming-text/) | Stream text responses in real-time |
 
 ### More Examples Coming Soon
 
 - **Conversation** - Multi-message conversations with context
-- **Streaming** - Stream responses in real-time
 - **Multi-modal** - Working with images and files
 - **Tools** - Function calling and tool usage
 - **Advanced** - Production patterns and error handling

aisdk/ai/examples/basic/streaming-text/main.go

@@ -0,0 +1,60 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+
+	"go.jetify.com/ai"
+	"go.jetify.com/ai/api"
+	"go.jetify.com/ai/provider/openai"
+)
+
+func example() error {
+	// Create a model
+	model := openai.NewLanguageModel("gpt-4o-mini")
+
+	// Stream text
+	response, err := ai.StreamTextStr(
+		context.Background(),
+		"Explain what artificial intelligence is in simple terms",
+		ai.WithModel(model),
+		ai.WithMaxOutputTokens(100),
+	)
+	if err != nil {
+		return err
+	}
+
+	// Print the streaming response:
+	printStreamResponse(response)
+
+	return nil
+}
+
+func printStreamResponse(response api.StreamResponse) {
+	fmt.Print("AI: ")
+
+	for event := range response.Stream {
+		switch e := event.(type) {
+		case *api.TextDeltaEvent:
+			// Print text delta events as they arrive
+			fmt.Print(e.TextDelta)
+		case *api.FinishEvent:
+			// Print final information
+			fmt.Printf("\n\nFinish Reason: %s\n", e.FinishReason)
+			fmt.Printf("Usage: Input=%d, Output=%d, Total=%d tokens\n",
+				e.Usage.InputTokens,
+				e.Usage.OutputTokens,
+				e.Usage.TotalTokens)
+		case *api.ErrorEvent:
+			// Handle errors
+			fmt.Printf("\nError: %s\n", e.Error())
+		}
+	}
+}
+
+func main() {
+	if err := example(); err != nil {
+		log.Fatal(err)
+	}
+}