langbot-dev

name

langbot-dev

description

Develop, build, and debug the LangBot core backend and web frontend. Use when working inside the LangBot repository — backend (Python/Quart, src/langbot/pkg), the Vite/React web UI, HTTP API controllers/services, Alembic migrations, or the MCP server. Covers the dev environment (uv, pnpm), repo layout, the API auth model (user token / API key / global key), adding API endpoints, and the rule that API changes must update the MCP server and skills. Triggers on "langbot backend", "langbot dev", "langbot api", "add langbot endpoint", "langbot migration".

LangBot Core Development

This skill covers developing the LangBot core (the main repo), distinct from plugin development (see langbot-plugin-dev) and deployment (langbot-deploy).

Stack

• Backend: Python >=3.11,<4.0, deps via uv. Framework: Quart (async Flask). Serves the HTTP API + pre-built web UI on http://127.0.0.1:5300.
• Frontend (web/): Vite + React Router 7 + shadcn/ui + Tailwind, managed by pnpm. Dev server on :3000. (NOT Next.js — dev script is vite.)

Dev environment

# Backend
pip install uv
uv sync --dev
uv run main.py            # API + UI on http://127.0.0.1:5300

# Frontend (separate terminal)
cd web
cp .env.example .env
pnpm install
pnpm dev                  # http://127.0.0.1:3000 (reads VITE_API_BASE_URL)

# Lint/format hooks (CI runs the same checks)
uv run pre-commit install

First run generates data/config.yaml; DB defaults to SQLite (PostgreSQL supported). Migrations run automatically on startup.

Repo layout (key paths)

src/langbot/
├── __main__.py             # entrypoint, CLI flags (--standalone-runtime/-box/--debug)
├── pkg/
│   ├── api/
│   │   ├── http/           # Quart controllers + services
│   │   │   ├── controller/groups/   # route groups (@group.group_class)
│   │   │   └── service/             # business logic (called by controllers AND MCP)
│   │   └── mcp/            # MCP server (server.py = tools, mount.py = ASGI dispatch)
│   ├── core/               # app bootstrap, stages, task manager
│   ├── platform/ provider/ pipeline/ plugin/ box/ skill/ rag/ vector/
│   ├── command/ persistence/ storage/ config/ entity/ telemetry/
│   └── templates/config.yaml        # config template (top-level: api, system, plugin, box, space...)
├── web/                    # Vite SPA
└── docker/                 # compose deployment

HTTP API auth model

Route auth is declared per-route via AuthType in pkg/api/http/controller/group.py:

• NONE — public.
• USER_TOKEN — web UI JWT (Authorization: Bearer <jwt>).
• API_KEY — X-API-Key or Authorization: Bearer <key>.
• USER_TOKEN_OR_API_KEY — either.

API keys are verified by apikey_service.verify_api_key(), which accepts:

1. the global key from config.yaml api.global_api_key (no DB, no login, no lbk_ prefix required), then
2. web-UI keys (DB-stored, lbk_ prefix).

Route groups self-register via @group.group_class(name, path) and are discovered by importutil.import_modules_in_pkg.

Adding an API endpoint

1. Add/extend a controller in pkg/api/http/controller/groups/ and the matching service method in pkg/api/http/service/.
2. Pick the right AuthType.
3. If the endpoint should be agent-accessible, add/adjust the matching MCP tool in pkg/api/mcp/server.py and update the langbot-mcp-ops skill. API and MCP surface must stay aligned (see AGENTS.md).
4. Update docs/service-api-openapi.json if you maintain the OpenAPI overview.

Database migrations (Alembic)

Single migration set supports SQLite + PostgreSQL. Files in src/langbot/pkg/persistence/alembic/versions/.

# From project root (needs data/config.yaml)
uv run python -m langbot.pkg.persistence.alembic_runner autogenerate "description"

Standards

• All code comments/docstrings in English; user-facing strings need i18n (en_US + zh_Hans minimum, ja_JP where present).
• Consider toC and toB compatibility + security.
• Commit format: <type>(<scope>): <subject> (feat/fix/docs/refactor/...).

Tests

uv run pytest tests/unit_tests -q          # unit tests
uv run pytest tests/unit_tests/api -q      # API service tests
uv run python tests/manual/mcp_smoke.py    # MCP server e2e smoke

See also

• langbot-plugin-dev — plugin SDK / runtime development.
• langbot-testing — WebUI/e2e QA harness (bin/lbs).
• langbot-deploy — Docker/compose deployment + config.
• langbot-mcp-ops — operating the LangBot MCP server.