langdag

README

LLM Conversations as Directed Acyclic Graphs

Features • Go Library • Installation • CLI • API & SDKs • Roadmap

---

Why LangDAG?

LangDAG is a high-performance Go tool that persists LLM conversations as directed acyclic graphs. Branch from any point, explore alternative paths, and maintain full conversation history.

┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐
│  User   │────▶│   LLM   │────▶│  Tool   │────▶│   LLM   │
└─────────┘     └─────────┘     └─────────┘     └─────────┘
                    │                               │
                    └──────── conversation ─────────┘
                                 = DAG

Key insight: A conversation is a DAG—it just grows incrementally.

---

Features

Feature	Description
⚡ Performance	Pure Go, ~1ms overhead, single static binary, zero runtime deps
🌊 Native Streaming	SSE streaming with real-time token delivery
🌳 Conversation Forking	Branch from any node, explore alternative paths
🏷️ Node Aliases	Human-readable names for any node
🔄 Auto Retry	Exponential backoff for transient LLM failures
💾 Persistent Storage	SQLite with WAL mode, full history replay
🔧 Tool Use	First-class tool definitions with tool_use/tool_result flows
🌐 Multi-Provider	Canonical model routing across Anthropic, OpenAI, Gemini, Grok, OpenRouter, Ollama, Azure, Vertex AI, and Bedrock deployments

---

Use as a Go Library

LangDAG is available as an importable Go package for building AI agent applications with persistent conversation storage.

go get langdag.com/langdag

Basic Usage

import "langdag.com/langdag"

client, err := langdag.New(langdag.Config{
    StoragePath: "./agent.db",
    APIKeys: map[string]string{
        "anthropic": os.Getenv("ANTHROPIC_API_KEY"),
    },
})
if err != nil {
    log.Fatal(err)
}
defer client.Close()

// Start a new conversation
result, err := client.Prompt(ctx, "What is LangDAG?",
    langdag.WithModel("claude-opus-4-6"),
)
// Stream the response
for chunk := range result.Stream {
    if chunk.Done {
        fmt.Printf("\n[saved as node %s]\n", chunk.NodeID)
    } else {
        fmt.Print(chunk.Content)
    }
}

// Continue the conversation from a specific node
result2, err := client.PromptFrom(ctx, result.NodeID, "Tell me more")

Deployment-Aware Routing

client, err := langdag.New(langdag.Config{
    Deployments: map[string]langdag.DeploymentConfig{
        "openai-direct": {APIKey: os.Getenv("OPENAI_API_KEY")},
        "openrouter":    {APIKey: os.Getenv("OPENROUTER_API_KEY")},
    },
    RoutingPolicy: &langdag.RoutingPolicy{
        Providers: map[string][]langdag.RoutingStage{
            "openai": {{
                Deployments: []langdag.DeploymentChoice{
                    {DeploymentID: "openai-direct", Weight: 80},
                    {DeploymentID: "openrouter", Weight: 20},
                },
                Retries: 1,
            }},
        },
    },
})

result, err := client.Prompt(ctx, "Review this change",
    langdag.WithModel("openai/gpt-4.1-2025-04-14"),
)

The request targets a canonical model ID. LangDAG resolves it to an eligible deployment offering, passes the deployment's native model ID to the adapter, and records served identity, normalized usage, pricing snapshot, and provider exact cost metadata when available. Provider and model routing rules are scoped, so unrelated models continue to use automatic eligible deployment resolution. Set RoutingPolicy.Default only when you intentionally want an advanced global baseline for every unmatched model.

Config Options

Field	Description
StoragePath	Path to SQLite database file
APIKeys	Map of provider name to API key ("anthropic", "openai", "gemini", "grok")
Provider	Default provider name (anthropic, openai, gemini, grok)
ModelCatalog	Deployment-aware catalog used for canonical model resolution
RemoteModelCatalog	Explicit opt-in to fetch the latest published catalog at startup
Deployments	Routeable deployment credentials, base URLs, cloud settings, and Azure model mappings
RoutingPolicy	Weighted deployment stages by default, provider, or exact canonical model
Routing	Deprecated provider-keyed routing rules
FallbackOrder	Deprecated provider fallback order
RetryConfig	Retry settings (max retries, base/max delay)

Available Methods

