SEOCHO | Blog

SEOCHO Design Philosophy & Operating Principles

Fri, 01 May 2026 00:00:00 GMT

Source mirrored from seocho/docs/PHILOSOPHY.md

This document captures the non-negotiable design philosophy for SEOCHO and how it maps to implementation.

Core Philosophy

Extract domain rules and key domain characteristics from heterogeneous data into a SHACL-like semantic layer.
Preserve extracted data in table form and build ontology artifacts (.ttl and related files) as merge/governance evidence.
Use ontology-aware entity extraction and linking by providing prompt + ontology context to LLMs, then convert related data into graph structures.
Map graph instances to graph agents in a 1:1 model.
Keep router agent as the default request entrypoint and delegate to graph agents that can answer the query.
Use supervisor-style orchestration for router <-> graph-agent collaboration, with ontology metadata driving query-to-instance allocation.
Track and manage all agent-layer flow data through a vendor-neutral trace contract, with JSONL as the canonical artifact and Opik as the preferred team exporter.

Additional Perspectives

Provenance-first evidence model:
- Every extracted fact, inferred rule, and routing decision must be traceable to source records/chunks.
Confidence-aware decisioning:
- Semantic disambiguation and routing should expose confidence and support deterministic human override.
Contract-first DAG integration:
- Backend emits strict topology metadata (node_id, parent_id, parent_ids) for frontend workflow canvas rendering.
- UI consumes backend topology directly and must avoid heuristic-only lineage reconstruction.
Practical readiness before promotion:
- Rule profiles must pass readiness checks (/rules/assess) before governance promotion/export.
Versioned ontology lifecycle:
- Ontology files (.ttl, hint artifacts, profiles) are control-plane assets with explicit versioning and rollback.
Observability as a product surface:
- Trace artifacts must remain portable and reviewable outside any single vendor.
- Opik traces are preferred team-facing evidence for trust and governance, not the only valid runtime contract.
Cost-and-SLO bounded orchestration:
- Debate/semantic paths must expose measurable latency and cost envelopes for production viability.
Deterministic degradation:
- Router/graph-agent flows require explicit fallback behavior when confidence or topology contracts are not met.

Expert Feasibility Lens

For multi-role feasibility reviews (frontend/backend/architect/software engineer/DBA), use:

/blog/feasibility-review-framework/

Implementation Mapping

Ontology-guided extraction/linking:
- extraction/ontology_prompt_bridge.py
- extraction/extractor.py
- extraction/linker.py
SHACL-like rule lifecycle:
- extraction/rule_constraints.py
- extraction/rule_api.py
- extraction/rule_export.py
Graph instance and agent mapping:
- extraction/database_manager.py
- extraction/agent_factory.py
- extraction/debate.py
Router/supervisor and semantic orchestration:
- extraction/agent_server.py
- extraction/semantic_query_flow.py
Flow telemetry and auditability:
- extraction/tracing.py
- JSONL trace artifacts and optional Opik profile in docker-compose.yml

Operating Checks

Before promotion to production-like use:

Rules:
- Run /rules/assess and review practical_readiness, violation_breakdown, export_preview.
Routing:
- Confirm router decisions align with ontology-backed graph metadata.
Traceability:
- Verify JSONL traces and, when enabled, Opik spans include enough metadata to reconstruct decision path.
UI contract:
- Ensure workflow canvas lineage uses backend topology fields, not inferred-only links.
Governance:
- Persist ontology/rule artifacts as versioned files and record change rationale in decision docs.

Turning a Folder of Filings into a Compliance Graph in Under a Minute

Sun, 19 Apr 2026 00:00:00 GMT

Compliance teams spend an enormous amount of time re-reading the same filings. Which regulation does this inquiry reference? Which control evidence covers this incident? Which policy version was in effect last quarter? Those answers are already in the documents — they just are not structured yet.

This post walks through a working SEOCHO usecase that shows one path out of that loop: declare the ontology you already think in (regulation, regulator, incident, control, policy), ingest a folder of filings, and ask questions that cross those entity boundaries. The whole example fits in one directory of the SEOCHO repository and runs on pip install "seocho[local]" with no server.

The thesis in one sentence

In regulated finance, the ontology should carry the quality bar, not the model.

Prompt-driven RAG can get away with vague answers in consumer-facing settings. In compliance, “approximately correct” is not correct. If you want an answer you can show to an auditor, the system must be able to point at a typed path in a graph — not summarize a paragraph.

