The Framework

The Framework is a Python library for building applications around a persistent AI agent. It supplies the parts that are easy to get wrong repeatedly: one durable conversation, a supervised agent worker, plugin and specialist-agent lifecycle, authenticated HTTP/WebSocket connections, and versioned web interfaces. You supply the agent's identity, instructions, application services, security policy and user experience.

You can use it for a local desktop companion, a private agent with tools and memory, or another agent application whose browser and backend need to survive worker restarts without losing the conversation. It is a library, not a hosted agent service. The included starter is an editable application that shows the pieces working together; you are free to build a different frontend or none at all.

The PyPI distribution is named b4pt0r-the-framework. Python code imports the_framework, and the template command is the-framework. Python 3.12 or newer is required. The examples below describe the 0.2 composition API in this checkout; until 0.2 is published, run them using the checkout's uv sync instructions below. The published package may still have the older API.

To install the published package in a virtual environment:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install b4pt0r-the-framework

The Python wheel includes the framework and the editable starter template, but not a prebuilt browser UI or Playwright's Chromium binary. Those are prepared separately when you run the starter.

What an application is made of

There is exactly one primary, durable conversation. Private specialist agents can perform bounded background work, but their sessions are not new user-facing conversations and they cannot edit the primary history directly. The server supervises workers and owns authentication and client transport; workers own inference and their own sessions; a browser client owns its local interface and device/media execution. This separation lets a client reconnect or refresh while the main conversation remains intact.

To implement agent-side tools and hooks, subclass AgentPlugin from the_framework.agent and pass that class as Plugin(agent=...). A plugin may have agent-side behavior, server-side behavior, or both. Every plugin declared at startup keeps its server routes and services until shutdown. Its binding to the agent can change live: turning off tools does not remove routes that a settings screen or safety control still uses. To remove the runtime, remove the plugin from the startup declaration and restart the server. Specialists, durable task delivery and versioned public capabilities are available when a simple plugin is not enough. More detail is in the framework guide.

Try a working application

Install uv and Node.js/npm, then from this checkout run:

uv sync
npm --prefix starter/ui ci
npm --prefix starter/ui run build
uv run playwright install chromium
uv run python -m starter

Playwright Chromium also needs its system libraries; on Linux, uv run playwright install --with-deps chromium can install them if you have the required system permissions. The starter opens a local Chromium window with chat, settings, file attachments and an editable React interface. Its server listens on loopback and authenticates the browser. You can inspect the UI and settings without model credentials; generating replies, using hosted search or embeddings, and voice features require a usable account/capabilities through codex-backend-sdk. The starter guide covers sign-in, data storage and feature-by-feature behavior.

To make an independent, editable copy, run the-framework bootstrap in the environment where you installed the package. From this checkout, prefix it with uv run:

uv run the-framework bootstrap --code-dir /path/to/my-agent-code --data-dir /path/to/my-agent-data

Both directories must be empty or absent, distinct and non-overlapping. The command copies the starter source and records the private data location; it does not install npm dependencies, build the UI or launch the app. From the new code directory, run npm --prefix starter/ui ci, npm --prefix starter/ui run build, then python -m starter in an environment with b4pt0r-the-framework installed. Change starter/application.py and starter/instructions.md first; starter/ui/ contains the editable interface. Keep the data directory private: it holds conversation history, configuration, uploads, memory and browser profiles.

Build a small application yourself

Save the following as example.py. It is a complete HTTP application; the repository also includes an expanded version with modict request/response models and a health endpoint.

from the_framework import AgentApplication, AgentSpec, Plugin, SessionPolicy, endpoint
from the_framework.server.api.endpoints import Principal


class BearerSecurity:
    async def authenticate(self, request):
        if request.headers.get("authorization") != "Bearer example-secret":
            return None
        return Principal(id="example-client", scopes=frozenset({"counter:write"}))

    async def authorize(self, principal, requirement, request):
        return requirement is None or requirement.get("scope") in principal.scopes


class Counter:
    def __init__(self):
        self.value = 0
        self.running = False

    async def start(self):
        self.running = True

    async def stop(self):
        self.running = False

    @endpoint(
        "post", "/api/v1/counter/increment",
        request={"type": "object", "properties": {"amount": {"type": "integer"}},
                 "required": ["amount"], "additionalProperties": False},
        response={"type": "object", "properties": {"value": {"type": "integer"}},
                  "required": ["value"]},
        authorization={"scope": "counter:write"},
    )
    def increment(self, amount: int):
        """Increment the application counter."""
        self.value += amount
        return {"value": self.value}


counter = Counter()
application = AgentApplication(
    name="Counter Agent",
    version="0.1",
    primary_agent=AgentSpec(
        name="assistant",
        description="The application's primary agent",
        session=SessionPolicy.durable(),
    ),
    security=BearerSecurity(),
    plugins=(Plugin(name="counter", runtime=counter),),
)
app = application.build()

Start it with:

uv run uvicorn example:app --host 127.0.0.1 --port 8000

Then, in another terminal:

curl -sS -X POST http://127.0.0.1:8000/api/v1/counter/increment \
  -H 'Authorization: Bearer example-secret' \
  -H 'Content-Type: application/json' \
  -d '{"amount": 2}'

The result is {"value":2}. The literal bearer secret is only for this loopback demonstration; use a real authentication policy for an application. The primary agent declaration alone does not create a chat API or start inference: the starter shows how to add its supervised worker and client transport. @endpoint validates request and response data and contributes an OpenAPI schema. Passing a service directly to Plugin.runtime discovers its decorated routes and manages its start()/stop() lifecycle. For a feature with several server components or dependencies on other services, return Extension declarations instead; there, endpoints="service" explicitly enables route discovery, and omitting it exposes no routes. During build, the combined dependency graph and routes are validated before services start.

For the next step, read composition and runtime for plugins, private specialists, persistent resources, security, voice and client surfaces. The starter source shows these features in one application without requiring you to adopt its UI design.

Develop and package

uv sync --extra dev
uv run pytest -q tests/application tests/agentic
uv build

The build produces a wheel and source archive in dist/. The wheel contains the typed the_framework package, runtime prompts and the editable starter template; it does not bundle Node modules or a prebuilt browser UI. The test suite includes a wheel-only import/bootstrap check outside the checkout. For UI changes, also run npm --prefix starter/ui test and npm --prefix starter/ui run build.

This repository is MIT licensed. See the changelog for version notes. Publishing to PyPI is a separate release action; building locally does not publish anything.