• client.Prompt(ctx, message, opts...) — Start a new conversation
• client.PromptFrom(ctx, nodeID, message, opts...) — Continue from an existing node
• client.ListConversations(ctx) — List all root conversation nodes
• client.GetNode(ctx, nodeID) — Get a single node by ID
• client.GetSubtree(ctx, nodeID) — Get full subtree rooted at a node
• client.GetAncestors(ctx, nodeID) — Get ancestor chain up to root
• client.DeleteNode(ctx, nodeID) — Delete a node and its subtree

Testing with NewWithDeps

Use NewWithDeps to inject custom storage and provider implementations — no API keys required in tests:

client := langdag.NewWithDeps(tempStorage, mockProvider)

Model Catalog Refresh

LangDAG ships an embedded catalog generated from the published origin/model-catalog branch. The generated internal/models/catalog.json file is committed so Go module release tags include the data used by go:embed. Maintainers can update it manually with ./scripts/sync-model-catalog.sh.

Prompt/runtime routing uses the embedded catalog by default. It does not read ~/.config/langdag/model_catalog.json implicitly, so a stale user cache cannot override the published catalog snapshot. Apps that want the freshest catalog at startup can set RemoteModelCatalog; apps that want a one-shot fetch can call LoadRemoteModelCatalog or RefreshModelCatalogCache with no cache path and pass the returned catalog via Config.ModelCatalog. langdag models --update can fetch https://langdag.com/model-catalog/v1/catalog.json for the current command. LANGDAG_MODEL_CATALOG_URL / LANGDAG_MODEL_CATALOG_TIMEOUT can override CLI fetches.

---

Installation

From Source

git clone https://github.com/aduermael/langdag.git
cd langdag
go build -o langdag ./cmd/langdag

Go Install

go install github.com/aduermael/langdag/cmd/langdag@latest

---

CLI

# Set your API key
export ANTHROPIC_API_KEY="your-api-key"

# Start a new conversation
langdag prompt "What is a DAG?"

# Interactive mode
langdag prompt

# List all conversations (root nodes)
langdag ls

# View a conversation tree
langdag show a1b2

# Continue from a specific node
langdag prompt a1b2 "Tell me more"

# Delete a conversation
langdag rm a1b2

Every conversation is a DAG that grows as you chat—and you can branch from any point:

Node history:
├─ 1a2b [human]: What is a DAG?
│  ├─ 5e6f [assistant]: A DAG is a directed graph with no cycles...
│  │  └─ 9c0d [human]: Can you give me an example?
│  │     └─ 2f34 [assistant]: Sure! Think of a family tree...
│  └─ 7a8b [assistant]: Let me explain with a diagram...
│     └─ 4e5f [human]: That's clearer, thanks!
└─ ...

CLI Reference

# Prompt commands
langdag prompt "message"               # Start new conversation
langdag prompt -m <model> "message"    # Use a specific model
langdag prompt -s "system" "message"   # With system prompt
langdag prompt <node-id> "message"     # Continue from node
langdag prompt                         # Interactive mode (new tree)
langdag prompt <node-id>               # Interactive mode from node

# Node management
langdag ls                             # List root nodes
langdag show <id>                      # Show node tree
langdag rm <id>                        # Delete node and subtree

---

API & SDKs

LangDAG can run as a REST API server:

langdag serve --port 8080

Endpoints:

• POST /prompt — Start new conversation tree
• POST /nodes/{id}/prompt — Continue from existing node
• GET /nodes — List root nodes
• GET /nodes/{id} — Get a single node
• GET /nodes/{id}/tree — Get full tree from node
• DELETE /nodes/{id} — Delete node and subtree
• PUT /nodes/{id}/aliases/{alias} — Create node alias
• GET /nodes/{id}/aliases — List node aliases
• DELETE /aliases/{alias} — Delete alias

See the OpenAPI specification for full API documentation.

Python

pip install langdag

from langdag import LangDAGClient

client = LangDAGClient()

# Start a conversation
node = client.prompt("What is a DAG?")
print(node.content)

# Continue from any node
node2 = node.prompt("Tell me more")

# Stream responses
for event in client.prompt("Explain graphs", stream=True):
    if event.content:
        print(event.content, end="")

Go

go get github.com/langdag/langdag-go

client := langdag.NewClient("http://localhost:8080")

// Start a conversation
node, _ := client.Prompt(ctx, "What is a DAG?")
fmt.Println(node.Content)

// Continue from any node
node2, _ := node.Prompt(ctx, "Tell me more")

