DigitalBase API

FastAPI backend of DigitalBase (internal name: lmlight). Single source tree — the inference backend is chosen at runtime with LLM_BACKEND=ollama|vllm|sglang|none (vllm / sglang spawn and supervise their own chat/embed/vision servers via common/llm/local_engine.py; none = cloud LLM APIs only). Shipped to customers as a PyInstaller single binary built by .github/workflows/release.yml.

Run from source

cd api
uv sync                      # deps + dev group (pytest, ruff, cython, ...)
# write api/.env (python-dotenv): DATABASE_URL, JWT_SECRET, LLM_BACKEND, ... (all keys: common/config/)
uv run python main.py        # listens on API_HOST:API_PORT (default 0.0.0.0:8000)
uv run python manage.py db diff   # show pending schema ALTERs (see ../docs/migrations.md)

PostgreSQL with pgvector is required for knowledge (RAG) (DATABASE_URL). Startup creates schemas, tables and the vector extension itself; the database must already exist. Without the extension the API still starts with RAG disabled, and an admin enables it from License > RAG search enhancement once a superuser has run CREATE EXTENSION vector (see ../docs/migrations.md). The SPA build in static/ is served by the same process when present.

Layout

Conventions (short list)

• Function-first Python; classes only for state / inheritance / library requirements. One-line Japanese comments.
• LLM HTTP goes through common/llm (httpx, auth_headers()), never an SDK. Chat uses /v1/chat/completions only.
• New module → import it explicitly in the package __init__.py and add a --hidden-import in release.yml (tests/contract/test_packaging.py enforces this; Cython-compiled modules are invisible to PyInstaller).
• Tunable constants live in common/config via get_env(..., advanced=True); API datetimes use iso_utc().
• Document text comes only from common.document.extract_document (chat attachments, tools, RAG, pipelines); callers never import parsers or branch on format (tests/contract/test_document_extraction_boundary.py).
• Full principles: ../docs/CODING_PRINCIPLES.md.

Tests

Single entry point is the repo-root ./test.sh (layer definitions: ../docs/test/MATRIX.md).

../test.sh unit          # api unit+contract + app vitest (no external deps)
../test.sh api           # api unit+contract only
../test.sh integration   # tests/e2e against E2E_BASE (default http://localhost:8000); add `fast` to skip @llm
../test.sh connection    # tests/connection (mocks: ../test.sh env up demo)
../test.sh smoke         # GET sweep of every route on a running instance
uv run ruff check .      # lint / format (ruff format)

Release gate (release.yml) runs only tests/contract/test_packaging.py plus the app tsc / vite build; everything else is run manually before tagging.