llms.txt

# DSGo

> Go framework for building structured LLM applications with DSPy-style composable modules, type-safe signatures, and production-grade robustness.

DSGo provides a batteries-included approach to LLM orchestration in Go. Build everything from simple classifiers to complex multi-step agents with tool calling, all with zero external dependencies.

- **Repository**: https://github.com/assagman/dsgo
- **Language**: Go 1.25+
- **License**: MIT
- **Architecture**: 3-layer (Providers → Core → Modules)
- **Test Coverage**: 91.8%

## Documentation

- [README.md](README.md): Index + diagrams + tiny example
- [QUICKSTART.md](QUICKSTART.md): Step-by-step tutorials to get started in minutes
- [ARCHITECTURE.md](ARCHITECTURE.md): Diagram-first deep dive
- [DEVELOPMENT.md](DEVELOPMENT.md): Contributor workflow
- [REFERENCE.md](REFERENCE.md): Tables + links (quick reference)
- [examples/README.md](examples/README.md): Runnable examples index
- [AGENTS.md](AGENTS.md): Development guide for contributors and AI agents
- [ROADMAP.md](ROADMAP.md): Implementation status and future plans

## Core Concepts

### Signatures

Define input/output contracts for modules with type validation:

```go
sig := dsgo.NewSignature("Classify sentiment").
    AddInput("text", dsgo.FieldTypeString, "Text to classify").
    AddClassOutput("sentiment", []string{"positive", "negative", "neutral"}, "Sentiment")
```

**Field Types**: String, Int, Float, Bool, JSON, Class (enum), Image, Datetime

### Modules

High-level behaviors implementing the Module interface:

| Module | Purpose |
|--------|---------|
| Predict | Basic structured prediction |
| ChainOfThought | Step-by-step reasoning with rationale |
| ReAct | Tool-using agent (Reason + Act loop) |
| Refine | Iterative improvement (triggered by `inputs["feedback"]`) |
| BestOfN | Multi-candidate sampling with scoring (requires a scorer) |
| Program | Sequential module composition |
| Parallel | Concurrent execution with worker pool |
| ProgramOfThought | Code-first reasoning; optional local execution disabled by default |
| MultiChainComparison | DSPy-style answer synthesis from multiple attempts |

### Adapters

Handle LLM output parsing with automatic fallback:

| Adapter | Format | Use Case |
|---------|--------|----------|
| ChatAdapter | Field markers `[[ ## field ## ]]` | General purpose |
| JSONAdapter | Structured JSON with schema | APIs, structured data |
| TwoStepAdapter | Reason then extract | Complex reasoning |
| FallbackAdapter | Chains adapters | >95% success rate |

### Providers

LLM API implementations (auto-registered via init()):

- **OpenAI**: GPT-3.5, GPT-4, GPT-4 Turbo, GPT-4o
- **OpenRouter**: 100+ models (Claude, Llama, Gemini, etc.)

## Source Code

- [dsgo.go](dsgo.go): Main package with public API re-exports (300+ types)

### Core Layer (internal/core/)

- [signature.go](internal/core/signature.go): Field and Signature definitions with validation
- [lm.go](internal/core/lm.go): LM interface, Message, GenerateOptions, GenerateResult
- [module.go](internal/core/module.go): Module interface (Forward, GetSignature, Clone)
- [adapter.go](internal/core/adapter.go): Adapter implementations (Chat, JSON, TwoStep, Fallback)
- [prediction.go](internal/core/prediction.go): Prediction wrapper with metadata and diagnostics
- [history.go](internal/core/history.go): Thread-safe conversation history management
- [tool.go](internal/core/tool.go): Tool and ToolCall definitions for function calling
- [cache.go](internal/core/cache.go): LRU cache with TTL and deterministic keys
- [collector.go](internal/core/collector.go): History collectors (Memory, JSONL, Composite)
- [settings.go](internal/core/settings.go): Global configuration singleton
- [configure.go](internal/core/configure.go): Functional options for configuration

### Module Layer (internal/module/)

- [predict.go](internal/module/predict.go): Basic prediction module
- [chain_of_thought.go](internal/module/chain_of_thought.go): Reasoning with rationale extraction
- [react.go](internal/module/react.go): ReAct agent with tool calling loop
- [refine.go](internal/module/refine.go): Iterative refinement module
- [best_of_n.go](internal/module/best_of_n.go): Multi-candidate selection with scoring
- [program.go](internal/module/program.go): Module pipeline composition
- [parallel.go](internal/module/parallel.go): Concurrent execution with auto-cloning
- [program_of_thought.go](internal/module/program_of_thought.go): Code-first reasoning module
- [multi_chain_comparison.go](internal/module/multi_chain_comparison.go): DSPy-style synthesis

### Provider Layer (internal/providers/)

- [openai/lm.go](internal/providers/openai/lm.go): OpenAI API implementation
- [openrouter/lm.go](internal/providers/openrouter/lm.go): OpenRouter API implementation

### Infrastructure