// Stream responses
stream, _ := client.PromptStream(ctx, "Explain graphs")
for event := range stream.Events() {
    fmt.Print(event.Content)
}
result, _ := stream.Node()

TypeScript

npm install langdag

import { LangDAGClient } from 'langdag';

const client = new LangDAGClient();

// Start a conversation
const node = await client.prompt('What is a DAG?');
console.log(node.content);

// Continue from any node
const node2 = await node.prompt('Tell me more');

// Stream responses
const stream = await client.promptStream('Explain graphs');
for await (const event of stream.events()) {
  process.stdout.write(event.content);
}
const result = await stream.node();

See the SDK source code and example projects for more details.

---

Architecture

┌──────────────────────────────────────────────────────────┐
│                      CLI / API                           │
├──────────────────────────────────────────────────────────┤
│                 Conversation Manager                     │
├──────────────────────────────────────────────────────────┤
│                      Provider Layer                      │
│   ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌──────┐ │
│   │ Anthropic │  │  OpenAI   │  │  Gemini   │  │ Grok │ │
│   └───────────┘  └───────────┘  └───────────┘  └──────┘ │
├──────────────────────────────────────────────────────────┤
│                   Storage Layer                          │
│   ┌───────────┐                                          │
│   │  SQLite   │                                          │
│   └───────────┘                                          │
└──────────────────────────────────────────────────────────┘

---

Documentation

• Design Document — Deep dive into architecture
• API Reference — REST & WebSocket APIs
• Examples — Sample workflows
• Migrate from LangGraph — Import your existing LangGraph conversations into LangDAG

---

Roadmap

• SQLite storage with WAL mode
• Anthropic, OpenAI, Gemini providers with streaming
• Node-centric API (prompt, branch, tree)
• Tree visualization
• REST API with SSE streaming
• Python, Go, TypeScript SDKs
• Node aliases
• Automatic retry with exponential backoff
• Tool use (WithTools, tool_use/tool_result flows)
• Grok (xAI) provider
• Model catalog with pricing and context windows
• LangGraph migration tooling (JSON + SQLite import)
• Prompt caching (Anthropic)
• Web UI

---

Comparison

	LangDAG	LangGraph	Langfuse
Focus	Conversation tree store	State machine orchestration	Observability
Language	Go	Python	TypeScript
Performance	~1ms overhead	Higher latency	N/A
Conversation model	Native DAG	Manual	Trace-based
Deployment	Single binary	Python runtime	SaaS/Self-host

---

Contributing

Contributions are welcome! Please read the Contributing Guide first.

# Run tests
go test ./...

# Build
go build -o langdag ./cmd/langdag

---

License

MIT License - see LICENSE for details.

---

_{Built with ❤️ in Go}

Documentation

Overview

Package langdag provides a Go library for managing AI agent conversations with tree-structured storage and multi-provider LLM routing.

Index

• Constants
• Variables
• type APIProtocolV1
• type AnthropicConfig
• type AzureOpenAIConfig
• type BedrockConfig
• type CapabilitySetV1
• type CapabilityState
• type CatalogDiagnosticV1
• type CatalogLoadOptions
• type CatalogLoadResult
  • func LoadModelCatalogWithOptions(opts CatalogLoadOptions) (*CatalogLoadResult, error)
  • func LoadRuntimeModelCatalog() (*CatalogLoadResult, error)
  • func LoadRuntimeModelCatalogWithOptions(opts CatalogLoadOptions) (*CatalogLoadResult, error)
• type CatalogRefreshOptions
• type CatalogRefreshResult
  • func LoadRemoteModelCatalog(ctx context.Context, opts CatalogRefreshOptions) (*CatalogRefreshResult, error)
  • func RefreshModelCatalogCache(ctx context.Context, opts CatalogRefreshOptions) (*CatalogRefreshResult, error)
• type CatalogSource
• type CatalogV1
• type Client
  • func New(cfg Config) (*Client, error)
  • func NewWithDeps(store Storage, prov Provider) *Client
  • func (c *Client) Close() error
  • func (c *Client) DeleteNode(ctx context.Context, id string) error
  • func (c *Client) GetAncestors(ctx context.Context, id string) ([]*types.Node, error)
  • func (c *Client) GetNode(ctx context.Context, id string) (*types.Node, error)
  • func (c *Client) GetSubtree(ctx context.Context, id string) ([]*types.Node, error)
  • func (c *Client) ListConversations(ctx context.Context) ([]*types.Node, error)
  • func (c *Client) Prompt(ctx context.Context, message string, opts ...PromptOption) (*PromptResult, error)
  • func (c *Client) PromptFrom(ctx context.Context, nodeID string, message string, opts ...PromptOption) (*PromptResult, error)
  • func (c *Client) Provider() Provider
  • func (c *Client) Storage() Storage
