From 52b2ca78aed7950af27d4865aee65da781514a99 Mon Sep 17 00:00:00 2001 From: T Date: Sun, 26 Apr 2026 11:09:37 -0600 Subject: Initial work, and name change to pantograph --- docs/overview.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) (limited to 'docs/overview.md') diff --git a/docs/overview.md b/docs/overview.md index 962516d..dfc9f0f 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -1,16 +1,16 @@ -# awl — Overview +# pantograph — Overview -`awl` is a minimal coding agent built for performance, efficiency, correctness, and a small core that can be extended deliberately. +`pantograph` is a minimal coding agent built for performance, efficiency, correctness, and a small core that can be extended deliberately. ## Ethos -**Batteries optional.** A full-featured coding agent experience ships by default — but everything can be deactivated. The standard distribution includes a curated set of coding-oriented tools and settings, all of which can be turned off. Strip out every coding tool and `awl` becomes a general-purpose LLM chat client. Additional capabilities may ship in the base but remain deactivated by default, waiting to be opted into. Nothing is mandatory; everything is intentional. +**Batteries optional.** A full-featured coding agent experience ships by default — but everything can be deactivated. The standard distribution includes a curated set of coding-oriented tools and settings, all of which can be turned off. Strip out every coding tool and `pantograph` becomes a general-purpose LLM chat client. Additional capabilities may ship in the base but remain deactivated by default, waiting to be opted into. Nothing is mandatory; everything is intentional. -**Small core, deliberate extension.** The core runtime does as little as possible. Features that would be built-ins in other agents are extensions in `awl` — including the fundamental tools like `read`, `write`, `edit`, and `bash`. The extension system is the primary mechanism for adding capability. +**Small core, deliberate extension.** The core runtime does as little as possible. Features that would be built-ins in other agents are extensions in `pantograph` — including the fundamental tools like `read`, `write`, `edit`, and `bash`. The extension system is the primary mechanism for adding capability. -**Conservative provider support.** Provider integrations are careful and complete rather than broad and broken. `awl` supports Anthropic-shaped and OpenAI-shaped APIs with arbitrary base URLs. A provider integration that partially works is worse than no integration at all. +**Conservative provider support.** Provider integrations are careful and complete rather than broad and broken. `pantograph` supports Anthropic-shaped and OpenAI-shaped APIs with arbitrary base URLs. A provider integration that partially works is worse than no integration at all. -**Own your data model.** `awl` defines its own internal conversation representation and maps to/from provider wire formats. No provider's API shape is treated as canonical. This ensures that adding a new provider never requires contorting the core model. +**Own your data model.** `pantograph` defines its own internal conversation representation and maps to/from provider wire formats. No provider's API shape is treated as canonical. This ensures that adding a new provider never requires contorting the core model. **Lean on the terminal.** The TUI does not try to be a full application framework. Scrollback, selection, and search are handled by the surrounding terminal (ghostty, tmux, etc.). The TUI's job is to present output clearly and offer targeted enhancements — like expanding or collapsing tool-call blocks — by clearing and re-rendering its own output region. This keeps the TUI simple while still providing a much nicer experience than a raw CLI. @@ -32,7 +32,7 @@ ContentBlock = Text | Thinking | ToolUse | ToolResult ### Library structure -`awl` is a library first. The core agent functionality lives in `libawl`, a Zig module. The CLI is a thin consumer of the library. A C ABI build of `libawl` will be produced when the extension system needs it (for Lua interop), implemented as thin `export fn` wrappers around the Zig API. +`pantograph` is a library first. The core agent functionality lives in `libpanto`, a Zig module. The CLI is a thin consumer of the library. A C ABI build of `libpanto` will be produced when the extension system needs it (for Lua interop), implemented as thin `export fn` wrappers around the Zig API. ### Provider abstraction @@ -40,26 +40,26 @@ Providers implement a streaming interface: given a conversation, stream a respon ### Extension system -Extensions will initially be written in Lua, requiring a C ABI surface on `libawl`. Future support for shared-object extensions (Zig, Rust, C, C++) will use the same C ABI. Core tools like `read`, `write`, `edit`, and `bash` are extensions — individually disableable, included in the standard distribution but not hardcoded into the runtime. +Extensions will initially be written in Lua, requiring a C ABI surface on `libpanto`. Future support for shared-object extensions (Zig, Rust, C, C++) will use the same C ABI. Core tools like `read`, `write`, `edit`, and `bash` are extensions — individually disableable, included in the standard distribution but not hardcoded into the runtime. ### Server/proxy mode -In a future phase, `awl` will be able to run as a server exposing OpenAI-compatible and Anthropic-compatible APIs, acting as a lightweight provider router/proxy to its configured backends. This is not yet planned in detail. +In a future phase, `pantograph` will be able to run as a server exposing OpenAI-compatible and Anthropic-compatible APIs, acting as a lightweight provider router/proxy to its configured backends. This is not yet planned in detail. ## Phase Roadmap | Phase | Deliverable | Doc | |-------|-------------|-----| -| 1 | libawl — minimal chat library, OpenAI provider, streaming, minimal CLI | [phase-1.md](phase-1.md) | +| 1 | libpanto — minimal chat library, OpenAI provider, streaming, minimal CLI | [phase-1.md](phase-1.md) | | 2 | Anthropic provider — second provider, validates the abstraction | phase-2.md | | 3 | Extension API — Lua runtime, extension loading, tool registration | phase-3.md | | 4 | Conversation serialization — JSONL event log, session save/resume, crash recovery | [phase-4.md](phase-4.md) | | 5 | Core tools — read/write/edit/bash as distributable extensions | phase-5.md | | 6 | Rounded coding agent — slash commands, TOML config, extended TUI | phase-6.md | -### Phase 1: libawl +### Phase 1: libpanto -A Zig library that holds a streaming conversation with an LLM via an OpenAI-compatible API. No tools, no extensions — just chat. Ships a minimal CLI (`awl` binary) for live testing: readline, send, print streamed response, repeat. The conversation model is established with all four ContentBlock variants defined (ToolUse and ToolResult exist in the type but are never produced in this phase). +A Zig library that holds a streaming conversation with an LLM via an OpenAI-compatible API. No tools, no extensions — just chat. Ships a minimal CLI (`panto` binary) for live testing: readline, send, print streamed response, repeat. The conversation model is established with all four ContentBlock variants defined (ToolUse and ToolResult exist in the type but are never produced in this phase). ### Phase 2: Anthropic Provider @@ -67,7 +67,7 @@ A second provider implementation targeting Anthropic's API shape. Validates that ### Phase 3: Extension API -Introduces a Lua extension runtime and the extension loading mechanism. Extensions can register tools, access configuration, and participate in the agent loop. This phase also produces the C ABI build of `libawl` needed for Lua interop. Tools exist but none ship yet — the extension system is the deliverable, not the tools. +Introduces a Lua extension runtime and the extension loading mechanism. Extensions can register tools, access configuration, and participate in the agent loop. This phase also produces the C ABI build of `libpanto` needed for Lua interop. Tools exist but none ship yet — the extension system is the deliverable, not the tools. ### Phase 4: Conversation Serialization @@ -75,11 +75,11 @@ Save and resume conversations. Sessions are stored as append-only JSONL event lo ### Phase 5: Core Tools as Extensions -The fundamental coding tools — `read`, `write`, `edit`, `bash` — are implemented as extensions (initially Lua, eventually native). They live under the `std` namespace: `std.read`, `std.write`, `std.edit`, `std.bash`. The `std` package is a curated set of coding-oriented extensions — some enabled by default, some available but deactivated — embodying the "batteries optional" ethos. They ship with the standard distribution but are individually disableable. This is where `awl` becomes a functional coding agent rather than just a chat client. +The fundamental coding tools — `read`, `write`, `edit`, `bash` — are implemented as extensions (initially Lua, eventually native). They live under the `std` namespace: `std.read`, `std.write`, `std.edit`, `std.bash`. The `std` package is a curated set of coding-oriented extensions — some enabled by default, some available but deactivated — embodying the "batteries optional" ethos. They ship with the standard distribution but are individually disableable. This is where `pantograph` becomes a functional coding agent rather than just a chat client. ### Phase 6: Rounded Coding Agent -Polish and capstone features that make `awl` a well-rounded coding agent experience: +Polish and capstone features that make `pantograph` a well-rounded coding agent experience: - **Slash commands** — an extensible framework for `/`-prefixed commands (e.g., `/help`, `/model`, `/clear`) - **TOML configuration** — a config file for persistent settings (default model, enabled/disabled extensions, provider configs, system prompt templates) @@ -90,8 +90,8 @@ Polish and capstone features that make `awl` a well-rounded coding agent experie These are recorded from the initial ideas but do not yet have phase documents or detailed plans: -- **Server/proxy mode** — run `awl` as a server exposing OpenAI-compatible and Anthropic-compatible APIs, routing to configured backends +- **Server/proxy mode** — run `pantograph` as a server exposing OpenAI-compatible and Anthropic-compatible APIs, routing to configured backends - **Shared-object extensions** — extend the extension system beyond Lua to support native shared libraries via the C ABI (Zig, Rust, C, C++) - **System prompt construction framework** — opinionated system for assembling system prompts from composable parts (templates, project context, extension contributions) - **Google API provider** — native integration with Google's Gemini API (rather than their OpenAI-compatibility layer), unlocking richer capabilities specific to that API shape. Low priority compared to Anthropic and OpenAI support. -- **C ABI distribution of libawl** — `export fn` wrappers exposing libawl functionality through a C calling convention, enabling external programs to embed or build on awl from C, Rust, or other native languages. Not a separate library — the C ABI is a second interface on the same `libawl` artifact, compiled from `export fn` shims that translate between Zig types and C types. Needed eventually for shared-object extensions (Zig, Rust, C, C++) beyond Lua. +- **C ABI distribution of libpanto** — `export fn` wrappers exposing libpanto functionality through a C calling convention, enabling external programs to embed or build on pantograph from C, Rust, or other native languages. Not a separate library — the C ABI is a second interface on the same `libpanto` artifact, compiled from `export fn` shims that translate between Zig types and C types. Needed eventually for shared-object extensions (Zig, Rust, C, C++) beyond Lua. -- cgit v1.3