aigo

README

aigo

中文说明

aigo is an agent-native Go SDK for multimodal media generation. Describe work as a lightweight workflow graph, route it to 30+ execution engines, and get structured results with error classification, retry hints, and progress callbacks.

Architecture

Agent (LLM / code)
  │
  ▼
AgentTask ──► BuildGraph() ──► workflow.Graph (DAG)
                                    │
              ┌─────────┬──────────┼──────────┬──────────┐
              ▼          ▼          ▼          ▼          ▼
        engine/kling  engine/luma  engine/fal  ...   engine/comfyui
              │          │          │                     │
              ▼          ▼          ▼                     ▼
         Kling API   Luma API   Fal API             ComfyUI WS

Engines

Image Generation

Engine	Backend	Env Var
aliyun	Alibaba Cloud DashScope (Qwen, Wan, Z-Image)	DASHSCOPE_API_KEY
openai	OpenAI DALL-E 3	OPENAI_API_KEY
google	Google Imagen	GOOGLE_API_KEY
flux	Black Forest Labs FLUX	BFL_API_KEY
stability	Stability AI (SD3, Ultra, Core)	STABILITY_API_KEY
ideogram	Ideogram	IDEOGRAM_API_KEY
recraft	Recraft V3	RECRAFT_API_KEY
midjourney	Midjourney (via GoAPI)	GOAPI_KEY
jimeng	Jimeng (Volcengine)	JIMENG_API_KEY
liblib	LibLibAI (HMAC-SHA1 auth)	LIBLIB_ACCESS_KEY / LIBLIB_SECRET_KEY
ark	Volcengine Ark	ARK_API_KEY

Video Generation

Engine	Backend	Env Var
kling	Kling AI (v1/v1.5/v2/v2.1)	KLING_API_KEY
hailuo	Hailuo / MiniMax Video	HAILUO_API_KEY
luma	Luma Dream Machine	LUMA_API_KEY
runway	Runway Gen-3/Gen-4	RUNWAY_API_KEY
pika	Pika Labs	PIKA_API_KEY
hedra	Hedra (talking head video)	HEDRA_API_KEY

Audio / Music

Engine	Backend	Env Var
elevenlabs	ElevenLabs TTS	ELEVENLABS_API_KEY
minimax	MiniMax TTS & Music	MINIMAX_API_KEY
suno	Suno Music Generation	SUNO_API_KEY
volcvoice	Volcengine Speech	VOLC_SPEECH_ACCESS_TOKEN

3D Generation

Engine	Backend	Env Var
meshy	Meshy (text/image to 3D)	MESHY_API_KEY

Multi-Modal Understanding

Engine	Backend	Env Var
gemini	Google Gemini (vision + text)	GEMINI_API_KEY
gpt4o	OpenAI GPT-4o Vision	OPENAI_API_KEY

Multi-Backend / Gateway

Engine	Backend	Env Var
newapi	Multi-route gateway (OpenAI, Kling, Jimeng, Sora, Qwen, Gemini)	NEWAPI_API_KEY
openrouter	OpenRouter (multi-provider routing)	OPENROUTER_API_KEY
fal	Fal.ai (generic model runner)	FAL_KEY
replicate	Replicate (generic model runner)	REPLICATE_API_TOKEN
comfydeploy	ComfyDeploy (hosted ComfyUI)	COMFYDEPLOY_API_TOKEN
comfyui	ComfyUI server (WebSocket)	COMFY_CLOUD_API_KEY
runninghub	RunningHub (ComfyUI cloud)	RH_API_KEY

Embedding

Engine	Backend	Env Var
embed/openai	OpenAI Embeddings	OPENAI_API_KEY
embed/gemini	Google Gemini Embeddings	GEMINI_API_KEY
embed/aliyun	DashScope Embeddings (text + multimodal)	DASHSCOPE_API_KEY
embed/jina	Jina Embeddings	JINA_API_KEY
embed/voyage	Voyage AI Embeddings	VOYAGE_API_KEY

Install

go get github.com/godeps/aigo

Quick Start

Simple prompt

client := aigo.NewClient()

_ = client.RegisterEngine("img", aliyun.New(aliyun.Config{
    Model: aliyun.ModelQwenImage,
}))