• type CompiledCatalogV1
• type Config
• type CredentialV1
• type DeploymentBindingV1
• type DeploymentChoice
• type DeploymentConfig
• type DeploymentV1
• type EnvFallbackV1
• type GeminiConfig
• type GrokConfig
• type ModelCatalog
  • func DefaultModelCatalog() (*ModelCatalog, error)
  • func FetchModelCatalog(ctx context.Context, cachePath string) (*ModelCatalog, error)
  • func LoadModelCatalog(cachePath string) (*ModelCatalog, error)
• type ModelOfferingTemplateV1
• type ModelOfferingV1
• type ModelPricing
• type ModelV1
• type NativeModelIDSource
• type OllamaConfig
• type OpenAIConfig
• type OpenRouterConfig
• type PricingStatus
• type PricingV1
• type PromptOption
  • func WithAPIProtocol(apiProtocolID string) PromptOption
  • func WithMaxOutputGroupTokens(n int) PromptOption
  • func WithMaxTokens(n int) PromptOption
  • func WithMaxTurns(n int) PromptOption
  • func WithModel(model string) PromptOption
  • func WithSystemPrompt(prompt string) PromptOption
  • func WithThink(enabled bool) PromptOption
  • func WithTools(tools []types.ToolDefinition) PromptOption
• type PromptResult
  • func (r *PromptResult) GetContent() string
  • func (r *PromptResult) GetNodeID() string
• type ProvenanceV1
• type Provider
  • func WithRetry(p Provider, cfg RetryConfig) Provider
• type ProviderV1
• type RemoteModelCatalogConfig
• type ResponseCostSource
• type RetryConfig
• type RetryEvent
• type RoutingEntry
• type RoutingPolicy
• type RoutingStage
• type Storage
• type StreamChunk
• type VertexConfig

Constants

const CapabilitySupported = models.CapabilitySupported

const CapabilityUnknown = models.CapabilityUnknown

const CapabilityUnsupported = models.CapabilityUnsupported

const CatalogSourceCache = models.CatalogSourceCache

const CatalogSourceEmbedded = models.CatalogSourceEmbedded

const CatalogSourceRemote = models.CatalogSourceRemote

const CatalogV1JSONSchema = models.CatalogV1JSONSchema

const CatalogV1SchemaVersion = models.CatalogV1SchemaVersion

const DefaultRemoteCatalogURL = models.DefaultRemoteCatalogURL

const NativeModelIDCatalogKnown = models.NativeModelIDCatalogKnown

const NativeModelIDCatalogOrUser = models.NativeModelIDCatalogOrUser

const NativeModelIDDiscovered = models.NativeModelIDDiscovered

const NativeModelIDUserConfigured = models.NativeModelIDUserConfigured

const PricingFree = models.PricingFree

const PricingKnown = models.PricingKnown

const PricingPartial = models.PricingPartial

const PricingUnknown = models.PricingUnknown

const ResponseCostLocalFree = models.ResponseCostLocalFree

const ResponseCostProviderAsync = models.ResponseCostProviderAsync

const ResponseCostProviderExact = models.ResponseCostProviderExact

const ResponseCostUsageCountersOnly = models.ResponseCostUsageCountersOnly

Variables

var CatalogRefreshOptionsFromEnv = models.CatalogRefreshOptionsFromEnv

var CompileCatalogV1 = models.CompileCatalogV1

var ContextWithRetryCallback = internalprovider.ContextWithRetryCallback

ContextWithRetryCallback returns a child context that carries a per-call retry callback. This takes priority over the config-level OnRetry.

var DeploymentBindingsV1 = models.DeploymentBindingsV1

var ParseCatalogV1 = models.ParseCatalogV1

var ParseRemoteCatalogV1 = models.ParseRemoteCatalogV1

var ReferenceCatalogV1 = models.ReferenceCatalogV1

var SplitOfferingIDV1 = models.SplitOfferingIDV1

var ValidateCatalogV1 = models.ValidateCatalogV1

Types

type APIProtocolV1

