Twilight AI
When To Use
Use this skill when the task involves twilight-ai, especially:
- implementing or refactoring SDK APIs in
sdk/
- adding or updating providers under
provider/
- working on
Model.Generate, Model.Stream, Embed, EmbedMany, GenerateImage, or EditImage
- adding tool-calling, streaming, reasoning, embedding, or image generation support
- writing examples, docs, or usage guidance for this library
Project Snapshot
Twilight AI is a lightweight Go AI SDK with a provider-agnostic core API.
- Text generation: build an
sdk.Request and call Model.Generate or Model.Stream; one call, one ModelResult
- Image generation:
sdk.GenerateImage, sdk.EditImage
- Embeddings:
sdk.Embed, sdk.EmbedMany
- Tool calling:
sdk.ToolDefinition (or sdk.NewToolDefinition[T]), typed sdk.ToolCall / sdk.ToolArguments / sdk.ToolOutput
- Streaming: typed
StreamPart events over Go channels
- Current providers:
provider/openai/completions
provider/openai/responses
provider/openai/codex
provider/openai/images
provider/anthropic/messages
provider/google/generativeai
provider/openai/embedding
provider/google/embedding
Default Mental Model
Prefer the high-level SDK API first, then drop to provider details only when needed.
sdk.Model binds a chat model to a sdk.Provider
sdk.EmbeddingModel binds an embedding model to an sdk.EmbeddingProvider
sdk.ImageGenerationModel binds an image generation model to an sdk.ImageGenerationProvider
sdk.ImageEditModel binds an image edit model to an sdk.ImageEditProvider
- A runtime drives
Model.Generate or Model.Stream with an sdk.Request, runs the returned ToolCalls, and appends the assistant and tool messages of the step to the next request
- Providers handle backend-specific HTTP, request mapping, response parsing, and SSE translation
Core API Guidance
Choose the narrowest API that matches the task:
- Need one model call and its result: use
Model.Generate or Model.Stream with an sdk.Request
- Need one vector: use
sdk.Embed
- Need multiple vectors or embedding token usage: use
sdk.EmbedMany
- Need image generation from a text prompt: use
sdk.GenerateImage
- Need image editing or inpainting: use
sdk.EditImage
If the task introduces examples or docs, prefer simple end-to-end snippets that start with:
- construct provider
- get model
- call SDK API
- handle error
Provider Selection Rules
- Use
openai/completions for broad OpenAI-compatible support such as DeepSeek, Groq, Ollama, Azure-style compatible endpoints, and generic /chat/completions backends.
- Use
openai/responses when the task needs OpenAI Responses API features such as first-class reasoning models, reasoning summaries, URL citation annotations, or flat input mapping.
- Use
openai/codex when the task needs OpenAI Codex coding agent models (gpt-5.x-codex series) with ChatGPT access token authentication and encrypted reasoning content.
- Use
anthropic/messages for Claude and Anthropic extended thinking via WithThinking.
- Use
google/generativeai for Gemini chat, tool calling, vision, streaming, and Gemini reasoning.
- Use
openai/images for image generation (dall-e-2, dall-e-3, gpt-image-1) and image editing via the OpenAI Images API.
- Use
openai/embedding or google/embedding for embeddings. Keep embedding-provider work separate from chat-provider work.
Implementation Rules
Chat Providers
If adding or changing a chat provider, preserve the sdk.Provider contract:
Name()
ListModels(ctx)
Test(ctx)
TestModel(ctx, modelID)
DoGenerate(ctx, req sdk.Request) (sdk.ModelResult, error)
DoStream(ctx, req sdk.Request) (<-chan sdk.StreamPart, error)
Keep provider responsibilities focused:
- translate SDK messages/options into backend request format
- parse backend responses into
sdk.ModelResult
- map backend streaming events into typed
sdk.StreamPart values; the SDK core assembles them into a ModelResult
- report usage, finish reasons, reasoning, tool calls, sources, and files when supported
Embedding Providers
Embedding providers are separate from chat providers. Use sdk.EmbeddingProvider and return an sdk.EmbeddingModel via EmbeddingModel(id).
When updating embeddings:
- keep
sdk.Embed for single-string convenience
- keep
sdk.EmbedMany for batched requests
- preserve
Usage.Tokens
- only expose dimensions/task-type behavior when the backend supports it
Image Providers
Image providers are separate from chat, embedding, and speech providers. Use sdk.ImageGenerationProvider and/or sdk.ImageEditProvider.
When updating image providers:
- keep
sdk.GenerateImage for generation convenience
- keep
sdk.EditImage for editing convenience
- preserve
ImageUsage token details when the backend supports them
- support both multipart file upload and JSON reference modes for edit inputs
Tool Calling
Prefer sdk.NewToolDefinition[T] for new tool examples: typed arguments and an inferred JSON Schema.
Use these defaults unless the task requires something else:
Request.ToolChoice left zero (auto) for normal use; sdk.ToolChoice{Mode: sdk.ToolChoiceRequired} or {Mode: sdk.ToolChoiceTool, Tool: name} to force a call
- one
Generate per step; the caller runs the returned ToolCalls and decides how many steps to take
- a call's arguments are
sdk.ToolArguments; decode with Unmarshal, never assume a map[string]any; Valid() false means answer the model with an error result instead of running the tool
- a tool's result is a
sdk.ToolResultPart whose Result is sdk.TextOutput or sdk.JSONOutput; the replayed assistant message keeps the reasoning parts and each part's ProviderMetadata
When streaming with tools, the stream emits tool input construction parts and one StreamToolCallPart per completed call.
Streaming
Twilight AI streaming is channel-first and type-safe. Prefer type switches over loosely typed event parsing.
Important expectations:
Model.Stream returns an sdk.ModelStream: Parts is the channel of sdk.StreamPart values, Result() is valid once Parts is drained
sdk.CollectStream is the convenience path when callers do not want manual event handling
- a stream is one model call; it carries no tool execution events
Messages And Results
Preserve the SDK message model and avoid backend-specific shapes leaking into public usage.
- user, assistant, system, and tool messages should stay in SDK types
- support rich parts where relevant: text, image, file, reasoning, tool call, tool result
- keep finish reason mapping aligned with SDK constants such as
stop, length, content-filter, and tool-calls
Common Task Patterns
Add A New Usage Example
Use this structure:
- pick the correct provider package
- create provider with explicit options
- create model via
ChatModel, EmbeddingModel, GenerationModel, or EditModel
- call the top-level
sdk function
- show minimal but idiomatic result handling
Add Or Update A Provider Feature
Check all affected layers:
- request mapping
- non-streaming response mapping
- streaming event mapping
- finish-reason and usage mapping
- reasoning/tool/source/file support if the backend exposes them
- model discovery and provider health checks if endpoints exist
Add A Custom Provider
Use the built-in providers as the template. A custom provider should feel identical to existing ones from the caller's perspective.
Minimum behavior:
- return a provider-bound model from
ChatModel
- implement discovery and health-check methods
- support
DoGenerate
- support
DoStream with correct lifecycle parts
Documentation Rules
When writing Twilight AI docs or README content:
- prefer provider-agnostic phrasing first, provider-specific details second
- use Go examples, not pseudocode, unless explaining an interface contract
- keep examples small and runnable in spirit
- mention exact package paths for imports
- explain when to choose Completions vs Responses vs Codex when OpenAI is involved
- keep embeddings, tool calling, and streaming as separate concerns unless the example truly combines them
Terminology
Use these terms consistently:
- Provider: backend implementation for chat generation
- Embedding provider: backend implementation for embeddings
- Image generation provider: backend implementation for image generation
- Image edit provider: backend implementation for image editing
- Model: provider-bound chat model
- Embedding model: provider-bound embedding model
- Image generation model: provider-bound image generation model
- Image edit model: provider-bound image edit model
- Tool calling: model requests a tool invocation
- Step: one model call plus the tool calls it made; the caller assembles the assistant and tool messages
- Stream part: a typed event from the model seam (
sdk.StreamPart), delivered by Model.Stream
Quick Checklist
Before finishing work in this repo, verify:
- the chosen provider package matches the intended backend capabilities
- chat, embedding, and image concerns are not mixed accidentally
- public examples use top-level
sdk APIs unless lower-level behavior is the point
- streaming logic uses typed
StreamPart handling
- tool-calling examples build the replayed assistant and tool messages by hand
- provider work includes health checks or model discovery behavior if the backend supports them
Additional Resources
- For exported APIs, signatures, provider options, and stream/event types, see reference.md
1---2name: twilight-ai3description: Assist with development in the Twilight AI Go SDK. Use when working in this repository, adding or updating providers, embeddings, tool calling, streaming, examples, or docs for Twilight AI.4metadata:5 source: https://skillmd.com/skills/tuyv/twilight-ai6---78# Twilight AI910## When To Use1112Use this skill when the task involves `twilight-ai`, especially:1314- implementing or refactoring SDK APIs in `sdk/`15- adding or updating providers under `provider/`16- working on `Model.Generate`, `Model.Stream`, `Embed`, `EmbedMany`, `GenerateImage`, or `EditImage`17- adding tool-calling, streaming, reasoning, embedding, or image generation support18- writing examples, docs, or usage guidance for this library1920## Project Snapshot2122Twilight AI is a lightweight Go AI SDK with a provider-agnostic core API.2324- Text generation: build an `sdk.Request` and call `Model.Generate` or `Model.Stream`; one call, one `ModelResult`25- Image generation: `sdk.GenerateImage`, `sdk.EditImage`26- Embeddings: `sdk.Embed`, `sdk.EmbedMany`27- Tool calling: `sdk.ToolDefinition` (or `sdk.NewToolDefinition[T]`), typed `sdk.ToolCall` / `sdk.ToolArguments` / `sdk.ToolOutput`28- Streaming: typed `StreamPart` events over Go channels29- Current providers:30 - `provider/openai/completions`31 - `provider/openai/responses`32 - `provider/openai/codex`33 - `provider/openai/images`34 - `provider/anthropic/messages`35 - `provider/google/generativeai`36 - `provider/openai/embedding`37 - `provider/google/embedding`3839## Default Mental Model4041Prefer the high-level SDK API first, then drop to provider details only when needed.4243- `sdk.Model` binds a chat model to a `sdk.Provider`44- `sdk.EmbeddingModel` binds an embedding model to an `sdk.EmbeddingProvider`45- `sdk.ImageGenerationModel` binds an image generation model to an `sdk.ImageGenerationProvider`46- `sdk.ImageEditModel` binds an image edit model to an `sdk.ImageEditProvider`47- A runtime drives `Model.Generate` or `Model.Stream` with an `sdk.Request`, runs the returned `ToolCalls`, and appends the assistant and tool messages of the step to the next request48- Providers handle backend-specific HTTP, request mapping, response parsing, and SSE translation4950## Core API Guidance5152Choose the narrowest API that matches the task:5354- Need one model call and its result: use `Model.Generate` or `Model.Stream` with an `sdk.Request`55- Need one vector: use `sdk.Embed`56- Need multiple vectors or embedding token usage: use `sdk.EmbedMany`57- Need image generation from a text prompt: use `sdk.GenerateImage`58- Need image editing or inpainting: use `sdk.EditImage`5960If the task introduces examples or docs, prefer simple end-to-end snippets that start with:61621. construct provider632. get model643. call SDK API654. handle error6667## Provider Selection Rules6869- Use `openai/completions` for broad OpenAI-compatible support such as DeepSeek, Groq, Ollama, Azure-style compatible endpoints, and generic `/chat/completions` backends.70- Use `openai/responses` when the task needs OpenAI Responses API features such as first-class reasoning models, reasoning summaries, URL citation annotations, or flat input mapping.71- Use `openai/codex` when the task needs OpenAI Codex coding agent models (gpt-5.x-codex series) with ChatGPT access token authentication and encrypted reasoning content.72- Use `anthropic/messages` for Claude and Anthropic extended thinking via `WithThinking`.73- Use `google/generativeai` for Gemini chat, tool calling, vision, streaming, and Gemini reasoning.74- Use `openai/images` for image generation (dall-e-2, dall-e-3, gpt-image-1) and image editing via the OpenAI Images API.75- Use `openai/embedding` or `google/embedding` for embeddings. Keep embedding-provider work separate from chat-provider work.7677## Implementation Rules7879### Chat Providers8081If adding or changing a chat provider, preserve the `sdk.Provider` contract:8283- `Name()`84- `ListModels(ctx)`85- `Test(ctx)`86- `TestModel(ctx, modelID)`87- `DoGenerate(ctx, req sdk.Request) (sdk.ModelResult, error)`88- `DoStream(ctx, req sdk.Request) (<-chan sdk.StreamPart, error)`8990Keep provider responsibilities focused:9192- translate SDK messages/options into backend request format93- parse backend responses into `sdk.ModelResult`94- map backend streaming events into typed `sdk.StreamPart` values; the SDK core assembles them into a `ModelResult`95- report usage, finish reasons, reasoning, tool calls, sources, and files when supported9697### Embedding Providers9899Embedding providers are separate from chat providers. Use `sdk.EmbeddingProvider` and return an `sdk.EmbeddingModel` via `EmbeddingModel(id)`.100101When updating embeddings:102103- keep `sdk.Embed` for single-string convenience104- keep `sdk.EmbedMany` for batched requests105- preserve `Usage.Tokens`106- only expose dimensions/task-type behavior when the backend supports it107108### Image Providers109110Image providers are separate from chat, embedding, and speech providers. Use `sdk.ImageGenerationProvider` and/or `sdk.ImageEditProvider`.111112When updating image providers:113114- keep `sdk.GenerateImage` for generation convenience115- keep `sdk.EditImage` for editing convenience116- preserve `ImageUsage` token details when the backend supports them117- support both multipart file upload and JSON reference modes for edit inputs118119### Tool Calling120121Prefer `sdk.NewToolDefinition[T]` for new tool examples: typed arguments and an inferred JSON Schema.122123Use these defaults unless the task requires something else:124125- `Request.ToolChoice` left zero (auto) for normal use; `sdk.ToolChoice{Mode: sdk.ToolChoiceRequired}` or `{Mode: sdk.ToolChoiceTool, Tool: name}` to force a call126- one `Generate` per step; the caller runs the returned `ToolCalls` and decides how many steps to take127- a call's arguments are `sdk.ToolArguments`; decode with `Unmarshal`, never assume a `map[string]any`; `Valid()` false means answer the model with an error result instead of running the tool128- a tool's result is a `sdk.ToolResultPart` whose `Result` is `sdk.TextOutput` or `sdk.JSONOutput`; the replayed assistant message keeps the reasoning parts and each part's `ProviderMetadata`129130When streaming with tools, the stream emits tool input construction parts and one `StreamToolCallPart` per completed call.131132### Streaming133134Twilight AI streaming is channel-first and type-safe. Prefer type switches over loosely typed event parsing.135136Important expectations:137138- `Model.Stream` returns an `sdk.ModelStream`: `Parts` is the channel of `sdk.StreamPart` values, `Result()` is valid once `Parts` is drained139- `sdk.CollectStream` is the convenience path when callers do not want manual event handling140- a stream is one model call; it carries no tool execution events141142### Messages And Results143144Preserve the SDK message model and avoid backend-specific shapes leaking into public usage.145146- user, assistant, system, and tool messages should stay in SDK types147- support rich parts where relevant: text, image, file, reasoning, tool call, tool result148- keep finish reason mapping aligned with SDK constants such as `stop`, `length`, `content-filter`, and `tool-calls`149150## Common Task Patterns151152### Add A New Usage Example153154Use this structure:1551561. pick the correct provider package1572. create provider with explicit options1583. create model via `ChatModel`, `EmbeddingModel`, `GenerationModel`, or `EditModel`1594. call the top-level `sdk` function1605. show minimal but idiomatic result handling161162### Add Or Update A Provider Feature163164Check all affected layers:1651661. request mapping1672. non-streaming response mapping1683. streaming event mapping1694. finish-reason and usage mapping1705. reasoning/tool/source/file support if the backend exposes them1716. model discovery and provider health checks if endpoints exist172173### Add A Custom Provider174175Use the built-in providers as the template. A custom provider should feel identical to existing ones from the caller's perspective.176177Minimum behavior:1781791. return a provider-bound model from `ChatModel`1802. implement discovery and health-check methods1813. support `DoGenerate`1824. support `DoStream` with correct lifecycle parts183184## Documentation Rules185186When writing Twilight AI docs or README content:187188- prefer provider-agnostic phrasing first, provider-specific details second189- use Go examples, not pseudocode, unless explaining an interface contract190- keep examples small and runnable in spirit191- mention exact package paths for imports192- explain when to choose Completions vs Responses vs Codex when OpenAI is involved193- keep embeddings, tool calling, and streaming as separate concerns unless the example truly combines them194195## Terminology196197Use these terms consistently:198199- Provider: backend implementation for chat generation200- Embedding provider: backend implementation for embeddings201- Image generation provider: backend implementation for image generation202- Image edit provider: backend implementation for image editing203- Model: provider-bound chat model204- Embedding model: provider-bound embedding model205- Image generation model: provider-bound image generation model206- Image edit model: provider-bound image edit model207- Tool calling: model requests a tool invocation208- Step: one model call plus the tool calls it made; the caller assembles the assistant and tool messages209- Stream part: a typed event from the model seam (`sdk.StreamPart`), delivered by `Model.Stream`210211## Quick Checklist212213Before finishing work in this repo, verify:214215- the chosen provider package matches the intended backend capabilities216- chat, embedding, and image concerns are not mixed accidentally217- public examples use top-level `sdk` APIs unless lower-level behavior is the point218- streaming logic uses typed `StreamPart` handling219- tool-calling examples build the replayed assistant and tool messages by hand220- provider work includes health checks or model discovery behavior if the backend supports them221222## Additional Resources223224- For exported APIs, signatures, provider options, and stream/event types, see [reference.md](reference.md)