feat: OKF export + KG graph visualizer + KG-graph-health (P6/P1/P5)#222
Merged
Conversation
Add `--layout okf` to brain_export: frontmatter-first concept docs (non-empty `type` from tier, JSON-encoded string scalars so arbitrary values stay parseable YAML, READ-ONLY banner moved into the body) plus reserved bundle-root index.md (grouped by tier, relative links, okf_version) and log.md (ISO date headings, newest first). Redaction and secret-tag skipping are shared with the managed-agents path; manifest gains okf_version. Makes any brain a spec-conformant OKF producer, viewable in OKF's own visualizer. 5 new unit tests cover frontmatter-first conformance, YAML safety on colon/quote values, reserved index/log structure, redaction, and manifest. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…izer (P1 backend)
Add the backend for the knowledge-graph visualizer panel. build_kg_graph
(visual_snapshot.py) is a pure transform of a 1-hop get_neighbors result into a
{nodes, edges} star graph, carrying the signals that make the KG richer than a
plain hyperlink graph: edge confidence, status, contradicted, stability (FSRS
decay), evidence_count. A correct 1-hop star (expand-on-click re-roots on a
neighbour) is the right primitive — multi-hop rows lack the subject side, so a
2-hop dump would draw wrong edges.
GET /snapshot/graph?entity=<uuid>&limit=<n> (X-Project-Id header) composes the
already-tested kg_service.get_neighbors + _validate_uuid_field with the
serializer. 6 new unit tests cover the serializer (dedup, signal mapping,
contradicted/stale, missing fields, empty).
Follow-up before release: a DB-gated integration test for the endpoint against a
live KG (the serializer — where the logic lives — is fully unit-tested here).
Frontend Cytoscape panel is the next P1 increment.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Make /snapshot/graph accept the project via ?project= query (falling back to the
X-Project-Id header) so the dashboard calls it like GET /snapshot. Add TestClient
coverage for every branch — 400 (no project), 422 (bad entity UUID), 503 (no KG
configured), and the success path (monkeypatched KG service → {nodes, edges}) —
plus an OpenAPI-presence check. Regenerate the OpenAPI contract snapshot for the
new route (openapi.json + openapi-3.22.0.json) so the drift gate stays green.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Re-apply the KG visualizer panel onto the current (EPIC-078) dashboard. Adds a "Graph" page rendering GET /snapshot/graph with vendored (offline, CSP-safe) Cytoscape.js: edge opacity/width = confidence, red-dashed = contradicted, dotted/faded = stale/superseded, focus node ringed. Click a neighbour to re-centre (1-hop expand); click an edge for predicate/confidence/status/ stability(decay)/evidence. KPI tiles, legend, entity-UUID input, help entry. XSS-safe IIFE, no bundler — matches dashboard conventions. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…cs (P5) The memory-store diagnostics scorecard (freshness/staleness/GC, shipped in 3.25) covers memory *entries*, not the KG's typed/evidenced edges. Add the missing KG-graph-health slice: - build_kg_health(counts) — pure scorer: orphan_ratio, stale_ratio, contradicted_ratio, an ok/warn/degraded status, and actionable recommendations (6 unit tests). - PostgresKnowledgeGraphStore.graph_health_counts() + brain-scoped aggregate SQL (orphan entities = active entity with no active edge; edge counts by status + contradicted). - kg_service.graph_health() wrapper; GET /snapshot/graph/health endpoint (?project= or X-Project-Id), fully mock-tested (400/503/success/openapi). Carve-out of the original P5 after reconciling with 3.25.0: the general freshness/GC recommendations already shipped upstream; this adds only the KG-specific graph rot they don't measure. build_kg_health + endpoint are unit- tested; graph_health_counts SQL is DB-gated (needs a live KG to verify). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a "Health" button that fetches GET /snapshot/graph/health and shows the status (ok/warn/degraded), orphan/stale/contradicted counts + ratios, and any recommendations in the detail pane — making graph rot visible alongside the focus view. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Validates the P5 aggregate SQL against a real schema in CI (ephemeral Postgres): seeds 3 entities (one orphan) + 1 edge, asserts entities_active/orphan_entities/ edge counts. Skips locally when TAPPS_TEST_POSTGRES_DSN is unset. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Reconciled onto current
main(3.25.0) after finding the original work was built on a 3-versions-stale base.What's here
--layout okfonbrain_export(frontmatter-first concept docs + reservedindex.md/log.md). Makes any brain a spec-conformant OKF producer.build_kg_graphserializer +GET /snapshot/graph(1-hop focus star, edge confidence/status/contradicted/stability/evidence) + a Cytoscape.js dashboard panel (vendored, offline/CSP-safe).build_kg_healthscorer +graph_health_countsaggregate SQL +GET /snapshot/graph/health(orphan/stale/contradicted ratios, ok/warn/degraded) + a dashboard "Health" readout. Carve-out after confirming the memory-store freshness/GC scorecard already shipped upstream — this adds only the KG-graph rot it doesn't measure.Verification
graph_health_countsSQL) are covered by arequires_postgresintegration test that CI runs against ephemeral Postgres — validating the SQL against a real schema.node --check-clean but not browser-run in this session (no Playwright smoke).🤖 Generated with Claude Code