Skip to content

BACKLOG.md

Latest commit

 

History

History
114 lines (91 loc) · 13.8 KB

BACKLOG.md

File metadata and controls

114 lines (91 loc) · 13.8 KB
Raw

Backlog — Kuber Map for FIBO

Living execution tracker. PLAN.md = design/source-of-truth; this file = what's done and what's next. Pick the top unchecked item under Immediate next to continue. Every change must pass make check.

Last updated: 2026-07-05

Status snapshot

Done

  • ✅ Repo scaffold, MIT/FOSS files, quality gates (ruff + pytest + validate + attribution/employer guard), CLAUDE.md.
  • ✅ FIBO→OKF pipeline: etl/extract.py (walks owl:Restriction blank nodes), etl/to_okf.py, etl/validate.py, etl/fibo_ns.py.
  • ✅ De-risking spike passed + ETL hardened (kebab edges, module-aware collision-free paths, namespace classification, maturity propagation). See SPIKE_RESULTS.md.
  • ✅ Deterministic extraction — best_literal() prefers en-US labels/definitions; stable relation order (is-a first, then typed). make all now reproduces the bundle byte-for-byte. Fixed make setup on fresh checkouts (setuptools flat-layout).
  • ✅ All ten FIBO domains emitted: FND, LOAN, FBC, BE, SEC, DER, IND, MD, BP, CAE + Commons (CMNS) — 3,104 concepts, 6,676 typed relations, 68 sub-domain clusters. scripts/fetch_fibo.sh sparse-checks out all ten; DOMAINS/CLUSTERS and okf.config.js cover every domain. The map now spans all of FIBO; the curated use-case cores stay the default lens.
  • ✅ Loan-Origination curation: 71 core concepts (curation/loan-origination.json) + 4 validated cross-domain bridges (curation/bridges.json, knowledge/bridges/). Tools: etl/nominate_core.py, etl/bridges.py.
  • ✅ core: wired into the bundle — to_okf.py stamps core: true on all 71 curated concepts (frontmatter + index markers); make curate = nominate + bridges + rebuild.
  • ✅ Definition-rewrite overlay — curation/definitions.json supplies learner-friendly definitions for the 7 core concepts FIBO ships with no skos:definition (each grounded in its FIBO superclass/axioms); to_okf.py applies them as definition_provenance: curated, keeps FIBO's resource: IRI, and refuses to overwrite any real FIBO definition.
  • ✅ Context-pack export (the product, etl/export_pack.py + make pack) — export/loan-origination/ with pack.json (structured RAG records), context.md (LLM-injectable grounding doc), and a self-contained okf/ slice. 71 concepts + 4 bridges, each carrying its FIBO IRI as citation + provenance on every edge/definition.
  • ✅ MCP retrieval endpoint — etl/mcp_server.py (stdlib-only MCP stdio server) + etl/retrieval.py (weighted keyword search). Tools: search_concepts, get_concept, list_bridges; every hit carries citation IRI + provenance. Reusable by the eval runner.
  • ✅ Eval harness + benchmark — eval/ with pluggable model adapter (make eval = offline mechanism check; --adapter llm = live via a user EVAL_LLM_CMD, no vendor SDK), deterministic scoring (accuracy / hallucination / auditability), every question grounded in a real pack IRI (test-enforced).
  • ✅ Value proof, five use cases + two models — grounded-vs-ungrounded benchmarks for loan (53), KYC (50), securities (54), regulatory reporting (52), derivatives (54). gpt-4o-mini: +45.3pt aggregate accuracy lift over 263 questions, 97.0% auditable, 0% grounded hallucination; corroborated on gpt-4o (157 Q across 3 domains — lift is model-robust). See SPIKE_RESULTS.md.
  • ✅ Five curated use cases — loan origination (71), KYC / beneficial ownership (58), securities (59), regulatory reporting (52, most cross-domain — 8 clusters), derivatives (60). 284 core: concepts + 19 validated cross-domain bridges, each use case with worked card examples + a context pack (export/), all spec-driven under curation/usecases/.
  • ✅ Use-case lens + card badges — the map default core spans all five use cases; a lens focuses one, cards show use-case membership. Fed by use_cases: frontmatter.
  • ✅ EDM contribution package — etl/export_bridges.py (make contrib) → contrib/ (proposal MD + RDF/Turtle for the 19 bridges).
  • ✅ Published to GitHub (public): AI-First-Community/kuber-map, reproducible via make fibo.
  • ✅ Public FOSS launch & community scaffolding — GitHub Pages live, 9-page wiki, CI gate on every PR, CODEOWNERS + SECURITY/SUPPORT/CoC, issue/PR templates, Discussions, ROADMAP.md, THIRD_PARTY_NOTICES. A separate mobile PWA (m.html) over the same knowledge. Recorded demo GIFs (scripts/record-demos.mjs) + a marketing kit (marketing/: branded flyer + launch copy). Seeded good first issues (#1–#4).

Map UI (E2): data layer + vendored frontend + FIBO app.html/graph.js shipped (core-default view, domain/maturity filters, provenance-styled bridges, IRI-citation panel, offline PWA). Verified live on desktop + mobile.

Still open: engaging EDM Council with the packaged contribution + re-modeling accepted bridges as formal owl:Restriction axioms (outward-facing — user's call); more use cases (payments/insurance/ESG — now community good first issues); per-domain lazy loading (scale optimization, fine at 3,104 nodes); SME review of the eval gold set; tech-debt (orphan review, FIBO-pin refresh doc).

Fresh-checkout setup: make setup && make fibo && make commons && make all then make check.

Immediate next (in order)

Phases 0→3 are complete and the project is publicly launched. The MLV value proof was met and exceeded (5 use cases vs 1 planned; +45.3pt vs the +15–20pt target). Remaining work is outward-facing or optional:

  1. Engage the EDM Council with the packaged bridge contribution (contrib/) — outward-facing, user's call on timing. Prep: re-model accepted bridges as formal owl:Restriction axioms once reviewers map each edge to a FIBO/Commons property (E5).
  2. More use cases — payments & settlement, insurance underwriting, ESG (spec-driven under curation/usecases/; now open as good first issues).
  3. SME review of the eval gold answers before the numbers are treated as externally authoritative.
  4. Tech-debt (E6): orphan-node review, edge-label edge cases, a documented FIBO-pin refresh process.

Epics

E1 — Complete the Loan-Origination MLV (value proof) ◀ current focus

  • Wire core: flag from curation into generated bundle (to_okf.py)
  • make curate target (nominate_core + bridges + rebuild)
  • Definition-rewrite overlay for thin-def core concepts (curation input + to_okf apply)
  • etl/export_pack.py — grounds_in closure → OKF slice + JSON + context.md
  • MCP retrieval endpoint (etl/mcp_server.py + etl/retrieval.py)
  • eval/ harness: benchmark (53 Q), grounded vs ungrounded runner, scorecard (offline; live adapter ready)
  • Ran the live eval (gpt-4o-mini via OpenAI): +39.6pt accuracy lift (45.3% → 84.9%), auditability 0% → 98.1%, grounded hallucination 0%. See SPIKE_RESULTS.md.
  • Wrote up the MLV result in SPIKE_RESULTS.md (accuracy +39.6pt, auditability 98.1%, grounded hallucination 0%)

E2 — The map UI (fork of Bodhi)

  • Data layer — scripts/okf.js build (+ make map) + okf.config.js generate js/data.js from knowledge/: 1284 nodes (71 core), 2108 edges (4 curated bridges), every edge provenance-tagged; deterministic. Handles our module-nested paths + inline-object relations (Bodhi's parser could not).
  • Vendored Bodhi frontend (Cytoscape.js + fcose libs, css/style.css, Manrope fonts, PWA icons/SW/manifest).
  • Faithful Bodhi UI — app.html/js/graph.js/css/style.css taken from the Bodhi source; FIBO is driven the way Bodhi is designed for, through okf.config.js (taxonomy/vocab/flows) + generated data.js. CSS forked from Bodhi with our additions (busy overlay, use-case lens, card badges); graph.js is forked from Bodhi and substantially extended (core/use-case filters, the use-case lens, cluster reveal + focus, deferred visible-only layout, busy overlay, grounded card fallback). All Bodhi chrome retained: cluster-hull compound nodes, fcose layout, minimap, legend dock, fuzzy search, welcome, theme, deep-linking.
  • FIBO adaptations via config: 4 domain clusters; curated bridges dashed/red by provenance; core-default view + Core/full toggle; maturity filter; detail panel shows FIBO IRI citation + provenance; real flows — a loan-origination decision guide, the underwriting guided tour, and mortgage-type / party-role comparison tables (all referenced by FIBO IRI, resolved to node ids at build); "for agents" OKF export.
  • Sub-domain clustering — each domain split one level into its FIBO modules as sub-clusters (30 total: FBC→4, FND→15, BE→8, LOAN→3), shaded within the domain hue; canvas shows a hull per sub-domain, legend groups them under the domain (collapsible, counts). Generated in data.js (CLUSTERS + CLUSTER_GROUPS).
  • Offline/PWA: network-first service worker (fresh when online, cache offline fallback — avoids stale-cache during dev), no CDN (all libs/fonts vendored).
  • Optional: 2-level nesting (domain super-hull around module hulls) if desired
  • Per-domain lazy loading for the full-ontology view (currently one data.js; fine at 1.3k, revisit at 5–10k scale)
  • Use-case lens — toolbar selector focuses one use case's curated subgraph (Loan origination / KYC / Securities); each detail card shows use-case badges (reverse lookup: concept → use cases), clickable to activate the lens. Membership flows from curation/usecases/*.json via use_cases: frontmatter.

E3 — Bridges & second use case

  • Decide fate of intra-domain bridges (e.g. lender played-by financial-institution) vs cross-domain-only for EDM
  • Map working bridge edge-names → formal FIBO object properties
  • Second use case: KYC / beneficial-ownership — 58 curated core concepts (curation/kyc.json) + 4 cross-domain bridges (curation/kyc-bridges.json) + context pack (export/kyc/). Backbone party/entity classes come from Commons (CMNS). Tooling is now spec-driven (curation/usecases/*.json), so a use case is a repeatable recipe.
  • Third use case: Securities instruments & issuance — 59 core (curation/securities.json), curated examples overlay for the cards (curation/securities-examples.json), 3 cross-domain bridges (curation/securities-bridges.json), pack (export/securities/). New backed-by relation added for the MBS→mortgage / ABS→loan bridges.
  • Fourth use case: Regulatory reporting & compliance — 52 curated core concepts (curation/regulatory-reporting.json) spanning 8 clusters (CMNS/FBC/FND/BE/BP/LOAN/CAE/SEC), the most cross-domain use case; curated examples (52) + 8 grounded definitions for FIBO's undefined classes + 4 cross-domain bridges (reporting-party→LEI, report→agency, report→regulation, trades-reporting→facility) + pack (export/regulatory-reporting/). Map now shows 15 curated bridges; default core spans 4 use cases (224 concepts).

E4 — Scale domains

  • Onboard SEC, DER, IND, MD, BP, CAE — all six loaded alongside FND/LOAN/FBC/BE + CMNS. Full FIBO now emitted: 3,104 concepts / 6,676 edges / 68 sub-clusters, gate green. Pending (not-yet-loaded) edges fell ~580 → 217 (remaining targets are LCC).
  • Loaded Commons (CMNS) — scripts/fetch_commons.sh fetches the 19 OMG Commons modules FIBO imports (content-negotiated RDF); extract.py loads them as CMNS. Resolved ~580 edges: pending links 693 → 114; graph now 1,440 nodes / 3,001 edges. (Commons isn't SHA-pinnable via OMG deref — a reproducibility caveat vs. the fibo pin.)
  • Per-domain core: sets + lateral bridges + index.md

E5 — EDM Council contribution

  • Export curated bridges as a proposal artifact — etl/export_bridges.py (+ make contrib) packages all 15 gated cross-domain bridges into contrib/edmc-bridge-contribution.md (methodology + per-use-case tables) and contrib/fibo-bridges.ttl (RDF/Turtle; each bridge a proposed kmb: triple + an owl:Axiom annotation carrying rationale + citation + provenance; parses in rdflib, 166 triples). Proposals stay in a neutral kmb: namespace — no unverified FIBO properties asserted (Rule 1).
  • Re-model accepted bridges as formal owl:Restriction axioms in FIBO style (once reviewers map each edge to a FIBO/Commons property)
  • Engage EDM Council OKG Innovation Lab / FIBO CoP (DCO-signed PR) — timing is user's call

E6 — Tech-debt / cleanups

  • Edge-label normalization edge cases (camelCase from properties defined in unloaded domains)
  • Review 219 orphan nodes (roots vs genuinely disconnected)
  • Bump/refresh FIBO pin deliberately (churns generated files, may move IRIs) — document process
  • Optional: shellcheck for scripts/*.sh in the gate

Open decisions (need a call)

  • Repo visibility: ✅ RESOLVED — public since the FOSS launch.
  • Commit generated knowledge/? currently yes (browsable without rebuild). Revisit if it gets noisy at scale.
  • Intra-domain bridges in the EDM contribution set — include or agent-only? (see E3)
  • Eval agent/model — benchmark now drafted in-repo (53 Q, eval/benchmark.json, grounded in the pack); still open: which model runs the live agent, and SME review of the gold answers before numbers are treated as authoritative.

Key facts to not re-derive

  • FIBO relations are owl:Restriction blank-node axioms, not flat triples (extractor handles this).
  • hasMaturityLevel is per-ontology → propagated to classes.
  • OKF types links by body prose, not frontmatter → our relations: typing is a private convention (fine for our build; generic OKF consumers see untyped links).
  • FIBO has no Production git tags (only 2018Q3); we pin a commit SHA (fibo-source.pin).
  • No AI attribution / no employer references anywhere (guard-enforced); author = Sanjeev Azad sanjeev.azad@gmail.com.