# ai-wiki-service

A self-synthesizing AI knowledge wiki (Karpathy LLM-wiki pattern). The successor to
`ai-wiki-mcp`: instead of the calling agent doing synthesis, this service does it itself.

Three parts:

- **UI** — vanilla JS/HTML, served by the server (ingest box, file tree, wikilink graph).
- **Server** — FastAPI HTTP API for the UI + a read-only FastMCP surface for external agents to
  trace the wiki. Writes only `raw/`.
- **Worker** — a LangGraph agentic loop that, on each ingested raw document, runs the import +
  synthesis process against a configured model (via the LiteLLM proxy) and commits the result.

State (job queue + LangGraph checkpoints) lives in Postgres. The wiki itself is a git repo of
markdown — one commit per import/synthesis run. A periodic lint pass is the correctness safety net;
there is no human review gate.

See `docs/plans/` for the implementation plan.

## Commands

```bash
uv sync                        # install deps
uv run pytest                  # run tests (offline; DB tests need AIWIKI_TEST_DSN)
uv run ruff check src tests    # lint
```

For the full local dev loop (rootless Postgres, env, running the server/worker, and the
manual end-to-end spikes), see `CLAUDE.md`.

## Deployment (llm-server / VM 215)

Built as one image with two entrypoints; docker-compose runs it as three services
(`ai-wiki-service-{db,server,worker}`) on the existing `app-net` bridge.

```bash
# 1. Image is built + pushed to the Gitea registry automatically by CI on merge to main
#    (.gitea/workflows/ci.yaml; bump pyproject version per PR). To build by hand instead:
#    docker build -t 192.168.10.32:3000/jhonnold/ai-wiki-service:<ver> . && docker push …

# 2. One-time host provisioning (creates + git-inits the wiki tree, seeds from live ai-wiki):
bash deploy/bootstrap.sh                       # run on VM 215

# 3. Add the three services from deploy/docker-compose.snippet.yaml into
#    ~/projects/llm-server/docker-compose.yaml, add the AIWIKI_* vars to its .env, then:
docker compose up -d ai-wiki-service-db ai-wiki-service-server ai-wiki-service-worker
```

The UI + read-only MCP are then at `http://192.168.10.40:3011/app/` and `…/mcp`. The
worker auto-synthesizes each ingested source and runs a lint pass after every
`AI_WIKI_LINT_AFTER_N` syntheses. See `.env.example` for all settings.