- [internal/logging/logger.go](internal/logging/logger.go): Structured logging with request IDs
- [internal/mcp/client.go](internal/mcp/client.go): Model Context Protocol integration
- [internal/signature_typed/func.go](internal/signature_typed/func.go): Generic Func[I,O] type-safe wrappers (implementation; use via dsgo.Func, dsgo.NewTypedPredict, etc.)
- [internal/jsonutil/extract.go](internal/jsonutil/extract.go): JSON extraction and repair
- [internal/cost/cost.go](internal/cost/cost.go): Model pricing tables
- [internal/retry/retry.go](internal/retry/retry.go): Exponential backoff retry logic

## Examples

- [examples/codebase_analysis/main.go](examples/codebase_analysis/main.go): Comprehensive code analysis with ChainOfThought
- [examples/react_experiment/main.go](examples/react_experiment/main.go): ReAct agent with tool calling
- [examples/modules/parallel/main.go](examples/modules/parallel/main.go): Concurrent execution patterns
- [examples/project_review/main.go](examples/project_review/main.go): Multi-stage pipeline composition
- [examples/multi_chain_comparison/main.go](examples/multi_chain_comparison/main.go): Answer synthesis from multiple chains
- [examples/filesystem_mcp/main.go](examples/filesystem_mcp/main.go): ReAct agent with filesystem MCP tools

## API Quick Reference

### Creating LM Instance

```go
lm, err := dsgo.NewLM(ctx, "openai/gpt-4o-mini")
// or
lm, err := dsgo.NewLM(ctx, "openrouter/anthropic/claude-3-opus")
```

### Basic Prediction

```go
sig := dsgo.NewSignature("Task description").
    AddInput("input", dsgo.FieldTypeString, "Input description").
    AddOutput("output", dsgo.FieldTypeString, "Output description")

predictor := dsgo.NewPredict(sig, lm)
result, err := predictor.Forward(ctx, map[string]any{"input": "value"})
output := result.GetString("output")
```

### Tool-Using Agent

```go
tool := dsgo.NewTool("search", "Search the web", searchFunc).
    AddParameter("query", "string", "Search query", true)

agent := dsgo.NewReAct(sig, lm, []dsgo.Tool{*tool}).
    WithMaxIterations(10).
    WithVerbose(true)
```

### Typed API (Func[I,O])

```go
// Import only github.com/assagman/dsgo
import "github.com/assagman/dsgo"

// Define input/output structs with dsgo tags
type Input struct {
    Query string `dsgo:"input,desc=Search query"`
}

type Output struct {
    Result string `dsgo:"output,desc=Search result"`
}

// Create typed function
predictor, err := dsgo.NewTypedPredict[Input, Output](lm)
if err != nil {
    log.Fatal(err)
}

// Use with type safety
input := Input{Query: "What is Go?"}
output, err := predictor.Run(ctx, input)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Result: %s\n", output.Result)
```

**Note**: Do not import `internal/signature_typed` from applications; treat it as internal.

### Module Composition

```go
program := dsgo.NewProgram("Pipeline").
    Add(classifier).
    Add(generator).
    Add(refiner)

result, err := program.Forward(ctx, inputs)
```

### Streaming

```go
chunks, finalPred, errCh := predictor.Stream(ctx, inputs)
for chunk := range chunks {
    fmt.Print(chunk.Content)
}
result := <-finalPred
```

## Development Commands

```bash
make all        # Full validation (clean + check + lint + test-race)
make test       # Fast testing (unit + integration, no race)
make check      # Format + vet + build
make lint       # Run golangci-lint
make fmt-fix    # Auto-fix formatting
```

## Environment Variables

```bash
OPENAI_API_KEY=sk-...              # OpenAI API key
OPENROUTER_API_KEY=sk-or-...       # OpenRouter API key
DSGO_LOG=pretty                    # Logging: none, pretty, events
DSGO_LOG_COLOR=auto                  # Color: auto, always, never
DSGO_DEBUG_PARSE=1                 # Show parse attempts
DSGO_TIMEOUT=30s                   # Request timeout
DSGO_CACHE_SIZE=1000               # LRU cache size
```

## Key Design Decisions

- **Zero external dependencies**: Standard library only for core
- **Thread-safe by default**: All components safe for concurrent use
- **Builder pattern**: Fluent API for configuration
- **Adapter fallback chain**: >95% parsing success rate
- **Internal packages**: Clean public API via re-exports
- **Typed generics via dsgo only**: Typed helpers (Func[I,O], typed Predict, struct mappers) are implemented in `internal/signature_typed` and re-exported from `dsgo`; do not introduce public `typed` or `signature_typed` packages.
- **Context propagation**: Request IDs and cancellation throughout

## Optional

- [internal/mcp/transport.go](internal/mcp/transport.go): MCP HTTP/SSE/Stdio transports
- [internal/signature_typed/schema.go](internal/signature_typed/schema.go): Struct-to-signature conversion (implementation; use via dsgo.Func, dsgo.NewTypedPredict, etc.)
- [internal/core/streaming_buffer.go](internal/core/streaming_buffer.go): Thread-safe streaming buffer
- [internal/core/streaming_marker_filter.go](internal/core/streaming_marker_filter.go): Field marker filtering
- [integration/](integration/): Integration test suite with fixtures