result, err := client.ExecutePrompt(ctx, "img", "A shiba inu riding a vintage motorcycle")
fmt.Println(result.Value)   // URL or data URI
fmt.Println(result.Kind)    // aigo.OutputURL, OutputDataURI, etc.
fmt.Println(result.Engine)  // "img"
fmt.Println(result.Elapsed) // execution duration

Rich Result type

Every execution method returns aigo.Result:

type Result struct {
    Value    string         // raw output (URL, data URI, JSON, etc.)
    Kind     OutputKind     // authoritative classification
    Engine   string         // which engine produced this
    Elapsed  time.Duration  // wall-clock execution time
    Metadata map[string]any // engine-specific data (optional)
}

fmt.Println(result) // Result implements String(), prints Value

Structured task

result, err := client.ExecuteTask(ctx, "video", aigo.AgentTask{
    Prompt:   "Turn this product scene into a short ad",
    Duration: 2,
    Structured: &aigo.AgentTaskStructured{
        VideoSize: "1280*720",
        ImageSize: "1024*1024",
    },
    References: []aigo.ReferenceAsset{
        {Type: aigo.ReferenceTypeVideo, URL: "https://example.com/input.mp4"},
        {Type: aigo.ReferenceTypeImage, URL: "https://example.com/style.png"},
    },
})

TTS (text-to-speech)

result, err := client.ExecuteTask(ctx, "tts", aigo.AgentTask{
    Prompt: "Welcome to our product launch event",
    TTS: &aigo.TTSOptions{
        Voice:        "zhiyan",
        LanguageType: "zh",
    },
})

Voice design

result, err := client.ExecuteTask(ctx, "vd", aigo.AgentTask{
    Prompt: "design a voice",
    VoiceDesign: &aigo.VoiceDesignOptions{
        VoicePrompt:   "A warm, friendly female voice",
        PreviewText:   "Hello, welcome!",
        TargetModel:   "cosyvoice-v2",
        PreferredName: "custom-voice-01",
    },
})

Agent-Native Features

Structured errors with retry classification

Errors from all engines are classified so agents can make retry decisions:

import "github.com/godeps/aigo/engine/aigoerr"

_, err := client.ExecutePrompt(ctx, "img", "...")
if aigoerr.IsRetryable(err) {
    // safe to retry (429, 5xx, timeout)
}

code, ok := aigoerr.GetCode(err)
// aigoerr.CodeRateLimit, CodeServerError, CodeInvalidInput, etc.

var ae *aigoerr.Error
if errors.As(err, &ae) {
    fmt.Println(ae.StatusCode)  // original HTTP status
    fmt.Println(ae.RetryAfter)  // parsed Retry-After header
}

JSON Schema tool definitions

Register aigo tools with any agent framework (OpenAI, Anthropic, LangChain, Vercel AI SDK):

import "github.com/godeps/aigo/tooldef"

tools := tooldef.AllTools()
// generate_image, generate_video, generate_3d, text_to_speech,
// design_voice, edit_image, edit_video, transcribe_audio, generate_music

Engine registry

Centralized engine registration, lookup, and capability-based discovery:

import "github.com/godeps/aigo/engine"

reg := engine.NewRegistry()
reg.Register("kling", engine.Entry{
    Name:   "kling",
    Engine: klingEngine,
    ConfigSchemaFunc:   kling.ConfigSchema,
    ModelsByCapability: kling.ModelsByCapability,
})

// Find all engines that can generate video
videoEngines := reg.FindByCapability("video")

// Get all models grouped by engine and capability
allModels := reg.AllModels()

Engine capability discovery

Query what engines can do — for dynamic tool selection:

cap, _ := client.EngineCapabilities("aliyun-img")
// cap.MediaTypes  → ["image"]
// cap.Models      → ["qwen-image"]
// cap.SupportsSync, cap.SupportsPoll

// Find all engines that handle video:
videoEngines := client.AvailableFor("video")

Progress reporting

Monitor long-running tasks:

result, err := client.Execute(ctx, "video", graph, aigo.WithProgress(func(e aigo.ProgressEvent) {
    fmt.Printf("[%s] elapsed=%s\n", e.Phase, e.Elapsed)
    // Phase: "submitted", "completed"
}))

Result caching

Cache results to avoid redundant API calls:

import "github.com/godeps/aigo/engine"

