Geppetto documentation index

Task-based index for Geppetto docs and example programs.

Sections

Terminology & Glossary
📖 Documentation
Navigation
54 sectionsv0.1
📄 Geppetto documentation index — glaze help geppetto-docs-index
geppetto-docs-index

Geppetto documentation index

Task-based index for Geppetto docs and example programs.

Topicgeppettodocumentation

Geppetto Documentation Index

Geppetto is a Go toolkit for building AI-powered applications. It provides:

  • Streaming inference with real-time token delivery
  • Tool calling that works across providers (OpenAI, Claude, Gemini, Ollama)
  • Provider-agnostic architecture — write once, switch providers via config
  • Event-driven design for building responsive UIs and debugging
  • Profile registry stack resolution (YAML + SQLite sources with read-only registry resolution)
  • Native JS API (require("geppetto")) for scripting and host embedding

Start Here (New Users)

If you're new to Geppetto, read these docs in order:

  1. Turns and Blocks — The core data model. Understand this first.
  2. Opinionated Runner API — Recommended app-facing entry point for new Go applications.
  3. Inference Engines — How inference is executed across providers.
  4. Profiles — Registry-first runtime selection and stack resolution.
  5. JS API Getting Started — Step-by-step tutorial for the JavaScript API.
  6. Streaming Tutorial — Build your first streaming command.

After that, explore based on what you need:

Core Concepts

DocWhat It Covers
Turns and BlocksThe Turn data model: Run → Turn → Block. How conversations are represented.
Opinionated Runner APIThe recommended pkg/inference/runner surface for new Go apps that already have resolved runtime input.
Inference EnginesThe Engine interface, factory pattern, and provider implementations.
ToolsDefining tools, registering them, and executing tool calls.
Events and StreamingReal-time event delivery, Watermill routing, and printers.
MiddlewaresAdding cross-cutting behavior (logging, tool execution) around inference.
JS API ReferenceExhaustive contract for require(\"geppetto\") namespaces and options.
JS API User GuidePractical composition patterns for sessions, middlewares, tools, and hooks.

Configuration and Setup

DocWhat It Covers
ProfilesRegistry-first profile model, read-only resolution flow, and migration from legacy profile maps.
EmbeddingsVector embeddings for semantic search, including caching.
Linting (turnsdatalint)Custom linter for Turn data key hygiene.

Tutorials

TutorialWhat You'll Build
Streaming Inference with ToolsA Cobra command that streams output and supports tool calling.
Event Routing and Structured LoggingMultiple event handlers with JSON logging and metrics.
Embeddings WorkflowsSemantic search with caching and batch processing.
Structured Data ExtractionExtract structured data from streaming output in real-time.
JS API Getting StartedEnd-to-end walkthrough of turns, sessions, tools, and hooks from JavaScript.
Build Scoped JavaScript Eval ToolsDetailed intern-friendly guide to pkg/inference/tools/scopedjs, runtime wiring, registration, and debugging.
Build a Streaming Tool-Loop Agent with Glazed FlagsBuild a small Glazed CLI that streams events, runs a tool loop, and keeps engine settings hidden in app bootstrap.

Playbooks

Operational step-by-step guides for common tasks:

PlaybookWhat You'll Do
Add a New ToolRegister a tool, attach to context, configure on Turn, run tool loop.
Add a New Event HandlerImplement handler, subscribe to router, parse events.
Progressive Structured DataExtract structured payloads from streaming output with filtering sinks.
Migrate to Session APIMigrate from legacy lifecycle APIs to session.Session + ExecutionHandle.
Migrate legacy profiles.yaml to registryConvert legacy profile maps to canonical registry YAML and switch to registry-first profile workflows.
Operate SQLite-backed profile registryRun profile registry with SQLite storage, plus backup/recovery and permissions guidance.
Bootstrap binary StepSettings from defaults, config, registries, and profileBuild final runtime settings by separating hidden base parsing from profile resolution.

Example Programs

These working examples are the source of truth for patterns. Run them to see Geppetto in action:

ExampleDescription
inference/Basic blocking inference without tools.
streaming-inference/Basic streaming inference without tools.
runner-simple/Smallest pkg/inference/runner blocking example.
runner-tools/pkg/inference/runner example with a function tool and tool-name filtering.
runner-streaming/pkg/inference/runner async/event-sink example.
runner-registry/pkg/inference/runner example that resolves runtime prompt metadata from a profile registry.
runner-glazed-full-flags/pkg/inference/runner example driven by full Geppetto sections and Glazed parsing.
runner-glazed-registry-flags/pkg/inference/runner example where only Glazed profile-registry flags are public and base StepSettings stay app-owned.
advanced/generic-tool-calling/Provider-agnostic low-level tool calling example.
advanced/openai-tools/Low-level OpenAI native function-calling example.
advanced/claude-tools/Low-level Claude native tool_use example.
advanced/middleware-inference/Low-level middleware and tool execution example.
citations-event-stream/Structured data extraction from streaming output.

Find examples in: geppetto/cmd/examples/

Prerequisites

  • Go 1.25+ (repository currently uses go 1.25.7)
  • Profile-backed provider configuration for your chosen provider(s), preferably in ~/.config/pinocchio/profiles.yaml and selected with --profile / --profile-registries.
  • Ollama, when using local models, running at http://localhost:11434 or at the base URL configured in the selected profile.

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                      Your Application                        │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────┐    ┌──────────┐    ┌─────────────────────────┐ │
│  │  Turn   │───▶│  Engine  │───▶│  Provider (OpenAI/...)  │ │
│  │ (Blocks)│◀───│          │◀───│                         │ │
│  └─────────┘    └────┬─────┘    └─────────────────────────┘ │
│                      │                                       │
│                      ▼                                       │
│               ┌──────────────┐                               │
│               │  Event Sink  │──▶ Router ──▶ Handlers        │
│               └──────────────┘                               │
├─────────────────────────────────────────────────────────────┤
│  Middleware: Logging │ Tools │ Validation │ Custom          │
└─────────────────────────────────────────────────────────────┘

Getting Help

  • API docs: Run go doc github.com/go-go-golems/geppetto/pkg/...
  • Examples: Study the example programs in geppetto/cmd/examples/
  • Debug: Use --print-parsed-fields to see resolved configuration

All public docs use the Turn-based architecture. Legacy conversation APIs are intentionally omitted.