Skip to content

Draft: Agentic Enablement - OKF knowledge-serving spec & three-pillar pipeline (OPEA 1.5 + SST + OKF)

David FORDEN requested to merge feat/okf-server into main

Summary

Production specification (planning artifacts — no code yet) for the OKF Server initiative: an open-source, sovereign, enterprise/government-grade service that hosts multiple OKF repositories (one per domain) from Git/S3, serves them to AI agents, and grounds RAG responses in all available data — complementary to Genie's existing dataprep/RAG pipeline.

Google's Open Knowledge Format (OKF v0.1) is a format, not a platform — it deliberately leaves hosting/serving/security/curation to the ecosystem. No multi-tenant, governed, hosted OKF serving layer exists today (OSS or commercial). This fills that gap using Genie's existing stack (4.Embedding_Model% reuse).

Design (production — flexible framework for any RAG use case, any domain, across domains)

components/okf-server/ (Node/Express) consumes + extends Genie's OPEA overlay:

  • One graph per repository (OKF_{repo_id}); the retriever is extended to fan out + RRF across the free-form GRAPH + all authorized OKF_* graphs (ChatQnA forwards the authorized graph set) so chat + agents ground in all data.
  • Repository / bundle / concept CRUD + in-app Markdown authoring (frontmatter form + body + link picker + live OKF §9 validation) + Vue 3 admin ingestion/curation UI.
  • Bundle content routes through the existing document-repository (storage + ClamAV + dataprep handoff), which is the single source of truth post-ingest (versioned); external Git/S3 origins are sync sources only — periodically checked and survived if deleted.
  • Served over REST now (MCP-ready). Behind Kong + Keycloak OIDC + per-tenant/repo/domain RBAC, PII redaction, OTel tracing, FOI-exportable audit. No raw AQL to agents; no Neo4j; permissive licenses only.

Artifacts (clean, consolidated, BMAD-interoperable)

  • Brief + decision log + research addendum — _bmad-output/planning-artifacts/briefs/brief-okf-server-2026-07-15/
  • PRD (28 FRs, enterprise/government NFRs) — _bmad-output/planning-artifacts/prds/prd-okf-server-2026-07-15/prd.md
  • Architecture — _bmad-output/planning-artifacts/prds/prd-okf-server-2026-07-15/architecture.md
  • 16 ADRs — docs/adr/okf-001..016

Key decisions (ADRs)

  • okf-001 OKF Server = components/okf-server/ Node app (NOT OPEA); consumes the OPEA overlay
  • okf-002 / okf-014 per-repository graphs (OKF_{repo_id}); repository = one OKF bundle = one domain (service-category hierarchy); ACL via chunk_labels
  • okf-003 standalone behind Kong; Keycloak OIDC terminated at Kong
  • okf-008 / okf-016 bundle content via document-repository (= single source of truth post-ingest, versioned) + external-origin management (sync-only, periodic checks, deletion-tolerant)
  • okf-012 / okf-013 multi-graph grounding (retriever fan-out + RRF; ChatQnA forwards authorized graph set) — CORE; + graph_name wiring
  • okf-015 / okf-007 in-app authoring/curation (Markdown editor + live §9 validation) + steward REST/UI
  • okf-011 no raw AQL to agents — parameterized traversal only
  • No Neo4j (any edition); ArangoDB only; permissive licenses only (NFR26)

Status

Planning only (no code). Next: epics & stories → implementation.

🤖 Generated with Claude Code

Edited by David FORDEN

Merge request reports