cached := engine.WithCache(myEngine, 10*time.Minute, 100) // TTL + max entries
// Identical workflow graphs return cached results

HTTP retry & rate limiting

Built-in HTTP transports for resilient API calls:

import "github.com/godeps/aigo/engine/httpx"

// Auto-retry on 429/5xx with exponential backoff
retryClient := httpx.NewRetryClient(httpx.RetryOptions{
    MaxRetries: 3,
    BaseDelay:  time.Second,
})

// Token bucket rate limiting
rateLimitedClient := httpx.NewRateLimitedClient(10, 20, 30*time.Second) // 10 RPS, burst 20

Middleware

Add cross-cutting concerns (logging, retry, timing):

client.Use(aigo.WithLogging(os.Stderr))
client.Use(aigo.WithRetry(3)) // retry retryable errors up to 3 times

Pipeline chaining

Chain multi-step workflows where each step feeds the next:

p := aigo.NewPipeline("img", aigo.AgentTask{Prompt: "a cat"}).
    Then(func(prev aigo.Result) (aigo.AgentTask, string) {
        return aigo.AgentTask{
            Prompt:     "animate this image",
            References: []aigo.ReferenceAsset{{Type: aigo.ReferenceTypeImage, URL: prev.Value}},
        }, "video"
    })

results, err := client.ExecutePipeline(ctx, p)
// results[0] = image result, results[1] = video result

DryRun estimation

Check what would happen without executing:

dr, err := client.DryRun("video", aigo.AgentTask{Prompt: "..."})
// dr.WillPoll       — whether the engine will poll
// dr.EstimatedTime  — human-readable time estimate
// dr.Warnings       — potential issues

Auto-routing with selector

Let the LLM inside your agent choose the engine:

result, err := client.ExecuteTaskAuto(ctx, selector, aigo.AgentTask{
    Prompt:   "make a 2 second product video",
    Duration: 2,
})
// result.Engine       — which engine was selected
// result.Reason       — why it was selected
// result.Output.Value — the generation result

Fallback across engines

Try multiple engines in order; first success wins:

result, err := client.ExecuteWithFallback(ctx, []string{"primary", "backup"}, graph)
// result.Engine       — which engine succeeded
// result.Output.Value — the result
// result.Skipped      — engines that failed (with errors)

Async execution

Non-blocking execution via channel:

ch := client.ExecuteAsync(ctx, "video", graph)
// ... do other work ...
ar := <-ch
if ar.Err != nil { ... }
fmt.Println(ar.Result.Value)

Low-Level API

If your agent already emits workflow graphs, call Execute directly:

graph := workflow.Graph{
    "1": {
        ClassType: "CLIPTextEncode",
        Inputs:    map[string]any{"text": "A cinematic lighthouse in a storm"},
    },
    "2": {
        ClassType: "EmptyLatentImage",
        Inputs:    map[string]any{"width": 1536, "height": 1024},
    },
}

result, err := client.Execute(ctx, "img", graph)

Internal Packages

Package	Purpose
workflow	Workflow graph types and validation
workflow/resolve	Graph resolution (prompt extraction, option helpers, link following)
engine/poll	Unified polling with backoff, progress callbacks, and status mapping
engine/httpx	HTTP client defaults, retry transport, rate limiting, file upload
engine/aigoerr	Structured error classification for agent retry logic
engine/embed	Embedding engine implementations (OpenAI, Gemini, Jina, Voyage, Aliyun)
tooldef	JSON Schema tool definitions for agent frameworks

Examples

# Alibaba Cloud
go run ./examples/aliyun_qwen_image
go run ./examples/aliyun_wan_image
go run ./examples/aliyun_zimage
go run ./examples/aliyun_wan_t2v
go run ./examples/aliyun_wan_r2v
go run ./examples/aliyun_wan_videoedit
go run ./examples/aliyun_qwen_tts
go run ./examples/aliyun_qwen_voice_design

# New API gateway
go run ./examples/newapi_image
go run ./examples/newapi_speech
go run ./examples/newapi_video

# Auto-routing
go run ./examples/agent_auto_router

Notes

• Alibaba Cloud result URLs are temporary OSS links. Persist them immediately.
• All async engines support WaitForCompletion mode for synchronous use and Resume() for reconnecting to running tasks.
• All engines use unified API key resolution via engine.ResolveKey — configure via struct field or environment variable.