type APIProtocolV1 = models.APIProtocolV1

type AnthropicConfig

type AnthropicConfig struct {
	BaseURL string
}

AnthropicConfig holds Anthropic-specific configuration.

type AzureOpenAIConfig

type AzureOpenAIConfig struct {
	Endpoint   string
	APIVersion string
	APIKey     string
}

AzureOpenAIConfig holds Azure OpenAI-specific configuration.

type BedrockConfig

type BedrockConfig struct {
	Region string
}

BedrockConfig holds AWS Bedrock configuration.

type CapabilitySetV1

type CapabilitySetV1 = models.CapabilitySetV1

type CapabilityState

type CapabilityState = models.CapabilityState

type CatalogDiagnosticV1

type CatalogDiagnosticV1 = models.CatalogDiagnosticV1

type CatalogLoadOptions

type CatalogLoadOptions = models.CatalogLoadOptions

type CatalogLoadResult

type CatalogLoadResult = models.CatalogLoadResult

func LoadModelCatalogWithOptions

func LoadModelCatalogWithOptions(opts CatalogLoadOptions) (*CatalogLoadResult, error)

LoadModelCatalogWithOptions loads a usable model catalog immediately, preferring a valid cache and falling back to embedded catalog data with diagnostics.

func LoadRuntimeModelCatalog

func LoadRuntimeModelCatalog() (*CatalogLoadResult, error)

LoadRuntimeModelCatalog loads the model catalog used by prompt/runtime routing from the embedded catalog generated from the published model-catalog branch.

func LoadRuntimeModelCatalogWithOptions

func LoadRuntimeModelCatalogWithOptions(opts CatalogLoadOptions) (*CatalogLoadResult, error)

LoadRuntimeModelCatalogWithOptions loads the prompt/runtime catalog with explicit load options. If opts.CachePath is empty, the embedded catalog is used and no user cache path is read implicitly.

type CatalogRefreshOptions

type CatalogRefreshOptions = models.CatalogRefreshOptions

type CatalogRefreshResult

type CatalogRefreshResult = models.CatalogRefreshResult

func LoadRemoteModelCatalog

func LoadRemoteModelCatalog(ctx context.Context, opts CatalogRefreshOptions) (*CatalogRefreshResult, error)

LoadRemoteModelCatalog fetches the published remote model catalog and validates it without reading or writing any local cache file.

func RefreshModelCatalogCache

func RefreshModelCatalogCache(ctx context.Context, opts CatalogRefreshOptions) (*CatalogRefreshResult, error)

RefreshModelCatalogCache fetches the published remote catalog artifact. If opts.CachePath is non-empty, the fetched catalog replaces that cache. Invalid, stale, or partial remote data does not replace an existing cache.

type CatalogSource

type CatalogSource = models.CatalogSource

type CatalogV1

type CatalogV1 = models.CatalogV1

Deployment-aware model catalog v1 contract types.

type Client

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

Client is the main langdag client for managing AI conversations.

A Client is safe for concurrent use by multiple goroutines. The underlying storage (SQLite with WAL mode and busy_timeout) and providers (stateless HTTP clients) are themselves concurrent-safe, and each call to Prompt or PromptFrom returns an independent PromptResult with its own streaming channel.

func New

func New(cfg Config) (*Client, error)

New creates a new langdag client with the given configuration.

func NewWithDeps

func NewWithDeps(store Storage, prov Provider) *Client

NewWithDeps creates a Client from pre-built dependencies. Useful for testing or custom integrations where the caller has already constructed a Storage and Provider.

func (*Client) Close

func (c *Client) Close() error

Close releases all resources held by the client.

func (*Client) DeleteNode

func (c *Client) DeleteNode(ctx context.Context, id string) error

DeleteNode deletes a node and all its descendants.

func (*Client) GetAncestors

func (c *Client) GetAncestors(ctx context.Context, id string) ([]*types.Node, error)

GetAncestors returns all ancestors of a node (the conversation history leading to it).

func (*Client) GetNode

func (c *Client) GetNode(ctx context.Context, id string) (*types.Node, error)

GetNode returns a node by ID or ID prefix.

func (*Client) GetSubtree

func (c *Client) GetSubtree(ctx context.Context, id string) ([]*types.Node, error)

GetSubtree returns a node and all its descendants.

func (*Client) ListConversations

func (c *Client) ListConversations(ctx context.Context) ([]*types.Node, error)

