Kit — Atomic Era AI Assistant

Kit is a 1950s/60s Atomic Era-themed assistant.

• Backend: FastAPI “middleware”
• Engine: Open WebUI (typically via Docker)
• Frontend: Vite + React + Tailwind

Quickstart

Want the most reliable start/verify workflow? See: DEV_QUICKSTART.md.

1) Backend (FastAPI)

Install deps:

pip install -r requirements.txt

Run the server:

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Endpoints:

• GET / health
• GET /modules/list list discovered tools
• POST /modules/run/{tool_id} run a tool
• /{proxy}/... via GET|POST /proxy/{full_path:path} to Open WebUI

2) Frontend (Vite)

cd frontend
npm install
npm run dev

Then open:

• http://localhost:5173

The dev server proxies these paths to the backend:

• /modules/* → http://localhost:8000
• /proxy/* → http://localhost:8000

Open WebUI proxy configuration

The backend proxy defaults to http://localhost:3000.

Override with:

export OPENWEBUI_BASE_URL=http://localhost:3000
export OPENWEBUI_PROXY_TIMEOUT=30

Tool/module submission contract

A Python file in app/modules/ only qualifies as a tool module if it meets the contract below.

Required exports

1. TOOL_DEFINITION (dict)

Required keys:

• id (string)
• name (string)
• description (string)
• version (string)
• ralph_loop (boolean)
• allow_network (none|read|write)
• allow_filesystem (none|read|write)
• input_schema (dict; JSON-schema-ish)

Optional keys:

• icon (string)

2. run(payload: dict) -> Any

Safety policy

• Tools marked as mock: true are rejected.
• Tools that fail validation are not discoverable/runnable.

Validate tools

Run the validator from repo root:

python scripts/validate_tools.py

Want a step-by-step guide? See: docs/MODULE_TUTORIAL.md.

Docs index + templates: docs/README.md.

Atomic Era palette

• Teal: #008080
• Tangerine: #FF8C00
• Mustard: #E1AD01
• Beige: #F1E4B7