Implementation Choices

Toolang v1 is intentionally small and local-first.

Main choices

• Python for the runtime
• Typer for the CLI
• Pydantic v2 for typed internal models
• OpenAI Python SDK for the model layer
• FastAPI and Uvicorn for HTTP serving
• httpx for network access
• SQLite for local persistence
• Tree-sitter for editor support

Parser strategy

Toolang uses two parser layers:

• a runtime parser
• a Tree-sitter grammar for editor tooling

For v1, the runtime parser stays hand-written.

Config and lock formats

• toolang.toml: TOML
• toolang.lock: TOML
• .caps/index.json: JSON

TOML is preferred for human-facing configuration, and inline tables are preferred where they improve clarity.

Registry and publishing

V1 uses:

• the toolang CLI for cap management
• caps.sh as the hosted registry for searching, exploring, and scoring caps

A separate caps CLI is not part of v1.