ListConversations returns all root conversation nodes.

func (*Client) Prompt

func (c *Client) Prompt(ctx context.Context, message string, opts ...PromptOption) (*PromptResult, error)

Prompt starts a new conversation with the given message. Returns a PromptResult with the streaming response.

func (*Client) PromptFrom

func (c *Client) PromptFrom(ctx context.Context, nodeID string, message string, opts ...PromptOption) (*PromptResult, error)

PromptFrom continues a conversation from an existing node.

func (*Client) Provider

func (c *Client) Provider() Provider

Provider returns the underlying provider for advanced use cases.

func (*Client) Storage

func (c *Client) Storage() Storage

Storage returns the underlying storage interface for advanced use cases.

type CompiledCatalogV1

type CompiledCatalogV1 = models.CompiledCatalogV1

type Config

type Config struct {
	// StoragePath is the path to the SQLite database file.
	// Defaults to "$HOME/.config/langdag/langdag.db"
	StoragePath string

	// Provider is the default LLM provider to use.
	// Valid values: "anthropic", "openai", "gemini", "grok", "openrouter", "ollama",
	// "anthropic-vertex", "anthropic-bedrock", "openai-azure", "gemini-vertex"
	// "gemma" is accepted as an alias for "gemini".
	// Defaults to "anthropic"
	Provider string

	// APIKeys maps provider names to their API keys.
	// Keys: "anthropic", "openai", "gemini"
	APIKeys map[string]string

	// AnthropicConfig holds Anthropic-specific config (optional base URL override).
	AnthropicConfig *AnthropicConfig

	// OpenAIConfig holds OpenAI-specific config.
	OpenAIConfig *OpenAIConfig

	// GeminiConfig holds Gemini-specific config.
	GeminiConfig *GeminiConfig

	// GrokConfig holds Grok (xAI)-specific config.
	GrokConfig *GrokConfig

	// OpenRouterConfig holds OpenRouter-specific config.
	OpenRouterConfig *OpenRouterConfig

	// AzureOpenAIConfig holds Azure OpenAI-specific config.
	AzureOpenAIConfig *AzureOpenAIConfig

	// VertexConfig holds Google Vertex AI config.
	VertexConfig *VertexConfig

	// BedrockConfig holds AWS Bedrock config.
	BedrockConfig *BedrockConfig

	// OllamaConfig holds Ollama-specific config (local LLM server).
	OllamaConfig *OllamaConfig

	// ModelCatalog is the deployment-aware catalog used for canonical model
	// resolution. Defaults to the embedded catalog generated from the published
	// model-catalog branch when nil. Mutually exclusive with RemoteModelCatalog.
	ModelCatalog *ModelCatalog

	// RemoteModelCatalog, when non-nil, makes New fetch the published catalog
	// instead of using the embedded catalog. Fetch failures are returned from
	// New; no local cache file is read or written. Mutually exclusive with
	// ModelCatalog.
	RemoteModelCatalog *RemoteModelCatalogConfig

	// Deployments configures routeable deployment credentials and deployment-
	// scoped model mappings. Legacy provider-specific fields above remain
	// readable and are merged into this shape.
	Deployments map[string]DeploymentConfig

	// RoutingPolicy configures canonical-model deployment routing. Exact model
	// routes override matching provider routes. Non-matching models use
	// automatic eligible deployment resolution unless Default is explicitly set.
	RoutingPolicy *RoutingPolicy

	// Routing configures multi-provider routing (optional).
	// Deprecated: use RoutingPolicy with deployment IDs.
	Routing []RoutingEntry

	// FallbackOrder specifies provider fallback order (optional).
	// Deprecated: use RoutingPolicy with deployment IDs.
	FallbackOrder []string

	// RetryConfig configures retry behavior.
	RetryConfig *RetryConfig
}

Config holds all configuration for the langdag client.

type CredentialV1

type CredentialV1 = models.CredentialV1

type DeploymentBindingV1

type DeploymentBindingV1 = models.DeploymentBindingV1

type DeploymentChoice

type DeploymentChoice = internalprovider.DeploymentChoice

type DeploymentConfig

type DeploymentConfig struct {
	APIKey        string
	BaseURL       string
	Endpoint      string
	APIVersion    string
	ProjectID     string
	Region        string
	ModelMappings map[string]string
}

DeploymentConfig holds deployment-scoped credentials and native model mappings. Azure OpenAI uses ModelMappings to translate canonical model IDs to the caller's Azure deployment names.

