Phase 0+1: solution skeleton, ports, adapters, host with parity to the Python wiki-index #1

2026-09-24T10:15:13Z

claude-bot commented

2026-09-24 10:15:13 +00:00

Design: homelab kubernetes/PROPOSAL-wiki-web-api.md (PR #939).

Layout: Wiki.Core (domain, nine ports, dependency-free vault parsing), Wiki.Application (sync with hash diff and per-model backfill, coordinator, rank, status), adapters for Gitea (note store, fact sink), llama.cpp embeddings, file-backed vector index and document catalog; Wiki.Host (composition root from appsettings, /health, /ready, /api/v1/status, /rank and /webhook shape-compatible with the Python service, POST /api/v1/sync behind an API key, Authentik-header and API-key auth, MudBlazor status page), Dockerfile, Woodpecker test and release pipelines. Contract suites in test/Wiki.Contracts run against every adapter. 80 tests, warnings as errors.

Parity (phase 1 acceptance): the host run locally against Gitea and the in-cluster wiki-embed, 40 labelled queries, same commit as the Python wiki-index: hit rate @1/@5/@10/@20 = 0.425/0.85/0.875/0.95 on both; MRR 0.604 vs 0.606; 35 of 40 identical top-10 sets.

Found and fixed: Gitea reset the keep-alive TLS connection twice during the 3094-document initial sync; the Gitea adapter now retries idempotent reads with backoff and recycles pooled connections.

Not in this PR: cluster manifests (homelab repo), TypeSafe and Anthropic adapters (later phases).

🤖 Generated with Claude Code

Design: homelab `kubernetes/PROPOSAL-wiki-web-api.md` (PR #939). **Layout**: `Wiki.Core` (domain, nine ports, dependency-free vault parsing), `Wiki.Application` (sync with hash diff and per-model backfill, coordinator, rank, status), adapters for Gitea (note store, fact sink), llama.cpp embeddings, file-backed vector index and document catalog; `Wiki.Host` (composition root from `appsettings`, `/health`, `/ready`, `/api/v1/status`, `/rank` and `/webhook` shape-compatible with the Python service, `POST /api/v1/sync` behind an API key, Authentik-header and API-key auth, MudBlazor status page), Dockerfile, Woodpecker test and release pipelines. Contract suites in `test/Wiki.Contracts` run against every adapter. 80 tests, warnings as errors. **Parity** (phase 1 acceptance): the host run locally against Gitea and the in-cluster wiki-embed, 40 labelled queries, same commit as the Python wiki-index: hit rate @1/@5/@10/@20 = 0.425/0.85/0.875/0.95 on both; MRR 0.604 vs 0.606; 35 of 40 identical top-10 sets. **Found and fixed**: Gitea reset the keep-alive TLS connection twice during the 3094-document initial sync; the Gitea adapter now retries idempotent reads with backoff and recycles pooled connections. Not in this PR: cluster manifests (homelab repo), TypeSafe and Anthropic adapters (later phases). 🤖 Generated with [Claude Code](https://claude.com/claude-code)

claude-bot added 11 commits 2026-09-24 10:15:14 +00:00

core: domain model, ports, vault parsing; contract suites for note store, vector index, catalog, embeddings a26490e5e4

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

application: sync use case (hash diff, per-model embedding, backfill), coordinator, rank, status 811696da90

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

feat(llamacpp): embeddings adapter over llama-server's /v1/embeddings 2f6f56c4f0

Batches requests (default size 2, matching llama-server's limits for long
notes), sorts responses by index, and normalises vectors to unit length.
CheckAsync prefers GET /health, falling back to a one-word embed call when
the server doesn't expose it. Registers as a keyed IEmbeddingModel so
multiple models can be wired up under different names.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

feat(fileindex): file-backed vector index and document catalog adapters 019f046925

FileVectorIndex persists one binary file per model under index/ with
atomic tmp+rename writes; FileDocumentCatalog persists a single
catalog.json, rebuilding the link graph via WikiLinks.Extract on every
upsert. Both start empty and report health Ok with a reset detail if
their file on disk is corrupt, rather than crashing.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

host: composition root, health/ready/status, /rank and /webhook, auth handlers, MudBlazor status page, Dockerfile, CI pipelines af58249bc5

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Merge branch 'feat/adapter-fileindex' into feat/skeleton 65cf355dc4

Merge branch 'feat/adapter-llamacpp' into feat/skeleton 4f904f7eb3

feat(gitea): implement the Gitea note-store and fact-sink adapters f67cc7b871

INoteStore reads the vault straight from Gitea (branch HEAD, a paged
recursive tree listing, raw file reads); IFactSink appends a new raw/
file via the contents API, numbering around any path collision. Both
verified against the live gitea.renner.uno API for response shape
rather than the swagger doc.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Merge branch 'feat/adapter-gitea' into feat/skeleton 8b02986eff

host: endpoint tests; keep status-code pages off API responses; merge the three adapters 14b858bcfc

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

gitea: retry transient read failures, recycle pooled connections fba535e03a

A long sync over one keep-alive connection to Gitea behind Traefik saw a
TLS connection reset after ~1000 documents and aborted the whole run.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

claude-bot added 1 commit 2026-09-24 10:18:34 +00:00

ci: registry login as the bot (org-owned repo); allow manual test runs

ci/woodpecker/pr/test Pipeline was successful

Details

ci/woodpecker/push/test Pipeline was successful

Details

ded15eb96b

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

k.renner merged commit b48dd28b9e into main

2026-09-24 10:21:28 +00:00

k.renner deleted branch feat/skeleton

2026-09-24 10:21:28 +00:00

k.renner referenced this issue from a commit

2026-09-24 10:21:29 +00:00

Merge pull request 'Phase 0+1: solution skeleton, ports, adapters, host with parity to the Python wiki-index' (#1) from feat/skeleton into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: konairius/Wiki#1