docs(wiki): proposal for a local wiki web interface and agent API #939
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: konairius/homelab#939
Reference in New Issue
Block a user
Plan for a web interface to the Notes wiki that runs entirely in the cluster, plus an HTTP API for agents to ask typed questions, get answers and deposit facts, as one C# solution (net10.0, MudBlazor, shelly-manager conventions) in a new repository
k.renner/wiki.kubernetes/PROPOSAL-wiki-web-api.md.Ports and adapters:
Wiki.Coreholds the domain and the port interfaces and references nothing; use cases inWiki.Application; one adapter project per external thing (Gitea note store and fact sink, llama-server embeddings, TypeSafe judge, file vector index, Anthropic answer model);Wiki.Hostis the composition root with the API and the MudBlazor UI. Every port has a contract test suite that runs against every adapter, adapters are selected by configuration and can be registered several at once, each embedding model gets its own index namespace. Next adapters (a database note store, other embedding models, a locally hosted Jev, pgvector, OpenAI-compatible answer models incl. the local llama-server) are a project and a config line.Roles: the judge port returns typed judgements with probabilities, never prose.
POST /questionsanswers in process: rank, judge, then one answer-model call over the selected paragraphs, streamed, seconds not minutes, a few cents on Sonnet; below the covered gate it returns the gap. The service makes single model calls inside a request and never runs a tool loop or edits the vault; distill, consolidate and multi-question synthesis stay Claude agents in CI or a session, which are clients of this API. Secrets via ExternalSecret into env, no OpenBao access from the pod. Health: liveness, readiness (first sync and index loaded), status with per-adapter checks that never gate readiness.Seven phases, one PR each with verification, the Python wiki-index retired after parity is proven. Grounding:
~/Notes/output/2026-09-24-wiki-web-api-groundwork.mdand2026-09-24-wiki-dotnet-groundwork.md.🤖 Generated with Claude Code
🤖 Automated review — model
claude-haiku-4-5-20251001(complexity: trivial), commit80a0ee5b1903437a82ae459f4ff362c74a106888.Summary
This proposal outlines a thoughtful plan to move the wiki from a workstation-bound Python script to a cluster-resident service with a web UI and HTTP API. The architecture is well-structured, builds on existing patterns (Authentik gates, ExternalSecret, OpenBao tokens), and honestly discusses trade-offs. The phased implementation with per-phase verification is sound. No blocking issues, but several design details need clarification during implementation.
🟡 Suggestions
Memory budget — line 74: The proposal claims the 512 Mi limit "still fits" as the index grows from ~60 MB to ~80 MB. This seems optimistic if the service now holds the full text of
wiki/,raw/, andoutput/in memory (not just vectors and metadata). The current Deployment already has 256 Mi requests and 512 Mi limits (kubernetes/apps/wiki-index/deployment.yaml:89-95). No measurement is offered for the additional overhead of caching note bodies and the link graph. Recommend: estimate memory footprint including application overhead before finalizing Phase 1, or document the assumption that lazy-loading will keep steady-state significantly below the limit.Phase 5 is unspecified — line 215: "Maintenance and browse views" has no detail, just a title. This is a shipping phase where users rely on the feature. Recommend: expand this to at least cover the same level of detail as earlier phases — which views, what endpoints they consume, verification criteria.
Slug collision handling in
/facts— line 119: The proposal states "New files cannot conflict, so no branch or PR is needed" but doesn't explain how same-day filename collisions are prevented. If two agents deposit facts with the same slug within seconds, both will generateraw/<date>-<slug>.md; the second write will overwrite the first if the Gitea API is called sequentially, or conflict if attempted in parallel. Recommend: clarify the slug collision strategy (e.g., UUID suffix, rejection on collision, check-before-write via Gitea API).HTTP status codes and error response format for
/facts— lines 117–121: The proposal lists rejection criteria (missingsource, wrongkind, etc.) but doesn't specify HTTP status codes or response schema. Is a missingsourcea 400 or 422? What does the error response body look like? Recommend: document the error response contract (status codes, JSON schema) so clients can handle rejections uniformly.Rate limiting on
/ask— line 89: The proposal mentions/askcalls TypeSafe at ~1 cent per call, but includes no rate limiting, per-user quotas, or safeguards against accidental overages. The web UI could allow a user to spam questions and rack up charges. Recommend: decide on rate limiting strategy (per-token, per-user, global cap) and document it, even if Phase 4 is where the UI gets built.Bearer token security details — line 157: The proposal mentions comparing tokens constant-time and recording identity, but doesn't discuss token rotation, expiration, compromise scenarios, or how many tokens will be active (currently one per client identity in OpenBao). Recommend: document the token lifecycle (TTL, rotation schedule, revocation) when defining the ExternalSecret in Phase 2.
Link graph consistency with
/factswrites ��� line 65: The proposal describes keeping an "inbound references" link graph derived from[[links]]andrelated:frontmatter, but doesn't guarantee how quickly the graph updates after a new fact is deposited viaPOST /facts. If the next/rankor/askcall consumes stale link metadata, search results and context ranking could miss newly added notes. Recommend: clarify the link graph update cadence (immediate, next sync, half-hourly) and whether/askwaits for a fresh graph.🟢 Nits
/api/v1/rankis kept for backward compatibility, but no sunset plan is mentioned. Consider documenting when/whether scripts will be required to migrate to the new API.dns.renner.uno/publiclabel" — this is an implementation detail; move to Phase 4 (Web UI and gate) if detailed.Tests
The proposal's phase-by-phase verification is appropriate for infrastructure. Phase 1 and 2 verification criteria are concrete and testable (body matching, commit authorship, distill processing). Phase 3 includes automated test coverage (
test_wiki_ask.pyunchanged) and production validation (recall eval), which is solid. Phase 4 and 5 lack test specifics — recommend at least covering the happy path of the UI (search, note view, login redirect) with a simple smoke test in Phase 4.Recommendation
Looks reasonable — no blocking issues; comments above are clarifications and detail work for implementation phases.
🤖 Automated review — model
CLI default(complexity: unknown), commitb3dc3f6b4c9b94b3057e2628c502cfffe16683a9.Summary
Docs-only PR adding
kubernetes/PROPOSAL-wiki-web-api.md, a design proposal for a ports-and-adapters .NET service (new repok.renner/wiki) replacing the Pythonwiki-index/wiki_ask.pystack. No code or manifests change. I cross-checked the proposal's factual claims against the currentwiki-index/wiki-embed/shelly-managermanifests already in this repo (deployment, ingress, OpenBao policy,ai-ns.yamlCNPs,shelly-managergate/CNP/image-automation) and they match: LAN-only BasicAuth setup,ainamespace CNP shape,ak-outpost-<app>-gate:9000Ingress backend pattern,build.<unix-ts>image tag convention, and the ExternalSecret/no-direct-OpenBao pattern are all accurately described. No blocking issues — this is a plan, not an implementation.🟡 Suggestions
wiki-synth(kubernetes/PROPOSAL-wiki-web-api.md:29vs.:278). The doc first states "The wiki-synth agent composes answers from those judgements" as ifwiki-synthalready exists and runs today, but Phase 5 later describes building "awiki-synthpipeline taking the question as input" as new work, and the config example (:154) treatsAgentRunner.Pipeline: wiki-synthas a Woodpecker pipeline to be added. I could not findwiki-synthanywhere in this repo (onlywiki-distill/wiki-consolidateexist underci/agents/wiki-maintenance/and.woodpecker/wiki-maintenance.yml), so it's presumably a workstation-side/manual process today, not a CI pipeline. Worth a one-line clarification that "wiki-synth" currently means an ad hoc/manual composition step and Phase 5 is what turns it into an actual Woodpecker pipeline — otherwise a reader will look for an existing pipeline that isn't there.Status/Scopeheader (seekubernetes/apps/home-assistant/PROPOSAL-mosquitto-credential-rotation.md:1-4andkubernetes/PROPOSAL-cilium-single-owner.md). This proposal skips that convention; adding a short "Status: proposal, nothing implemented" line at the top would match house style, though it's a minor omission for a doc-only change.IAgentRunner's Woodpecker adapter mechanics are unspecified (kubernetes/PROPOSAL-wiki-web-api.md:87and the API table row forPOST /api/v1/questions,:203). The doc says questions get "queued" and "returns the run id" but doesn't say how the question text is threaded into a Woodpecker pipeline trigger (pipeline variables via the CLI/API, a webhook payload field, etc.) or how the run id maps back to a Woodpecker pipeline number for pollingGET /api/v1/questions/{id}. Not a blocker for a phase-0 skeleton proposal, but worth nailing down before Phase 5 since it's the one adapter with no existing precedent in this repo (unlike Gitea/LlamaCpp/TypeSafe, which mirrorwiki-index/wiki-maintenancetoday).🟢 Nits
kubernetes/PROPOSAL-wiki-web-api.md:150— thejev-localjudge entry is explicitly commented as "illustration" in the sample config; fine as-is, just flagging that it reads briefly as if ajev.ai.svcendpoint already exists (it doesn't, per the doc's own "no locally hosted Jev today" at:86).Tests
N/A — this is a planning document, not code. The proposal itself specifies a contract-test strategy (
test/Wiki.Contracts, one suite per port run against every adapter) and per-phase verification steps, which is an appropriate and specific enough test plan for a doc at this stage.Recommendation
Looks reasonable — no blocking issues; comments above are optional.
🤖 Automated review — model
CLI default(complexity: unknown), commit12e1a6e6f077ac126171a1b84637c1b2b0541860.Summary
This is a docs-only PR: it adds
kubernetes/PROPOSAL-wiki-web-api.md, a design proposal for a .NET/Blazor replacement of the Pythonwiki-indexservice plus a new agent-facing HTTP API. No code or manifests change. I checked the proposal's factual claims against what's actually in this repo (thewiki-index/wiki-embedmanifests, theainamespace CiliumNetworkPolicy, the OpenBao policy/ExternalSecret pattern, the Authentik outpost/gate-egress pattern used byshelly-manager, and the Flux image-automation tagging scheme) and everything it asserts about current state matches the checked-out repo. No blocking issues.🟡 Suggestions
kubernetes/PROPOSAL-wiki-web-api.md:254-258vs.239-241). Phase 0 shipsWiki.Hostserving/health,/readyand/api/v1/statuswith only the skeleton (Wiki.Core+ contract suites, no adapters yet — Gitea/LlamaCpp/FileIndex land in Phase 1, line 259). But the Health Endpoints section defines/readyas "the active note store has synced at least once and the active index is loaded" (line 240), which isn't meaningful until Phase 1's adapters exist. Worth a sentence on what/readyreturns in Phase 0 (e.g. always-ready stub) so the Phase 0 verification step ("the pod Ready", line 258) doesn't quietly become a no-op check.kubernetes/PROPOSAL-wiki-web-api.md:228-230). "Egress from the pod: Gitea, wiki-embed,api.typesafe.ai:443" reads as the enumeration that "every further adapter... gets its own CNP line" builds on. The existingainamespace CNP (kubernetes/infrastructure/network-policies/ai-ns.yaml:92-99) also grantskube-dnsegress on :53, which any pod resolving hostnames needs; whoever implements the CNP for this service in Phase 0/1 will need that too even though it isn't itemized here.Embeddingsconfig example uses"Adapter": "Ollama"fore5-large(line 142), but theIEmbeddingModelport row's list of future adapters names "the qwen3 embedding variants... ONNX in-process; any OpenAI-compatible endpoint" (line 83) without naming Ollama specifically — it only appears by name in the architecture diagram's parenthetical (line 59). Not a factual error (Ollama does speak an OpenAI-compatible API), just worth aligning the wording so a reader doesn't wonder whether Ollama is its own adapter or falls under "OpenAI-compatible endpoint."Tests
N/A — this is a design proposal with no code. The document itself specifies a testing strategy (a contract-test suite per port run against every adapter,
test/Wiki.Core.Tests,Wiki.Application.Tests,Wiki.Host.Tests) which is appropriate for the architecture described and mirrors the phased verification steps at the end of the doc.Recommendation
Looks reasonable — no blocking issues; comments above are optional.