That is what the examples/finance-compliance/ usecase demonstrates, using the smallest ontology that still resembles real work: six entity types, six relationships.

The ontology

Company ── SUBJECT_TO ──▶ Regulation ── ENFORCED_BY ──▶ Regulator
   │
   ├── REPORTED ──▶ ComplianceIncident ── RELATES_TO ──▶ Regulation
   │                     │
   │                     └── MITIGATED_BY ──▶ ControlEvidence
   │
   └── GOVERNED_BY ──▶ Policy

Every noun on that diagram is a node type; every arrow is a typed relationship. Declared as code:

from seocho import NodeDef, Ontology, P, RelDef

onto = Ontology(
    name="finance_compliance",
    nodes={
        "Company": NodeDef(properties={"name": P(str, unique=True), "ticker": P(str)}),
        "Regulator": NodeDef(properties={"name": P(str, unique=True)}),
        "Regulation": NodeDef(properties={"name": P(str, unique=True), "code": P(str)}),
        "ComplianceIncident": NodeDef(properties={
            "summary": P(str, unique=True), "date": P(str), "severity": P(str),
        }),
        "ControlEvidence": NodeDef(properties={
            "summary": P(str, unique=True), "date": P(str), "status": P(str),
        }),
        "Policy": NodeDef(properties={"name": P(str, unique=True), "version": P(str)}),
    },
    relationships={
        "SUBJECT_TO": RelDef(source="Company", target="Regulation"),
        "ENFORCED_BY": RelDef(source="Regulation", target="Regulator"),
        "REPORTED": RelDef(source="Company", target="ComplianceIncident"),
        "RELATES_TO": RelDef(source="ComplianceIncident", target="Regulation"),
        "MITIGATED_BY": RelDef(source="ComplianceIncident", target="ControlEvidence"),
        "GOVERNED_BY": RelDef(source="Company", target="Policy"),
    },
)

Full version in examples/finance-compliance/ontology.py.

Ingest six filings

The repo ships six small mock documents under sample_docs/:

A quarterly filing
A regulator inquiry (FMSA asks about MCR-401)
An incident report (I-2026-007 — client-data-access misconfiguration)
A control attestation (A-2026-014 remediating the incident)
Board meeting minutes (discussing the inquiry, approving a new policy)
A policy update (Trade Surveillance v2.0)

Each file is plain English, 50 to 80 words — the shape of the ambient text a compliance team actually receives, not pre-structured JSON.

Running the example:

pip install "seocho[local]"
export OPENAI_API_KEY=...
python examples/finance-compliance/quickstart.py

SEOCHO reads each file, runs an ontology-guided extraction pass, and writes nodes and typed relationships into an embedded LadybugDB file at .seocho/local.lbug. No separate server. No Docker.

Questions that cross entity boundaries

Once the graph is populated, the quickstart asks four questions designed to only have good answers if the typed paths are right:

“Which regulations is Acme Financial Services subject to, and who enforces them?” → Company → SUBJECT_TO → Regulation → ENFORCED_BY → Regulator
“What incidents have been reported, and which regulations do they relate to?” → Company → REPORTED → ComplianceIncident → RELATES_TO → Regulation
“Which control evidence mitigates incident I-2026-007?” → ComplianceIncident → MITIGATED_BY → ControlEvidence
“Which policies govern trade surveillance at Acme Financial Services?” → Company → GOVERNED_BY → Policy

The answers are not free-text summaries. They are traces through a graph your ontology constrained. Swap the company, regulator, or regulation name across all six filings and the answers update consistently — because the entity identity is a graph node, not a string in a paragraph.

Why this beats vector search for compliance

Vector retrieval can find that documents 2 and 3 both talk about “MCR-401”. It cannot tell you that “the inquiry in document 2 references the same regulation that document 3’s incident relates to.” The latter is a join over typed edges — exactly what a graph with an ontology gives you and what an embedding score approximates only noisily.

When an auditor asks “show me every incident in scope for MCR-401 and the controls that mitigate each,” a vector-only system can summarize. A graph-backed system can enumerate. That is the wedge.

Closed-network friendly on purpose

The same example runs against a local vLLM or any OpenAI-compatible endpoint — the quickstart accepts --llm deepseek/deepseek-chat, --llm kimi/kimi-k2.5, etc. Nothing in the ontology layer requires a hosted model. For regulated environments where prompts cannot leave the network, swap the --llm flag and keep the rest of the pipeline identical.

