Development setup and API entry points

Where a change belongs#

Web provides the React/TypeScript interface, Desktop supervises processes through Electron, and the Python API provides the FastAPI HTTP/SSE boundary. The shared Runtime handles characters, personas, worlds, state, memory, prompts, and evaluation and stores data in SQLite. Sharing UI/API-independent Runtime behavior between conversations and experiments is a central design principle.

LE is a separate local execution engine in its own repository and process. Kyalulu owns character truth; LE handles inference and model management. The browser uses Kyalulu routes such as /api/le/* and does not receive LE management tokens. Future media, voice, tools, or Cloud scope in the LE architecture proposal is not evidence of released features in this public version. Separating everyday UI from technical diagnostics also follows the public PRODUCT_SPEC.

Start from the public source#

Use Python 3.11+, uv 0.12+, Node.js 20+, and pnpm 10+, and run from the repository root. The public pyprojects define a uv workspace containing the root and runtime projects. Synchronize locked dependencies while skipping installation of workspace wheels, then execute from source.

# Copy only when .env does not exist
if (!(Test-Path .env)) { Copy-Item .env.example .env }
uv sync --frozen --all-packages --all-extras --no-install-workspace
pnpm install --frozen-lockfile
uv run --no-sync --directory runtime uvicorn python.api.main:app --reload --host 127.0.0.1 --port 8000
# In another terminal, from the root
pnpm dev

--no-sync avoids another synchronization during startup. --reload above is for development, not continuous home-server operation. Configure your endpoints in .env and keep credentials out of source and Web builds. These instructions are derived from public files; this guide's creation did not include a fresh installation and execution check.

Read APIs and model configuration#

Once the API is running, use these reads to inspect the model list and Provider connectivity. They do not request reply generation.

curl.exe http://127.0.0.1:8000/api/models
curl.exe http://127.0.0.1:8000/api/providers/health
curl.exe http://127.0.0.1:8000/api/library

Streaming generation uses POST /api/chat/stream. Imports preview through POST /api/imports/preview or POST /api/imports/text/preview and commit through POST /api/imports/{preview_id}/commit. Keep preview separate from persistence and check the current commit input contract before integrating it. A specification's suggested route categories alone do not prove an endpoint exists.

models/*.yaml is the registration source of truth; SQLite is a cache. Match provider.model in LM Studio/Ollama examples to the actual server ID. OpenAI-compatible configuration uses the base URL and key in .env; do not append /chat/completions to that URL. Example model names and context_length values do not prove a model is loaded or supported. LE-served models appear automatically as le:<id> without YAML.

Validate the affected behavior#

1. Inspect the diff and identify changes to API contracts, persisted data, or presentation.
2. Run pnpm typecheck; for Web changes, use pnpm --filter web test and pnpm --filter web build.
3. For Python changes, target the affected test, for example .venv/Scripts/python.exe -m pytest tests/YOUR_TEST.py -q, using dedicated test data.
4. If conversation wiring needs checking, select Mock and record it separately from real-model inference. Mock success does not establish model quality or release acceptance.

Public documentation describes Desktop API/LE supervision, but bundling Python/LE into an installer remains incomplete. Source startup instructions are not released npm or Cloud distribution instructions. Core code uses AGPL-3.0-only; models and external cards retain their distributors' licenses. Continue to the CharacterBench guide for character evaluation or the compatibility guide for migration contracts.