Documentation

Index

• Constants
• Variables
• func BuildGraph(task AgentTask) workflow.Graph
• type AgentTask
• type AgentTaskStructured
• type AsyncResult
• type Client
  • func NewClient(opts ...ClientOption) *Client
  • func (c *Client) AvailableFor(mediaType string) []string
  • func (c *Client) DryRun(engineName string, task AgentTask) (engine.DryRunResult, error)
  • func (c *Client) EngineCapabilities(name string) (engine.Capability, error)
  • func (c *Client) EngineNames() []string
  • func (c *Client) Execute(ctx context.Context, engineName string, graph workflow.Graph, ...) (Result, error)
  • func (c *Client) ExecuteAsync(ctx context.Context, engineName string, graph workflow.Graph) <-chan AsyncResult
  • func (c *Client) ExecutePipeline(ctx context.Context, p *Pipeline) ([]Result, error)
  • func (c *Client) ExecutePrompt(ctx context.Context, engineName string, prompt string) (Result, error)
  • func (c *Client) ExecutePromptAuto(ctx context.Context, selector Selector, prompt string) (RoutedResult, error)
  • func (c *Client) ExecuteTask(ctx context.Context, engineName string, task AgentTask, opts ...ExecuteOption) (Result, error)
  • func (c *Client) ExecuteTaskAuto(ctx context.Context, selector Selector, task AgentTask) (RoutedResult, error)
  • func (c *Client) ExecuteTaskWithFallback(ctx context.Context, engines []string, task AgentTask, opts ...ExecuteOption) (FallbackResult, error)
  • func (c *Client) ExecuteWithFallback(ctx context.Context, engines []string, graph workflow.Graph, ...) (FallbackResult, error)
  • func (c *Client) RecoverPending() ([]TaskRecord, error)
  • func (c *Client) RegisterEngine(name string, e engine.Engine) error
  • func (c *Client) Resume(ctx context.Context, taskID string) (Result, error)
  • func (c *Client) Submit(ctx context.Context, engineName string, graph workflow.Graph, ...) (string, error)
  • func (c *Client) Use(mw ...Middleware)
• type ClientOption
  • func WithDefaultStore() (ClientOption, error)
  • func WithStore(s TaskStore) ClientOption
• type ExecuteOption
  • func WithProgress(fn func(ProgressEvent)) ExecuteOption
• type FallbackError
  • func (e FallbackError) Error() string
  • func (e FallbackError) Unwrap() error
• type FallbackResult
• type FileTaskStore
  • func DefaultFileTaskStore() (*FileTaskStore, error)
  • func NewFileTaskStore(path string) (*FileTaskStore, error)
  • func (s *FileTaskStore) All() ([]TaskRecord, error)
  • func (s *FileTaskStore) Delete(id string) error
  • func (s *FileTaskStore) Load(id string) (TaskRecord, error)
  • func (s *FileTaskStore) Purge(maxAge time.Duration) error
  • func (s *FileTaskStore) Save(record TaskRecord) error
• type Middleware
  • func WithLogging(w io.Writer) Middleware
  • func WithRetry(maxRetries int) Middleware
• type MusicOptions
• type OutputKind
  • func InterpretOutputKind(s string) OutputKind
• type Pipeline
  • func NewPipeline(engineName string, task AgentTask) *Pipeline
  • func (p *Pipeline) Then(fn PipelineStep) *Pipeline
• type PipelineStep
• type ProgressEvent
• type ReferenceAsset
• type ReferenceType
• type Result
  • func (r Result) String() string
• type RoutedResult
• type Selection
• type Selector
• type TTSOptions
• type TaskRecord
• type TaskStore
• type VoiceDesignOptions

Constants

const (
	OutputUnknown   = engine.OutputUnknown
	OutputURL       = engine.OutputURL
	OutputDataURI   = engine.OutputDataURI
	OutputJSON      = engine.OutputJSON
	OutputPlainText = engine.OutputPlainText
)

const (
	TaskStatusPending   = "pending"
	TaskStatusCompleted = "completed"
	TaskStatusFailed    = "failed"
)

TaskStatus constants.

Variables

