Horismos Framework Documentation¶
Horismos is an ontology-first neuro-symbolic decision and capability kernel. Rust core, Python bindings. The ontology overlay declares a bounded decision/capability fragment, evaluated as a versioned projection over an existing system of record. Neural proposes; symbolic decides.
Status: framework definition, v0.1 — written in shipped voice so every contract is concrete and arguable, reviewed before implementation. Where behavior is still an open decision it is marked [DECIDE] and cross-referenced to a PRP in
../../PRPs/. Pivot adopted 2026-08-24 (bounded projection kernel —PRPs/PRP-000-vision- positioning.md§"Snapshot-scoped guarantees"): docs below are updated at the contract level for the new positioning. PRP-008's host SPI, FHIR and repository adapters, CDS-Hooks surface, and bounded PlanDefinition subset are now shipped; remaining future behavior stays marked and owned by its PRP.
The one-paragraph mental model¶
You author a small RDFS-plus overlay (.ttl) that declares the decision/capability
fragment your deployment needs: classes and constraints, rules, and an optional decision
workflow. The runtime loads it, formally verifies it, and evaluates it as a bounded
projection — a versioned, explicitly scoped snapshot hydrated from your existing system
of record (a FHIR server, a repository, a tool registry), never a live connection to it.
Natural language enters through a single declared perception boundary where an LLM
extracts typed instances — validated before they become facts. Everything downstream —
inference, workflow transitions, tool calls — is deterministic, traced, and replayable
for that snapshot; a typed proposed effect set commits back to the system of record
conditionally, failing closed if the source has moved on. Delete the LLM and the
framework still runs. Horismos does not own your durable records, your enterprise
workflow, your provider clients, or your standard terminology — it overlays them.
Documentation map¶
| # | Doc | What it covers |
|---|---|---|
| 01 | Concepts | The nouns, the two principles, how Horismos differs from agent frameworks and adjacent standards |
| 02 | The Ontology | RDFS-plus profile: classes, constraints, the full horis: vocabulary, imports, standard-artifact anchoring |
| 03 | The World | Instance store as an admitted projection: assertion, validation gate, queries, snapshots, freshness, conditional commit |
| 04 | Reasoning | Rules, forward/backward chaining, subsumption, proof trees, scoped to one input closure |
| 05 | Workflows | Step types, transitions, preconditions, fallbacks, termination — optional decision microflows a host may invoke |
| 06 | LLM Boundaries | Perception & narration: schema derivation, confidence, fallback contracts |
| 07 | Tools | Tool contracts, bindings (Python/Rust/HTTP/MCP), effect validation, proposals, adapter-mediated commits |
| 08 | The Bridge | Model backends, registry, timeouts, the mock backend, provider mechanics |
| 09 | Traces | The trajectory schema, replay, audit, training-corpus export |
| 10 | Verification | BDD checks, witnesses, the assumption manifest, non-vacuity, workflow verification, CI usage |
| 11 | Python API | The horismos package reference |
| 12 | Rust API | The horismos-core crate reference, feature flags, WASM |
| 13 | Authoring | The authoring agent: import/align/overlay-first, SMEs converse, Claude drafts, the verifier gatekeeps |
| 14 | Architecture | Internals: crate layout, PyO3 boundary, performance, PRP mapping, adapter/service crate boundary |
| 15 | Security & Trust | The v1 threat model: assets, trust boundaries, threats, mitigations vs. deployer-owned concerns; the host-harness boundary |
Reading paths¶
- "Show me the product" → 01 → 05 → 06 → the quickstarts in 11.
- "I'm reviewing before we build" → in order, 01–15; argue with every [DECIDE].
- "I'm reviewing trust/deployment risk" → 15, then 06/07/08/09/13 for the boundaries it cites.
- "I build agents today" → 01 (the comparison table), 07 (tools inversion), 06.
- "I'm the SME" → 13 only. You will never read Turtle unless you want to.
- "I'm integrating against FHIR/CIS or a coding harness" →
PRPs/PRP-000-vision- positioning.md's comparison table, thenPRPs/PRP-008-standards-host-integration/01-objective.mdfor the mechanism and its exact prototype limits; docs 03 and 14 for how the projection boundary works today, andexamples/vte/for the recorded vertical slice.
The running example¶
All documentation uses one worked domain: clinical triage (triage.ttl) — a
patient-intake workflow that extracts vitals and symptoms from natural language,
derives acuity through rules over a SNOMED-anchored symptom hierarchy, and routes to
a queue via an EHR tool. It exercises every framework feature. The full file is built
up progressively in docs 02–07.
Research wiki¶
../../research/ reality-checks this design against the field (CIG formalisms,
neuro-symbolic AI, clinical validation practice, terminology engineering,
agent-authored ontologies) — see research/README.md.
Prior art¶
Horismos inherits designs proven in the sigil-lang project (same authors): Rete-lite
matching, BDD verification, constraint solving, trace semantics, the pluggable neural
bridge, and the validate-and-refine authoring loop — collectively ~1,270 tests of
prior art. Horismos is not a rewrite of sigil-lang; it inverts it: the engine is the
product, and the language surface is gone (an authoring agent writes standard Turtle
instead).