Runtime-side, SEOCHO’s ontology readiness gate can refuse rule-profile promotion when validation reports a blocked verdict — so the ontology is not just context for prompts, it is a gate on governance actions. Closed-network deployments lean on that gate to keep model dependency low.

Try it

git clone https://github.com/tteon/seocho && cd seocho
pip install "seocho[local]"
export OPENAI_API_KEY=...
python examples/finance-compliance/quickstart.py

The full walkthrough, including the mock filings, lives at examples/finance-compliance/.

Next usecases — contribute one

We deliberately keep docs/USECASES.md short. A usecase only appears there when there is a runnable example behind it. Finance compliance is the first. We would welcome contributions for:

Healthcare consent tracking — patients, consents, studies, revocations
Supplier risk — suppliers, contracts, incidents, alternates
Engineering team memory — services, incidents, runbooks, owners
Legal contract obligations — parties, obligations, deadlines, breaches

The pattern to copy is the finance example. Pick a domain you know, write a six-entity starter ontology, drop five to ten mock docs next to it, and open a pull request — the ontology shape is the interesting part.

What this is not

This example is not a production compliance system. The mock filings are intentionally short and synthetic. Real compliance work adds authentication, auditable evidence storage, retention policies, change-tracking, and regulator-specific formats that a six-file toy cannot cover.

What it is: a concrete, runnable shape. If “ontology-governed” has felt abstract in previous SEOCHO posts, this is the shortest working demo of the idea. Fork it, rename the entities, point it at your docs.

Feasibility Review Framework & Rubrics

Sat, 21 Feb 2026 00:00:00 GMT

Source mirrored from seocho/docs/PHILOSOPHY_FEASIBILITY_REVIEW.md

This document operationalizes philosophy-level decisions into an execution review framework for multi-role experts.

Purpose

verify whether SEOCHO philosophy can be delivered with current stack and constraints
identify blocking risks before implementation scales
define measurable Go/Conditional Go/No-Go criteria

Required Panel Roles

frontend engineer
backend engineer
software architect
software engineer (application/platform)
database engineer (DBA)

Review Dimensions

Evaluate each dimension with Green, Amber, or Red.

Dimension	Key Question	Evidence
Semantic Layer Viability	Can SHACL-like rules be inferred, validated, and promoted safely?	`/rules/assess`, profile/export results
Ontology Governance	Are `.ttl`/hint/profile artifacts versioned and rollback-safe?	git history, ADR, release notes
Agent Topology Integrity	Is graph-instance <-> graph-agent 1:1 mapping enforced?	runtime config, orchestration traces
Router Allocation Quality	Does router choose target graphs with explainable confidence?	routing metadata, override logs
DAG Contract Reliability	Does UI render topology only from backend contract fields?	trace payload schema tests
Data/Query Safety	Are query surfaces policy-gated and workspace-safe?	policy checks, audit traces
Cost/Latency Envelope	Can end-to-end flow stay within target SLO and budget?	p95 latency, token/runtime cost

Role-Specific Checklists

Frontend Engineer

topology lines are rendered from backend metadata (node_id, parent_id, parent_ids)
no heuristic-only lineage reconstruction for production path
fallback UI behavior is defined when topology is partial/missing
trace canvas scales under fan-out/fan-in orchestration load

Backend Engineer

trace schema contract is deterministic and versioned
router/semantic flows expose confidence and decision reasons
policy checks guard runtime endpoints consistently
workspace_id is propagated through all runtime contracts

Software Architect

control plane and data plane boundaries remain explicit
ontology governance path stays offline-heavy (not hot-path blocking)
ADR coverage exists for major orchestration/contract changes
failure modes have deterministic degradation strategy

Software Engineer (Platform/Application)

end-to-end flow is testable with reproducible fixtures
operational runbooks cover ingest -> rules -> routing -> response
observability fields are sufficient for incident replay
integration contracts across modules avoid hidden side effects

Database Engineer (DBA)

DozerDB/Neo4j compatibility assumptions are validated continuously
fulltext/index lifecycle is automated and idempotent
constraint/export plans are reviewed before governance promotion
query patterns are bounded for performance and operational safety

Decision Rubric

Go: no Red, and at most 2 Amber, with owners/dates assigned
Conditional Go: 1 Red or 3-4 Amber, with mandatory mitigation plan
No-Go: 2+ Red, or unresolved safety/governance blocker

Risk Register Template

ID	Risk	Severity	Owner Role	Mitigation	Trigger
R1	Example: ontology/profile drift	High	Architect	version pin + compatibility test	failed export/readiness