var (
	ErrEngineNil       = errors.New("aigo: engine is nil")
	ErrEngineExists    = errors.New("aigo: engine already registered")
	ErrEngineNotFound  = errors.New("aigo: engine not found")
	ErrEngineNameEmpty = errors.New("aigo: engine name is empty")
)

var (
	ErrStoreNotConfigured = errors.New("aigo: task store not configured")
	ErrTaskNotFound       = errors.New("aigo: task not found")
	ErrResumeNotSupported = errors.New("aigo: engine does not support resume")
)

Functions

func BuildGraph

func BuildGraph(task AgentTask) workflow.Graph

BuildGraph compiles a high-level agent task into the SDK's workflow graph format.

Types

type AgentTask

type AgentTask struct {
	Prompt         string
	NegativePrompt string
	Width          int
	Height         int
	Size           string
	Duration       int
	Watermark      *bool
	References     []ReferenceAsset

	TTS         *TTSOptions
	VoiceDesign *VoiceDesignOptions
	Music       *MusicOptions

	// Structured groups image/video options separately for finer control.
	Structured *AgentTaskStructured
}

AgentTask is a graph-free request shape for agents.

type AgentTaskStructured

type AgentTaskStructured struct {
	ImageSize        string
	ImageWatermark   *bool
	VideoDuration    int
	VideoSize        string
	VideoWatermark   *bool
	VideoAspectRatio string
	VideoResolution  string // "480P", "720P", "1080P"
	VideoAudio       *bool
}

AgentTaskStructured 将图像与视频选项分组；便于扩展而无需继续增大 AgentTask 扁平字段。

type AsyncResult

type AsyncResult struct {
	Result Result
	Err    error
}

AsyncResult delivers an asynchronous execution outcome.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client routes a workflow graph to a registered execution engine.

func NewClient

func NewClient(opts ...ClientOption) *Client

NewClient creates a new SDK client.

func (*Client) AvailableFor

func (c *Client) AvailableFor(mediaType string) []string

AvailableFor returns registered engine names whose capabilities include the given media type. Engines that do not implement Describer are included (assumed capable).

func (*Client) DryRun

func (c *Client) DryRun(engineName string, task AgentTask) (engine.DryRunResult, error)

DryRun checks what would happen without actually executing the task. Returns an estimation if the engine implements DryRunner; otherwise returns a basic result based on Describer capabilities.

func (*Client) EngineCapabilities

func (c *Client) EngineCapabilities(name string) (engine.Capability, error)

EngineCapabilities returns the capabilities of a registered engine. If the engine does not implement Describer, an empty Capability is returned.

func (*Client) EngineNames

func (c *Client) EngineNames() []string

EngineNames returns registered engine names in deterministic order.

func (*Client) Execute

func (c *Client) Execute(ctx context.Context, engineName string, graph workflow.Graph, opts ...ExecuteOption) (Result, error)

Execute dispatches the graph to the named engine.

func (*Client) ExecuteAsync

func (c *Client) ExecuteAsync(ctx context.Context, engineName string, graph workflow.Graph) <-chan AsyncResult

ExecuteAsync runs Execute in a goroutine and delivers the result on the returned channel. The channel is closed after sending exactly one value. Cancelling ctx stops the work.

func (*Client) ExecutePipeline

func (c *Client) ExecutePipeline(ctx context.Context, p *Pipeline) ([]Result, error)

ExecutePipeline runs each step in sequence, feeding results forward.

func (*Client) ExecutePrompt

func (c *Client) ExecutePrompt(ctx context.Context, engineName string, prompt string) (Result, error)

ExecutePrompt runs the simplest agent request: a single prompt.

func (*Client) ExecutePromptAuto

func (c *Client) ExecutePromptAuto(ctx context.Context, selector Selector, prompt string) (RoutedResult, error)

ExecutePromptAuto lets a selector choose the engine for a prompt-driven request.

func (*Client) ExecuteTask

func (c *Client) ExecuteTask(ctx context.Context, engineName string, task AgentTask, opts ...ExecuteOption) (Result, error)

ExecuteTask converts an agent task into a workflow graph and routes it to the target engine.

func (*Client) ExecuteTaskAuto

func (c *Client) ExecuteTaskAuto(ctx context.Context, selector Selector, task AgentTask) (RoutedResult, error)

ExecuteTaskAuto lets a selector choose the engine for a structured agent task.

