# delapan

**The grounding engine behind context-aware AI tooling.** Capture intent, ground
every answer in a maintained knowledge base, and fill gaps from the web on demand —
**ground → grow → answer**.

delapan runs fully local (SQLite + `sqlite-vec`, no cloud, no account) or behind your
own storage via a small `Store` protocol. It ships as an MCP server, so any MCP client
(Claude Code, etc.) can use it out of the box.

## Install as a Claude Code plugin

Requires [uv](https://docs.astral.sh/uv/) (`curl -LsSf https://astral.sh/uv/install.sh | sh`).

    claude plugin marketplace add anthonysuherli/delapan
    claude plugin install delapan@delapan

First launch materializes the Python environment (via uv) and seeds a bundled
demo KB. **With zero keys configured** you can immediately run
`/delapan:projects` and `/delapan:resume` against the demo (project `delapan`,
kb `demo`). To unlock semantic search and web research on your own repos, copy
`.env.example` to `.env` in the plugin directory and set `AI_GATEWAY_API_KEY`
(plus `TAVILY_API_KEY` for `/delapan:explore`).

Skills: `/delapan:resume`, `/delapan:search`, `/delapan:explore`,
`/delapan:ingest`, `/delapan:backlog`, `/delapan:projects`, `/delapan:model`.

## Quickstart — local, no credentials

```bash
pip install "delapan[local]"

# MCP server for Claude Code / any MCP client (resume, search, explore, projects)
python -m delapan.mcp.server

# or a loopback HTTP API on 127.0.0.1 (health, projects, KG read/write,
# findings, synopsis, resume, explore-over-SSE under /api/*)
python -m delapan.api.main
```

MCP tools: **`delapan_resume`** (tap a KB → resume card), **`delapan_search`**
(semantic recall over findings), **`delapan_explore`** (gap-fill from the web,
needs LLM + Tavily keys), **`delapan_backlog`** (ranked gap/sparse queries the KB
was asked and couldn't answer), **`delapan_projects`** (cross-repo discovery).
KG co-design seam: **`delapan_propose_kg_schema`** → **`delapan_set_kg_schema`**
(draft a target ontology from the findings, then validate + persist the approved
version) and **`delapan_build_graph`** / **`delapan_get_kg_schema`** (build the
graph steered by the intent schema; compare intent vs emergent ontology).

```python
# the engine, on SQLite, with no cloud creds:
from delapan.store import get_store
from delapan.mcp.tenancy import resolve_tenant

ctx = resolve_tenant("my-repo", "main", create=True)   # tenant on the local store
store = get_store()
print(store.count_findings(ctx.kb_id))
```

The local tier stores everything in `~/.delapan/delapan.db` (override with
`DELAPAN_DB_PATH`). No Supabase, no API key, loopback-only.

> **Status:** the engine core (grounding, exploration, findings, KB/project
> persistence), the `Store` seam, the MCP server, and the local HTTP API
> (`/api/*` — mirrors the MCP surface plus KG read/write for a control-panel
> frontend) all run on SQLite today — see [Roadmap](#status--roadmap).

## What's inside

| Capability | Module |
|---|---|
| **Coverage-banded grounding** — score how well the KB covers a query | `core/agent/` |
| **Gap-fill exploration** — plan → search → crawl → extract → merge | `core/exploration/` |
| **Write-time resolution** — ADD/UPDATE/NOOP/SUPERSEDE a candidate finding against its KB before persisting; nothing is ever deleted, only retired (bi-temporal `valid_from`/`invalidated_at`/`superseded_by`) | `core/memory/` |
| **Knowledge graph** — entities + relations over findings | `core/knowledge_graph/` |
| **Canvas surface** — `/canvas/search` (SSE: ephemeral web candidates + grounded streamed answer) and `/canvas/keep` (resolver-gated persistence returning ADD/UPDATE/NOOP/SUPERSEDE events) | `delapan/api/routes_canvas.py` + `delapan/core/canvas/` |
| **Pluggable storage** — `Store` protocol; ships SQLite, plus a Supabase/pgvector backend | `store/` |
| **MCP server** | `mcp/` |
| **Plugin launcher** — uv-run wrapper; materializes the environment on first run and starts the MCP server | `scripts/mcp-server.sh` |
| **Claude Code skills** — seven skills backing the `/delapan:*` slash commands (resume, search, explore, ingest, backlog, projects, model) | `skills/` |
| **Bundled demo KB** — seeded on first local server start so `/delapan:projects` + `/delapan:resume` work with zero keys | `data/demo.db` |
| **First-run onboarding** — KB-not-found guidance card + demo-KB seeding | `delapan/mcp/onboarding.py` |
| **Public `/api` auth** — config-forked bearer auth (Supabase JWT) + beta gate for the hosted tier; `auth: none` keeps the local tier byte-identical | `delapan/api/auth.py` |
| **Eval harness** — closed-book/production/oracle ablation, HHEM faithfulness, retrieval + verdict-calibration metrics, paired stats, reproducible run artifacts (`python -m evals run`); benchmark adapters for watsonxDocsQA + MultiHop-RAG (python -m evals.adapters.<name>) | `evals/` |

## Project tracking

Solo initiative status and prioritized backlog live in [`docs/tracking/`](docs/tracking/)
(markdown source of truth). See the [design spec](docs/superpowers/specs/2026-07-17-solo-project-tracker-design.md).

**Automatic sync**
- Local: `.git/hooks/post-commit` (installed from `.githooks/post-commit`) runs
  `scripts/tracking_sync.py` after commits that touch `docs/tracking/`.
- CI: GitHub Action `tracking-sync` mirrors on push (needs secrets
  `SUPABASE_URL` + `SUPABASE_SERVICE_ROLE_KEY`).

Manual:

```bash
uv run python scripts/tracking_sync.py --dry-run
uv run python scripts/tracking_sync.py
```

Findings, KBs, and projects are not separate submodules — that persistence lives
inside the `Store` implementations themselves (`store/sqlite.py`, `store/supabase.py`),
behind the one `Store` protocol below.

## Architecture — the storage seam

The engine **never** imports a storage client directly. It calls `get_store()`, which
returns a backend selected by `DELAPAN_BACKEND` (`local` | `cloud`, auto-detected from
creds when unset). Ship a new backend by implementing `store/base.py::Store`.

```python
from delapan.store import get_store

store = get_store()          # SQLiteStore on the local tier
findings = store.match_findings(kb_id, embedding, limit=10)
```

Every write to `findings` goes through `core/memory/persist.py::resolve_and_persist`,
not straight to `insert_findings` — a resolver decides per candidate whether it's
genuinely new, refines an existing finding, merely corroborates one, or contradicts
one, and applies that via the `Store`'s `update_finding`/`invalidate_finding`/
`supersede_finding` primitives. Set `memory.enabled: false` in `config.yaml` to fall
back to plain append-only ADD. `scripts/dedup_backfill.py` retires duplicates
already sitting in an existing KB (dry-run by default); `scripts/calibrate_bands.py`
recalibrates the coverage-band thresholds above for whichever embedding model is
active. Schema changes for this land in `migrations/` (cloud tier only — SQLite
migrates itself in-process).

The open-core distribution ships the **SQLite** backend, at parity with the cloud
Supabase/pgvector backend for both retrieval and the write-resolution path above.

## Configuration

Copy `.env.example` and fill the **local** block (the cloud block is optional
and only needed for a self-hosted multi-tenant deployment):

```bash
cp .env.example .env
```

## Development

```bash
python3.11 -m venv .venv
.venv/bin/pip install -e ".[dev,local]"
pytest && ruff check .
```

## Status & roadmap

**Working today (verified on SQLite, no cloud deps):**
- The `Store` seam — `get_store()` → `SQLiteStore`; tenancy, project listing, findings, synopsis, KG.
- The engine core — `agent` (preamble/synopsis/resume), `exploration`, `memory` (resolver + persist), `knowledge_graph` models.
- The tenancy gateway — `resolve_tenant()` resolves a local tenant through the store.
- The MCP server — `delapan_resume` / `delapan_search` / `delapan_explore` / `delapan_backlog` / `delapan_projects` / `delapan_archive` (whole package imports; all 6 tools register and run).
- `python -m delapan.api.main` → `/health` plus the `/api/*` surface: projects,
  per-KB graph read/write (nodes/edges CRUD, stats, schema), findings
  list/get/delete, synopsis, resume, explore over SSE, and **canvas search/keep** over SSE.
  CORS allows control-panel dev origins (`:5173`); `scripts/seed_demo_kb.py` seeds a
  credential-free demo KB to point a frontend at.
- **Canvas phase 1** — `/canvas/search` (streamed candidates + grounded answer) and `/canvas/keep`
  (resolver-gated persistence) landed; includes two loud-failure fixes: explore now fails the run
  on provider quota/error (Tavily HTTP 432, etc.), and synopsis rebuild routes via gateway with
  status reporting (`rebuilt`/`skipped`/`failed`).
- **Hosted-tier backend auth (build order phase 1 of [the public-release design](docs/truenorth/specs/2026-07-20-public-release-design.md))** —
  `api.auth: none | supabase` config fork; local JWT verification against `SUPABASE_JWT_SECRET`
  (`delapan/api/auth.py`), `beta_members` gate, org-scoped tenancy dependencies; slowapi rate
  limiting keyed by verified subject; an RLS audit script covering all 29 tenant tables; a
  two-user isolation acceptance test; `build_combined_app()` (`delapan/mcp/cloud_server.py`)
  serves REST `/api` beside the MCP server for a single Fly deploy. The local tier is unaffected
  (`auth: none` default).

- **Eval pipeline** — v1 ablation harness landed (spec: docs/truenorth/specs/2026-07-26-context-eval-pipeline-design.md); phase 2: LongMemEval adapter for externally comparable numbers.
- **Claude Code plugin shell** — shipped in-repo, marketplace-installable (2026-07-26): `scripts/mcp-server.sh` (uv-run launcher), seven skills under `skills/` backing the `/delapan:*` slash commands, a bundled demo KB (`data/demo.db`, project `delapan`/kb `demo`) seeded on first local start, and first-run onboarding (`delapan/mcp/onboarding.py`). Zero-key surface is `/delapan:projects` + `/delapan:resume` against the demo; `AI_GATEWAY_API_KEY` (plus `TAVILY_API_KEY`) unlocks search/explore on real repos.

**Next:**
- Public release phases 2–3: frontend auth screens, `/app` guard + waitlist gate, landing/legal
  pages, GitHub OAuth, custom SMTP, Sentry/uptime/analytics wiring, and the Fly deploy of the
  combined MCP+REST app — none of this is done yet (see the spec's build order).
- The capture HTTP route (mirror the remaining MCP-adjacent surface over FastAPI).
- Concepts, drift, deepen, bridges, monitoring, user-profile, research reports, and the broader MCP tool surface.
- Store-route or gate the remaining cloud-coupled surfaces (`userprofile`, generic `knowledge_graph/builder`) — currently `[cloud]`-gated at call-time.

LLM-backed features need keys — exploration: `TAVILY_API_KEY` + `AI_GATEWAY_API_KEY`
(the gateway covers LLM calls and embeddings; `OPENAI_API_KEY` is only the embeddings
fallback), synopsis rebuild: `ANTHROPIC_API_KEY`. Browse/tenant/persistence work without them.

## License

[AGPL-3.0-or-later](./LICENSE). Self-host freely; network-deployed modifications must
be shared under the same license. For commercial / non-AGPL licensing, contact the
maintainer.