type DeploymentV1

type DeploymentV1 = models.DeploymentV1

type EnvFallbackV1

type EnvFallbackV1 = models.EnvFallbackV1

type GeminiConfig

type GeminiConfig struct {
	BaseURL string
}

GeminiConfig holds Gemini-specific configuration.

type GrokConfig

type GrokConfig struct {
	BaseURL string
}

GrokConfig holds Grok (xAI)-specific configuration.

type ModelCatalog

type ModelCatalog = models.Catalog

ModelCatalog contains deployment-aware model, offering, pricing, and capability information.

func DefaultModelCatalog

func DefaultModelCatalog() (*ModelCatalog, error)

DefaultModelCatalog returns the model catalog embedded with the library. It contains model names, pricing (per 1M tokens), context window sizes, and max output tokens for all supported providers.

func FetchModelCatalog

func FetchModelCatalog(ctx context.Context, cachePath string) (*ModelCatalog, error)

FetchModelCatalog fetches the latest model catalog from official provider documentation pages (OpenAI, Anthropic, Google, xAI). This does not require any API keys.

If cachePath is non-empty, the fetched catalog is saved to that path so it can be loaded with LoadModelCatalog in future sessions.

func LoadModelCatalog

func LoadModelCatalog(cachePath string) (*ModelCatalog, error)

LoadModelCatalog loads the model catalog from a cache file, falling back to the embedded default if the file does not exist or is invalid JSON.

type ModelOfferingTemplateV1

type ModelOfferingTemplateV1 = models.ModelOfferingTemplateV1

type ModelOfferingV1

type ModelOfferingV1 = models.ModelOfferingV1

type ModelPricing

type ModelPricing = models.ModelPricing

ModelPricing contains pricing and capability information for a model.

type ModelV1

type ModelV1 = models.ModelV1

type NativeModelIDSource

type NativeModelIDSource = models.NativeModelIDSource

type OllamaConfig

type OllamaConfig struct {
	// BaseURL is the Ollama server address (e.g., "http://localhost:11434" or "http://100.93.184.1:11434")
	BaseURL string
}

OllamaConfig holds Ollama-specific configuration. Ollama is a local LLM server that provides an OpenAI-compatible API.

type OpenAIConfig

type OpenAIConfig struct {
	BaseURL string
}

OpenAIConfig holds OpenAI-specific configuration.

type OpenRouterConfig

type OpenRouterConfig struct {
	BaseURL string
}

OpenRouterConfig holds OpenRouter-specific configuration.

type PricingStatus

type PricingStatus = models.PricingStatus

type PricingV1

type PricingV1 = models.PricingV1

type PromptOption

type PromptOption func(*promptOptions)

PromptOption configures a prompt request.

func WithAPIProtocol

func WithAPIProtocol(apiProtocolID string) PromptOption

WithAPIProtocol selects a provider API surface for providers that expose multiple protocols for the same deployment, for example "openai-responses" or "openai-chat-completions".

func WithMaxOutputGroupTokens

func WithMaxOutputGroupTokens(n int) PromptOption

WithMaxOutputGroupTokens sets the maximum total output tokens across all continuation calls in an output group. When a response hits max_tokens and is continued, langdag tracks cumulative output tokens; if they exceed this budget the continuation stops. A value of 0 (the default) means 4× the per-call max_tokens.

func WithMaxTokens

func WithMaxTokens(n int) PromptOption

WithMaxTokens sets the max tokens for the response.

func WithMaxTurns

func WithMaxTurns(n int) PromptOption

WithMaxTurns sets the maximum number of LLM round-trips for a single Prompt/PromptFrom call. Since langdag does not have a built-in tool-use loop, the value is exposed on the PromptResult so the caller can decrement and check it in their own multi-turn loop. A value of 0 (the default) means unlimited.

func WithModel

func WithModel(model string) PromptOption

WithModel sets the model for the prompt.

func WithSystemPrompt

func WithSystemPrompt(prompt string) PromptOption

WithSystemPrompt sets the system prompt.

func WithThink

func WithThink(enabled bool) PromptOption

WithThink controls whether the model should use extended thinking. true = enable thinking, false = disable thinking. Omitting this option leaves the decision to the provider/model default.

func WithTools

func WithTools(tools []types.ToolDefinition) PromptOption