func (*Client) ExecuteTaskWithFallback

func (c *Client) ExecuteTaskWithFallback(ctx context.Context, engines []string, task AgentTask, opts ...ExecuteOption) (FallbackResult, error)

ExecuteTaskWithFallback is the AgentTask variant of ExecuteWithFallback.

func (*Client) ExecuteWithFallback

func (c *Client) ExecuteWithFallback(ctx context.Context, engines []string, graph workflow.Graph, opts ...ExecuteOption) (FallbackResult, error)

ExecuteWithFallback tries each engine in order; the first success wins. All engines that fail are recorded in FallbackResult.Skipped.

func (*Client) RecoverPending

func (c *Client) RecoverPending() ([]TaskRecord, error)

RecoverPending returns all tasks that are still pending (not completed or failed). Callers should iterate and call Resume for each.

func (*Client) RegisterEngine

func (c *Client) RegisterEngine(name string, e engine.Engine) error

RegisterEngine registers an engine under a logical name.

func (*Client) Resume

func (c *Client) Resume(ctx context.Context, taskID string) (Result, error)

Resume polls a previously submitted async task to completion. The taskID is the aigo-side ID returned by Submit.

func (*Client) Submit

func (c *Client) Submit(ctx context.Context, engineName string, graph workflow.Graph, opts ...ExecuteOption) (string, error)

Submit executes the graph and persists the task for crash recovery. If the engine completes synchronously, the result is stored as completed and an empty task ID is returned. If the engine returns a remote task ID (WaitForCompletion=false), the record is stored as pending and the aigo-side task ID is returned for later Resume.

func (*Client) Use

func (c *Client) Use(mw ...Middleware)

Use appends middleware that wraps every engine on each Execute call. Middleware is applied in the order added (first added = outermost wrapper).

type ClientOption

type ClientOption func(*Client)

ClientOption configures the Client at construction time.

func WithDefaultStore

func WithDefaultStore() (ClientOption, error)

WithDefaultStore attaches a FileTaskStore at .aigo/tasks.json (current working directory). Returns an error if the store directory cannot be created.

func WithStore

func WithStore(s TaskStore) ClientOption

WithStore attaches a TaskStore for async task persistence and crash recovery.

type ExecuteOption

type ExecuteOption func(*executeConfig)

ExecuteOption configures optional Execute behavior.

func WithProgress

func WithProgress(fn func(ProgressEvent)) ExecuteOption

WithProgress registers a callback for execution progress events.

type FallbackError

type FallbackError struct {
	Engine string
	Err    error
}

FallbackError records a single engine failure during fallback execution.

func (FallbackError) Error

func (e FallbackError) Error() string

func (FallbackError) Unwrap

func (e FallbackError) Unwrap() error

type FallbackResult

type FallbackResult struct {
	Engine  string
	Output  Result
	Skipped []FallbackError
}

FallbackResult is the outcome of a fallback-enabled execution.

type FileTaskStore

type FileTaskStore struct {
	// contains filtered or unexported fields
}

FileTaskStore implements TaskStore using a single JSON file. It uses sync.Mutex for in-process safety and flock for cross-process safety.

func DefaultFileTaskStore

func DefaultFileTaskStore() (*FileTaskStore, error)

DefaultFileTaskStore creates a file-backed task store at .aigo/tasks.json relative to the current working directory.

func NewFileTaskStore

func NewFileTaskStore(path string) (*FileTaskStore, error)

NewFileTaskStore creates a file-backed task store at the given path.

func (*FileTaskStore) All

func (s *FileTaskStore) All() ([]TaskRecord, error)

func (*FileTaskStore) Delete

func (s *FileTaskStore) Delete(id string) error

func (*FileTaskStore) Load

func (s *FileTaskStore) Load(id string) (TaskRecord, error)

func (*FileTaskStore) Purge

func (s *FileTaskStore) Purge(maxAge time.Duration) error

Purge removes completed and failed records older than maxAge.

func (*FileTaskStore) Save

func (s *FileTaskStore) Save(record TaskRecord) error

type Middleware

type Middleware func(name string, next engine.Engine) engine.Engine

Middleware wraps an engine to add cross-cutting behavior (logging, timing, retry, etc.).

func WithLogging

func WithLogging(w io.Writer) Middleware

