61 lines
2.7 KiB
Markdown
61 lines
2.7 KiB
Markdown
# beaver-gateway
|
|
|
|
A gateway for personal agents built on the Claude Agent SDK: conversations
|
|
with a lifecycle, windows to talk through, jobs, memory hooks, and a policy
|
|
boundary - without an opinion about what the agent is for. A setup is one
|
|
`config.py` (or a package next to it) that assembles a `Gateway`; this repo
|
|
holds the primitives, [beaver-agent](https://git.kotikot.com/beaver/beaver-agent)
|
|
is a full setup built on them.
|
|
|
|
## What it gives a setup
|
|
|
|
- **agents/** - what an agent is: a Claude agent with a prompt per
|
|
conversation kind, skill sets per kind, gateway tools, a `PreToolUse`
|
|
policy; a Raycast agent for cheap fast answers.
|
|
- **backends/** - how a turn runs: the Claude Agent SDK subprocess with a
|
|
session pool, transcripts and session stores; the Raycast wire.
|
|
- **conversations/** - the model of a conversation: kinds (master, branch,
|
|
deep, job, fork), rows and windows, the inject queue with priorities,
|
|
seeds, turns, questions, closing through a distiller, master rotation,
|
|
the envelope, the in-process gateway tools.
|
|
- **jobs/** - cron, webhook and event jobs on pgqueuer, deferred injects,
|
|
the subscription budget.
|
|
- **frontends/** - the windows: Telegram (master = General, topic = branch),
|
|
markdown files in a vault, `/api` + the admin SPA, an Anthropic-compatible
|
|
`/anthropic/v1/messages`, MCP re-exposure at `/mcp/<name>`.
|
|
- **mcp/** - MCP servers a setup declares (stdio, http, python tools),
|
|
aggregated in-process and handed to agents by name.
|
|
- **vault/** - watching a directory of notes for the envelope.
|
|
- **security/** - bearer tokens, the audit log, credential redaction.
|
|
- **events/** - the in-process bus every frontend taps, and the stream
|
|
event protocol backends emit.
|
|
- **storage/** - SQLModel tables and the Postgres session store.
|
|
|
|
`config.py` defines `Gateway` and loads a setup; `app.py` builds the runtime
|
|
from it; `cli.py` is the entrypoint. Every string the gateway puts in front of
|
|
a model or a user has an English default and is overridable
|
|
(`ConversationTexts`, `TelegramTexts`).
|
|
|
|
## Run
|
|
|
|
```sh
|
|
uv sync # python
|
|
cd ui && bun install && cd .. # admin + panel SPA, built into ui/build
|
|
cp examples/config.py /config/config.py
|
|
DATABASE_URL=postgresql+psycopg://... CONFIG_PATH=/config/config.py uv run beaver-gateway
|
|
```
|
|
|
|
`examples/config.py` is the smallest setup that starts. The setup's own
|
|
secrets come from `.env` (`load_dotenv` runs before the config is executed).
|
|
|
|
## Develop
|
|
|
|
```sh
|
|
make check # ruff format --check, ruff check, ty, pytest
|
|
make fix
|
|
```
|
|
|
|
No comments in code: modules carry a one-line docstring saying what they are
|
|
for, public configuration fields carry a one-line docstring saying what they
|
|
mean; everything else is the code.
|