Architecture Overview

High‑level map of the command lifecycle, provider abstraction, and type system (~3 minutes).

---

System Map

flowchart LR
    A["User code (@command/@tool)"] --> B["Command wrapper"]
    B --> C["Config (defaults/env/overrides)"]
    B --> D["Type system (JSON Schema)"]
    B --> E["Backend adapter"]
    E --|request|--> F["Provider API"]
    F --|tool calls|--> G["Your @tool funcs"]
    F --|final answer|--> H["Structured output"]
    H --> D
    D --> I["Validated Python object"]

Key Components

• Command lifecycle: prompt → (tool loop) → finalization → typed parse → result.
• Provider abstraction: thin adapters translate a uniform request into provider‑specific APIs.
• Type system: Python annotations → JSON Schema → provider structured outputs → Python objects.
• Errors: clear separation of configuration errors vs. model/parse errors.
• Streaming: text‑only today; preview for sequence‑of‑objects.

Code References

• Backends: openai.py, anthropic.py, gemini.py, ollama.py
• Type system: types.py (schema), command.py (parsing)
• Contracts: tool.py (require/ensure)

See detailed pages for diagrams and deeper explanations.