WithLogging returns middleware that logs engine calls to the given writer.

func WithRetry

func WithRetry(maxRetries int) Middleware

WithRetry returns middleware that retries on retryable errors up to maxRetries times.

type MusicOptions

type MusicOptions struct {
	Lyrics          string
	IsInstrumental  *bool
	LyricsOptimizer *bool
	OutputFormat    string // "url" or "hex"
	SampleRate      int
	Bitrate         int
	Format          string // "mp3", "wav", "flac"
}

MusicOptions groups music generation parameters.

type OutputKind

type OutputKind = engine.OutputKind

OutputKind is an alias for engine.OutputKind.

func InterpretOutputKind

func InterpretOutputKind(s string) OutputKind

InterpretOutputKind 根据内容前缀做轻量分类；任务 id、纯数字等会落在 OutputPlainText。

type Pipeline

type Pipeline struct {
	// contains filtered or unexported fields
}

Pipeline chains multiple engine executions where each step's input depends on the previous output.

func NewPipeline

func NewPipeline(engineName string, task AgentTask) *Pipeline

NewPipeline starts a pipeline with an initial engine and task.

func (*Pipeline) Then

func (p *Pipeline) Then(fn PipelineStep) *Pipeline

Then appends a step that transforms the previous result into the next task.

type PipelineStep

type PipelineStep func(prev Result) (AgentTask, string)

PipelineStep transforms a previous result into the next task and target engine.

type ProgressEvent

type ProgressEvent struct {
	Phase   string        // "submitted", "polling", "completed"
	Attempt int           // poll attempt number (0 for non-polling phases)
	Elapsed time.Duration // wall-clock time since execution start
}

ProgressEvent reports execution progress to the caller.

type ReferenceAsset

type ReferenceAsset struct {
	Type ReferenceType
	URL  string
}

ReferenceAsset describes an externally reachable media input.

type ReferenceType

type ReferenceType string

ReferenceType identifies the kind of remote asset to attach to an agent task.

const (
	ReferenceTypeImage ReferenceType = "image"
	ReferenceTypeVideo ReferenceType = "video"
)

type Result

type Result struct {
	Value    string         // Raw output from the engine.
	Kind     OutputKind     // Authoritative classification from the engine.
	Engine   string         // Name of the engine that produced the result.
	Elapsed  time.Duration  // Wall-clock execution time.
	Metadata map[string]any // Engine-specific data (optional).
}

Result is the public outcome of every Client execution method.

func (Result) String

func (r Result) String() string

String returns the raw output value, allowing fmt.Sprint(result) to work naturally.

type RoutedResult

type RoutedResult struct {
	Engine string
	Reason string
	Output Result
}

RoutedResult is the result of a selector-driven execution.

type Selection

type Selection struct {
	Engine string
	Reason string
}

Selection is the selector's routing decision.

type Selector

type Selector interface {
	SelectEngine(ctx context.Context, task AgentTask, engines []string) (Selection, error)
}

Selector decides which registered engine should handle a task.

type TTSOptions

type TTSOptions struct {
	Voice                string
	LanguageType         string
	Instructions         string
	OptimizeInstructions *bool
}

TTSOptions groups text-to-speech parameters.

type TaskRecord

type TaskRecord struct {
	ID         string     `json:"id"`
	EngineName string     `json:"engine"`
	RemoteID   string     `json:"remote_id"`
	Status     string     `json:"status"`
	CreatedAt  time.Time  `json:"created_at"`
	UpdatedAt  time.Time  `json:"updated_at"`
	ResultVal  string     `json:"result_value,omitempty"`
	ResultKind OutputKind `json:"result_kind,omitempty"`
	ErrMsg     string     `json:"error,omitempty"`
}

TaskRecord represents a persisted async task.

type TaskStore

type TaskStore interface {
	Save(record TaskRecord) error
	Load(id string) (TaskRecord, error)
	All() ([]TaskRecord, error)
	Delete(id string) error
}

TaskStore persists async task records for crash recovery.

type VoiceDesignOptions

type VoiceDesignOptions struct {
	VoicePrompt    string
	PreviewText    string
	TargetModel    string
	PreferredName  string
	Language       string
	SampleRate     int
	ResponseFormat string
	OmitPreview    bool
}

VoiceDesignOptions groups voice design parameters.