WithTools sets the tool definitions for the prompt. When tools are provided, the LLM may respond with tool_use content blocks.

type PromptResult

type PromptResult struct {
	// NodeID is the ID of the saved assistant node (set when streaming completes,
	// or immediately for non-streaming use when the stream is consumed).
	NodeID string

	// Content is the full response text (empty until streaming completes).
	Content string

	// Stream is the streaming channel. Range over it to receive chunks.
	// It is never nil; even for simple use cases, consumers should drain it.
	Stream <-chan StreamChunk

	// MaxTurns is the maximum number of LLM round-trips the caller should
	// allow for this conversation. 0 means unlimited. Since langdag does not
	// have a built-in tool-use loop, the caller can use this value to enforce
	// a turn budget in their own multi-turn loop.
	MaxTurns int
	// contains filtered or unexported fields
}

PromptResult holds the result of a prompt call.

The NodeID and Content fields are written by a background goroutine as the stream is consumed. Reading them directly before the stream is fully drained is a data race. Use the GetNodeID and GetContent accessor methods for concurrent-safe access at any time, or read the fields only after the Stream channel has been fully drained (closed).

func (*PromptResult) GetContent

func (r *PromptResult) GetContent() string

GetContent returns the full response content in a concurrent-safe manner. The value is only meaningful after the stream has been fully drained.

func (*PromptResult) GetNodeID

func (r *PromptResult) GetNodeID() string

GetNodeID returns the node ID in a concurrent-safe manner. The value is only meaningful after the stream has delivered a Done chunk.

type ProvenanceV1

type ProvenanceV1 = models.ProvenanceV1

type Provider

type Provider = internalprovider.Provider

Provider is the interface for LLM providers. It is re-exported here so that external consumers can use the return value of Client.Provider() without importing an internal package.

func WithRetry

func WithRetry(p Provider, cfg RetryConfig) Provider

WithRetry wraps a Provider with exponential backoff retry logic. Only transient errors (5xx, rate limits, timeouts) are retried.

type ProviderV1

type ProviderV1 = models.ProviderV1

type RemoteModelCatalogConfig

type RemoteModelCatalogConfig struct {
	Endpoint   string
	Timeout    time.Duration
	HTTPClient *http.Client
}

RemoteModelCatalogConfig configures an explicit runtime fetch of the published model catalog. Leave Endpoint empty to use DefaultRemoteCatalogURL.

type ResponseCostSource

type ResponseCostSource = models.ResponseCostSource

type RetryConfig

type RetryConfig struct {
	MaxRetries int
	BaseDelay  time.Duration
	MaxDelay   time.Duration
	// OnRetry is called before each retry wait. It may be nil.
	OnRetry func(RetryEvent)
}

RetryConfig configures retry behavior for LLM provider calls.

type RetryEvent

type RetryEvent = internalprovider.RetryEvent

RetryEvent holds information about a retry attempt.

type RoutingEntry

type RoutingEntry struct {
	Provider string
	Weight   int
	Retry    *RetryConfig
}

RoutingEntry configures a single provider entry in the routing table. Deprecated: use RoutingPolicy with deployment IDs.

type RoutingPolicy

type RoutingPolicy = internalprovider.RoutingPolicy

type RoutingStage

type RoutingStage = internalprovider.RoutingStage

type Storage

type Storage = internalstorage.Storage

Storage is the interface for persisting conversation nodes. It is re-exported here so that external consumers can use the return value of Client.Storage() without importing an internal package.

type StreamChunk

type StreamChunk struct {
	// Content is the incremental text content for this chunk.
	Content string

	// ContentBlock is set for content_done events (e.g. tool_use blocks).
	ContentBlock *types.ContentBlock

	// Done indicates the stream has completed.
	Done bool

	// Error holds any error that occurred during streaming.
	Error error

	// NodeID is set when Done=true and the assistant node has been saved to storage.
	NodeID string

	// StopReason is the reason the LLM stopped generating (e.g. "end_turn", "tool_use").
	// Set when Done=true.
	StopReason string

	Usage           *types.Usage
	ModelResolution *types.ModelResolutionMetadata
	NormalizedUsage *types.NormalizedUsage
	PricingSnapshot *types.PricingSnapshot
	ProviderCost    *types.ProviderCost
}

StreamChunk is a piece of a streaming response.

type VertexConfig

type VertexConfig struct {
	ProjectID string
	Region    string
}

VertexConfig holds Google Vertex AI configuration.