30/60/90 Plan Template

Day 0-30:
- enforce schema tests for topology contract
- baseline /rules/assess thresholds and publish pass criteria
Day 31-60:
- close confidence/override loop with operator UX and audit export
- add replay-grade Opik trace dashboards for router/debate/semantic
Day 61-90:
- production hardening for index/constraint lifecycle
- define release gate tying ADR + readiness + SLO checks

KPI Baseline

rule readiness pass rate (ready ratio) per ingestion batch
router allocation precision (verified answerable-route ratio)
semantic disambiguation confidence calibration (override rate vs confidence)
topology contract compliance (trace payload schema pass rate)
p95 end-to-end latency by mode (router, debate, semantic)
incident replay completeness (trace-to-root-cause success ratio)

Initial Panel Synthesis (2026-02-20)

Decision: Conditional Go

Primary reasons:

philosophy and architecture intent are explicit and well aligned
SHACL-like readiness and DAG contract directions are implemented
operational hardening remains for confidence calibration, SLO envelopes, and governance automation

Immediate priorities:

treat topology payload schema as a release-blocking contract
enforce readiness gates before rule/ontology promotion
publish confidence policy for router/semantic fallback behavior

Image Prompts for Landing Page

Sat, 21 Feb 2026 00:00:00 GMT

Prompts for 3D Graph / Network Assets

1. Hero Image / Core Engine

Prompt: A hyper-realistic, 3D abstract representation of a “knowledge graph neural network” floating in a pitch-black void. The nodes are glowing with vibrant cyan and violet neon lights, connected by sleek, pulsating fiber-optic cables. High-end, sleek, Apple-style product rendering, cinematic lighting, glassmorphism elements, dark gray metallic details, very high resolution, 8k, octane render.

2. Semantic Routing Visualization

Prompt: A sleek 3D graphic showing a glowing data packet (representing a user query) traveling along a bright purple neon track, splitting into branching paths (representing different knowledge graphs). Dark mode, deep slate background, elegant tech aesthetic, depth of field, sharp focus, futuristic but clean and minimalist, neon edge lighting.

3. Debate Engine / Multi-Agent Collaboration

Prompt: Three glowing, crystalline orbs (representing AI agents) hovering around a glowing, central holographic document. The orbs emit subtle light beams (cyan, emerald, and rose pink) that intersect at the document. Pitch black background, premium tech startup aesthetic, subtle glassmorphic reflections on the ground, extreme detail, 3D render.

SEOCHO Runtime Update: Strict E2E Smoke Tests and the Open Source Playbook

Sat, 21 Feb 2026 00:00:00 GMT

We are excited to announce a major update pushed to the SEOCHO main repository today, focusing heavily on runtime stability, reproducible quickstarts, and contributor experience.

If you are an external team or an open-source contributor looking to adopt the SEOCHO engine, this update is specifically designed for you.

1. Reproducible User Activation Path & New Quickstart

We have completely overhauled our Quick Start guide to follow a strict, reproducible User Activation Critical Path.

Previously, setting up the graph and running the agents could be highly environmental. Moving forward, no architecture changes will be merged unless this exact user path functions flawlessly:

Ingest raw data via the /platform/ingest/raw endpoint.
Ensure semantic index provisioning via the /indexes/fulltext/ensure API.
Execute semantic/debate chat successfully.
Pass the new make e2e-smoke automated test gate.

This flow is the definitive acceptance criteria for our user-facing releases.

2. Introducing the Open Source Playbook

To support external teams adapting SEOCHO to real, proprietary domain data, we have published the Open Source Playbook.

This playbook serves as a direct extension guide, detailing exactly where to hook into the engine:

Route Extensibility: How to modify extraction/semantic_query_flow.py for custom dispatch logic.
Ontology Injection: How to replace the default FIBO constraints with your own domain ontology.
Testing Contracts: Required quality gates (make test-integration, make e2e-smoke) that you must pass before expanding features.

3. Priority Execution Board Published

To ensure total transparency into the SEOCHO system’s next steps, we have published our current Priority Execution Board within the Architecture documentation.

P0 Priorities currently underway:

Isolating the OpenAI Agents SDK calls behind a unified adapter layer.
Enforcing contract tests for runner signatures.
Real-database Agent Provisioning (gracefully handling missing/stale databases in the debate fan-out phase).

Update Now

To experience the new stable routing and explore the updated CLI trace capabilities:

git pull origin main
make e2e-smoke

Read the full details in our updated Docs section.