How aiob3/ssot-okf works
Purpose and Repository Shape
This is a multi-language reference repository for governed context/intent workflows and Google Cloud Knowledge Catalog integrations. It combines: a Python reference agent that builds knowledge bundles, TypeScript tooling that synchronizes Markdown with catalog services, enrichment examples, and validation harnesses. The top-level README defines the SSOT-governed model: operator evidence is progressively promoted through interest, intent, objective, execution binding, loopback, and certified handoff.
Primary Entry Points
• Python reference-agent CLI/module: okf/src/reference_agent/__main__.py, okf/src/reference_agent/cli.py, okf/src/reference_agent/runner.py.
• Markdown synchronization tool and MCP endpoint: toolbox/mdcode/src/tool/main.ts, toolbox/mdcode/src/tool/commands.ts, toolbox/mdcode/src/tool/mcp.ts.
• TypeScript enrichment agent: toolbox/enrichment/src/agent/main.ts, toolbox/enrichment/src/agent/enrich/command.ts.
• Deja-vu validation scripts: harness/deja_vu/scripts/homologate.py, harness/deja_vu/scripts/mcp_wrapper.py.
Knowledge Bundle Model
The OKF package treats a filesystem of Markdown documents as a governed knowledge bundle. Document, path, indexing, and synthesis logic form the core bundle boundary in okf/src/reference_agent/bundle/document.py, okf/src/reference_agent/bundle/index.py, and okf/src/reference_agent/bundle/synthesizer.py. Bundles contain dataset/table metadata, joins, metrics, policies, computations, skills, attesters, and generated visualization pages; examples live under okf/bundles/ga4/, okf/bundles/crypto_bitcoin/, and okf/bundles/acme_retail/.
Reference-Agent Flow
The Python agent accepts user tasks through the CLI, assembles prompts and contextual bundle content, then operates through explicit tool layers. Agent orchestration is in okf/src/reference_agent/agent.py; tools expose bundle/context, source, and web capabilities in okf/src/reference_agent/tools/bundle_tools.py, okf/src/reference_agent/tools/source_tools.py, and okf/src/reference_agent/tools/web_tools.py. Prompt contracts are versioned Markdown in okf/src/reference_agent/prompts/reference_instruction.md and okf/src/reference_agent/prompts/web_ingestion_instruction.md. This separates agent reasoning from source access and filesystem mutations.
External Data and Presentation Boundaries
BigQuery is a first-class source adapter behind a source abstraction: okf/src/reference_agent/sources/base.py and okf/src/reference_agent/sources/bigquery.py. Web ingestion is isolated in okf/src/reference_agent/web/fetcher.py. Generated bundle visualization is handled separately by okf/src/reference_agent/viewer/generator.py and its static/template assets, rather than by an application server. Bundle viz.html files are output/artifact-style views.
mdcode Synchronization Platform
toolbox/mdcode is the TypeScript infrastructure layer for bidirectional catalog synchronization. It models layouts, manifests, source adapters, metadata, snapshots, and synchronization in toolbox/mdcode/src/libts/layout.ts, toolbox/mdcode/src/libts/manifest.ts, and toolbox/mdcode/src/libts/sync.ts. Source implementations include BigQuery datasets, Knowledge Catalog/Dataplex entry groups, and knowledge bases: toolbox/mdcode/src/libts/sources/bq-dataset.ts, toolbox/mdcode/src/libts/sources/entrygroup.ts, and toolbox/mdcode/src/libts/sources/kb.ts. Google Cloud integration code is bounded under toolbox/mdcode/src/libts/gcp/, including BigQuery, Dataplex, and CRM clients.
Enrichment and Governance Validation
The Python and TypeScript enrichment samples demonstrate ingestion, metadata snapshot/catalog handling, documentation generation, and publishing: samples/enrichment/src/enrichment/enrich.py, samples/enrichment/src/enrichment/metadata/snapshot.py, and toolbox/enrichment/src/agent/enrich/agent.ts. The Deja-vu harness independently validates historical evidence and explicitly gates real-source or MCP binding, centered on harness/deja_vu/scripts/validate_binding.py and harness/deja_vu/scripts/preview_real.py. This is the repository’s main control boundary for preventing uncertified external context from becoming governed execution input.
Main entry points: bundle_tools.py Agent tool boundary · sync.ts Sync engine · agent.py Agent orchestration · validate_binding.py Real-source binding gate
Components 20
OKF reference agent
Python governed knowledge-bundle workflow.
- Reference-agent CLI
okf/src/reference_agent/cli.py - Task runner
okf/src/reference_agent/runner.py - Agent orchestration · Assembles prompts, context, and explicit tool use.
okf/src/reference_agent/agent.py - Prompt contracts
okf/src/reference_agent/prompts/reference_instruction.md - Knowledge bundle core · Governed Markdown documents, index, and synthesis.
okf/src/reference_agent/bundle/document.py - Example bundles · GA4, Bitcoin, and retail governed metadata.
- Agent tool boundary · Separates bundle, source, and web access from reasoning.
okf/src/reference_agent/tools/bundle_tools.py - Source abstraction
okf/src/reference_agent/sources/base.py - Web ingestion
okf/src/reference_agent/web/fetcher.py - Bundle visualization · Generates bundle viz.html artifacts.
okf/src/reference_agent/viewer/generator.py
mdcode platform
TypeScript catalog synchronization and MCP tooling.
- mdcode CLI
toolbox/mdcode/src/tool/main.ts - MCP endpoint
toolbox/mdcode/src/tool/mcp.ts - Sync engine · Models layouts, manifests, snapshots, and bidirectional sync.
toolbox/mdcode/src/libts/sync.ts - Catalog source adapters · BigQuery datasets, entry groups, and knowledge bases.
toolbox/mdcode/src/libts/sources/bq-dataset.ts - Google Cloud clients · BigQuery, Dataplex, and CRM clients.
Enrichment examples
Python and TypeScript metadata enrichment flows.
- Enrichment agent · Generates and publishes enriched catalog documentation.
toolbox/enrichment/src/agent/enrich/agent.ts - Python enrichment sample · Ingests metadata and creates snapshots.
samples/enrichment/src/enrichment/enrich.py
Governance validation
Independent evidence and binding controls.
- Real-source binding gate · Prevents uncertified external context from entering governed execution.
harness/deja_vu/scripts/validate_binding.py - Evidence homologation · Validates historical evidence and MCP-mediated binding.
harness/deja_vu/scripts/homologate.py
Other components
- BigQuery
okf/src/reference_agent/sources/bigquery.py
Connections 20
- Reference-agent CLI → Task runner: runs
- Task runner → Agent orchestration: executes task
- Agent orchestration → Prompt contracts: uses instructions
- Agent orchestration → Agent tool boundary: uses explicit tools
- Agent tool boundary → Knowledge bundle core: reads and mutates
- Example bundles → Knowledge bundle core: provide governed content
- Agent tool boundary → Source abstraction: accesses sources
- Source abstraction → BigQuery: queries
- Agent tool boundary → Web ingestion: fetches web context
- Knowledge bundle core → Bundle visualization: generates views
- mdcode CLI → Sync engine: invokes
- MCP endpoint → Sync engine: serves synchronization
- Sync engine → Catalog source adapters: synchronizes adapters
- Catalog source adapters → Google Cloud clients: uses cloud APIs
- Google Cloud clients → BigQuery: accesses metadata
- Python enrichment sample → Enrichment agent: parallels enrichment flow
- Enrichment agent → Sync engine: publishes catalog content
- Evidence homologation → Real-source binding gate: checks evidence before binding
- Real-source binding gate → MCP endpoint: gates MCP binding
- Real-source binding gate → Source abstraction: gates real-source use