Published April 2026 · Last verified April 2026
io-gita.
A physics engine for the mind. Deterministic topological reasoning on compositional Hopfield networks - zero hallucination by design.
Deterministic routing
7,890+
Lines of Python
[ P ] · Pathways
Three entry points. Pick one.
The same engine reads four ways. The page below has been written for whichever way you came in — math first, felt sense first, or implementation first. The Rosetta Stone lets you cross between them at any time.
P/01
ON-SITEThe Scientist
Equations, proofs, convergence theorems.
If you came for the math, here it is unhedged: the topology-governs-feasibility result, the height-formula regression, the seed-stability tables, the kill-list of local predictors that did not survive intervention. Compositional Hopfield dynamics under dQ/dt = -Q + tanh(βWQ) + αF, full formalism.
P/02
EXTERNAL ↗The Seeker
Case studies, sliders, state-of-mind diagnostics.
If you came for the felt sense, the io-gita.com companion site walks you from eleven self-report questions to a personalised trajectory through the attractor landscape. No equations required — the slider on the research page lets you watch your own state move under Rajas and Tamas forcing in real time.
P/03
ON-SITEThe Architect
API, code, system architecture, implementation-ready.
If you came to build, the engine is a Python package with a 14-command CLI, a 9-endpoint FastAPI server, a verifier that grounds LLM chains-of-thought against the topology, and a roadmap of what ships next. Drop in a CSV, get a directed transition graph, route plans, and chain validation back.
[ A ] · The problem
LLMs reason by probability. Probability is not topology.
A large language model generates a chain of thought: premise, inference, conclusion. Each step sounds plausible. But the model has no ground-truth check for whether step three actually follows from step two - it only knows that step three is a likely token given step two. When the reasoning crosses into moral or strategic territory, likelihood and validity diverge. The model hallucinates a path that does not exist in the problem space.
Existing mitigations - retrieval augmentation, chain-of-thought prompting, self-consistency - still operate inside the probability layer. They make hallucination less likely; they do not make it impossible. What is missing is a separate, deterministic layer that encodes the problem space as a structured rule-set and checks every claimed transition against that structure.
io-gita was built to provide that layer. The Bhagavad Gita - encoded as a structured rule-set of forces and basins - becomes the ground truth. Every reasoning step is mapped to a basin in a high-dimensional attractor network. Every transition is checked against a pre-mapped topology. If the edge does not exist, the step is invalid - regardless of how eloquently the LLM phrased it.
[ B ] · The argument
Determinism is not a limitation. It is the feature that makes verification possible.
A Hopfield network with fixed atoms, fixed patterns, and fixed dynamics produces the same basin for the same initial state, every time. There is no sampling variance, no temperature parameter, no stochastic decoding. The attractor landscape is a geometric object. The Atlas is a graph. The planner is a graph search. The verifier is a graph edge check. Every layer is deterministic, inspectable, and testable.
[ C ] · Architecture
Eight layers. One geometry. Zero randomness.
Each layer is a contract - defined, versioned, tested. The network layer knows nothing about the planner. The planner knows nothing about the verifier. The verifier only needs the Atlas graph and a basin mapping.
Domain adapter
Incident response · manufacturing · future Gita encoding - maps real-world states to basins and actions to forces
Verifier
LLM chain validation · TF-IDF basin mapping · topological edge checking · VALID / PARTIAL / INVALID verdict
Planner + inference
BFS routing · tiered inference (graph → short ODE → full ODE) · conflict resolution · multi-hop chains
Schedule engine
Force-program execution · non-commutativity detection · novel-destination identification
Atlas
Directed transition graph · sampled edge mapping · SCC analysis · incremental updates · SHA-256 cache validation
Network dynamics
Hopfield attractor network · compositional patterns · pluggable nonlinearities · Euler + RK2 integrators
Control surface
FastAPI REST server · LRU network cache · CSV upload · CLI with 14 commands · interactive HTML explorer
Test harness
381+ pytest functions · contract tests · property tests · performance tests · blueprint contract validation
[ D ] · The numbers
Core LOC
7,890
Python · sg_engine/
Test files
19
pytest · contract · property
Test functions
381+
Unit · integration · slow
CLI commands
14
init · map · plan · infer · verify · serve
API endpoints
9
FastAPI · contract-bound
Accuracy
Observed 100%
Escape prediction · 2 domains (internal)
[ E ] · The forces
Four primitives. One landscape.
The physics of the mind is built from atoms, patterns, forces, and the atlas that binds them. Every reasoning operation is a manipulation of these four primitives.
F/01
Atoms - Primitive vectors
Random bipolar vectors in D-dimensional space. The irreducible units from which all patterns are composed. Eight atoms are sufficient to generate 60 distinct, well-separated attractor basins via weighted superposition.
F/02
Patterns - Attractor basins
Compositional combinations of atoms, sign-thresholded into stable high-dimensional states. Each pattern is a basin of attraction in the energy landscape. The first six are hand-constructed from atom combos; the rest are structured random with 0.75 cosine-similarity guardrails.
F/03
Forces - Directional bias
Normalized pattern vectors scaled by sqrt(D). When applied with alpha > 0, a force tilts the energy landscape and pushes dynamics toward a target basin. Forces are the 'fields' in the physics engine - moral duties, strategic goals, operational actions.
F/04
Atlas - Transition topology
The directed graph of which basins can reach which under forcing. Not all transitions exist - density is ~36.6% at alpha=0.50. The Atlas is the ground truth that makes hallucination detection possible: if an edge is absent, the claimed transition is invalid.
[ F ] · Operations
What the operator actually touches.
The CLI and API expose the full engine. The explorer turns topology into a visual map. The verifier turns LLM outputs into pass/fail results.
O/01
Route planning
Given a start basin and a goal basin, the planner searches the Atlas for the shortest valid path. If no direct edge exists, it finds multi-hop chains. If no path exists at any alpha, it reports unreachable and suggests the nearest hub sink.
O/02
Chain verification
Feed an LLM reasoning chain as a list of text steps. The verifier maps each step to its nearest attractor basin via TF-IDF cosine similarity, then checks whether consecutive basins have a valid edge in the Atlas. Steps without valid transitions are flagged red.
O/03
Force scheduling
Define a sequence of forces (moral duties, strategic actions, operational steps) with alpha intensities and durations. The schedule engine runs each force in order and reports the final basin, basins visited, and whether the outcome is novel (not reachable by any single force).
O/04
Bridge building
When two basins are disconnected, the BridgeBuilder synthesizes an intermediate pattern that opens a pathway. It validates the bridge by temporarily extending the pattern matrix and running dynamics. Only patterns that improve transition rate by >10% are applied permanently.
[ G ] · Under the hood
What’s actually in the source files.
Every layer below traces back to a real source path, a real line count, or a real test count. No aspirational names. What isn’t built yet sits in the Roadmap section.
S/01
Network Core
Compositional Hopfield Network · D=10,000 · beta=4.0
Attractor basin generator
Atoms are random bipolar vectors in high-dimensional space. Patterns are compositional combinations of atoms with weighted superposition, sign-thresholded into attractor basins. The weight matrix is built from pattern outer products. Supports D=10K, 20K, 50K tested.
Engineering twist
Five pluggable nonlinearities ship today - tanh, hard_tanh, sign, relu_symmetric, staircase - selectable at network construction. The same network instance can be re-evaluated under different activation regimes without rebuilding the pattern matrix.
S/02
Dynamics
ODE integrator · Euler + RK2 (Heun's method)
Basin transition simulator
Runs continuous-time dynamics from any initial state until convergence. Default Euler integration with a 0.05 dt step. RK2 (predictor-corrector) available for higher accuracy. Forces are applied via alpha-weighted directional bias. Noise injection supported up to sigma=0.10 with no accuracy degradation.
Engineering twist
A 10,000-step hard safety limit (MAX_ODE_STEPS) bounds every run. Convergence is detected by dQ norm dropping below 1e-7 - no fixed iteration budget, no risk of infinite loops on pathological landscapes.
S/03
Atlas
Directed transition graph · BFS · Kosaraju SCC
Topology mapper
Maps all N*(N-1) potential edges at multiple alpha levels via sampled edge testing. Stores edges with per-alpha hit rates. Computes in-degree / out-degree distributions, largest strongly connected component (SCC) via Kosaraju's algorithm, and hub source/sink rankings.
Engineering twist
Incremental atlas updates via add_and_remap() - add a new pattern, test only the new edges, and validate a sampled fraction of old edges for landscape drift. If drift exceeds 5%, the system warns and recommends a full remap. Pattern SHA-256 hashing validates cache integrity on save/load.
S/04
Planner
BFS shortest path · multi-hop chain · conflict resolution
Route finder over topology
Finds shortest paths between basins using BFS on the pre-mapped atlas graph. Supports multi-hop chain verification, min-alpha path discovery, and random valid chain generation. Executes chains on live network dynamics to confirm graph predictions.
Engineering twist
Conflict simulation applies two opposing forces simultaneously and finds the compromise basin via majority vote across noisy trials. Returns consistency rate, union/intersection membership, and reachability flags - useful for moral-dilemma modeling where two duties collide.
S/05
Inference
TieredInference · 3-tier fallback · 75% tier-0 hit
Smart query accelerator
Tier 0: graph lookup (instant, ~75% hit rate on reference network). Tier 1: short ODE rollout (20 steps, 81% accuracy). Tier 2: full ODE (500 steps, 100% accuracy). Auto-builds forced-query cache on first inference. Batch inference returns tier distribution and mean steps.
Engineering twist
The forced-query cache is not a naive memo - it pre-computes the top-K most connected forces per start basin using full dynamics, so tier-0 hits are grounded in real ODE outcomes, not heuristic guesses. Observed ~480x speedup on the 8-atom/60-pattern reference network at alpha=0.50.
S/06
Schedule
Force-schedule programs · non-commutativity verified
Sequential force execution engine
Executes sequences of (force, alpha, duration) steps. Each step runs dynamics for the specified duration, then hands the final state to the next step. Supports order-comparison (A→B vs B→A) with statistical consistency checks and novel-destination detection.
Engineering twist
Force schedules are provably non-commutative: the same two forces in different orders can land in different basins. The compare_orders() function exposes this with majority-vote consistency rates, making it a concrete test-bed for moral-dilemma sequencing where order matters.
S/07
Verifier
LLM reasoning chain validator · TF-IDF + cosine
Ground-truth checker for LLM outputs
Maps each step in an LLM reasoning chain to the nearest attractor basin via TF-IDF cosine similarity (sklearn or stdlib fallback), then checks whether consecutive transitions are topologically valid edges in the Atlas. Returns per-step color-coding (green/yellow/red), overall score, and verdict: VALID / PARTIAL / INVALID.
Engineering twist
The killer app of the engine. Instead of trusting an LLM's chain of thought, the verifier binds each step to a basin and checks if the claimed transition actually exists in the mapped topology. If the edge is absent, the step is flagged red - hallucination caught by geometry, not by another model.
S/08
Bridge
BridgeBuilder · edge synthesis · validate-before-apply
Topology extension
Suggests bridge patterns to create edges between disconnected basins. Validates by temporarily extending the pattern matrix and testing dynamics. Only applies permanently if the bridged rate improves the baseline by >10%.
Engineering twist
Bridges are not random vectors - they are weighted interpolations between source and destination patterns, sign-thresholded back into the bipolar space. This keeps new patterns compositional and maintains the network's semantic structure.
S/09
Explorer
Interactive HTML atlas · vis.js · standalone
Visual topology inspector
Generates a single self-contained HTML file with a force-directed graph visualization of the Atlas. Click-to-select start/goal basins, BFS route planning with path highlighting, basin info panel (in-degree, out-degree, energy), and alpha-level edge filtering. No build step, no server - open in any browser.
Engineering twist
The explorer is generated as a single string-interpolated HTML file with embedded vis.js CDN - zero dependencies, zero bundler. It ships inside the Python package as package data and opens via webbrowser module from the CLI.
S/10
API
FastAPI · LRU network cache · X-API-Key auth
REST control surface
FastAPI application with 9 endpoints: health, network creation (CSV upload), route planning, edge listing, reachability queries, schedule execution, tiered inference, chain verification, and an interactive demo page. LRU cache holds up to 10 networks with automatic eviction.
Engineering twist
CSV uploads are size-bounded at 10 MB, parsed into temporary files, and fed through from_data() with automatic atlas mapping. Basin name validation runs on every request - unknown basins return 422 with a sample of valid names, aiming to avoid silent failures.
[ H ] · Roadmap
What ships next.
The architecture leaves room for the next milestones on purpose. Each item below is named, scoped, and traceable to a design decision - not aspiration, planned work.
R/01 · Parallel mapping
Multiprocessing for atlas construction
The atlas mapper accepts an `n_workers` parameter today but falls back to sequential execution because Network objects contain lambdas and numpy Generators that cannot be pickled. The roadmap is to refactor the worker functions into top-level picklable callables and enable true parallel edge testing.
R/02 · Web interface
Browser-based network builder + planner
Today the explorer is a read-only visualization of a pre-mapped atlas. The planned web UI adds network creation from uploaded CSV/text, live route planning, and reasoning-chain verification through a browser form - no CLI required.
R/03 · Gita encoding
Bhagavad Gita structured rule-set integration
The engine's architecture is designed to encode moral and strategic dilemmas as force fields. The next milestone is a curated Gita chapter adapter that maps verses to attractor basins and dharmic tensions to opposing forces, producing verifiable reasoning paths through sacred text.
R/04 · Adapters
Supply-chain domain adapter
The incident-response adapter (`sg_engine/adapters/incident.py`, 10 states, 9 actions) and the manufacturing adapter (`sg_engine/adapters/manufacturing.py`, 8 states, 6 actions) both ship today. A supply-chain routing adapter - mapping logistics states and procurement actions to basins and forces - is not yet implemented.
R/05 · Persistence
MongoDB / PostgreSQL backend for network storage
Today networks are cached in memory with LRU eviction and saved to local NPZ/JSON files. The planned persistence layer stores networks, atlases, and verification histories in a database for multi-user access and audit trails.
[ I ] · In production
Three workloads. One geometry.
U/01
LLM hallucination detection - grounding chain-of-thought in topology.
A reasoning model outputs a 5-step argument. The verifier maps each step to a basin and checks edge validity. Step 3 claims a transition that does not exist in the Atlas - flagged red with confidence 0.0. The overall verdict drops to PARTIAL. The human reviewer knows exactly which inference is unsupported.
U/02
Incident recovery - shortest path from 'crashed' to 'healthy'.
The incident-response adapter encodes 10 system states and 9 recovery actions as basins and forces. When an alert fires 'crashed', the planner returns the shortest recovery path: crashed → recovering → degraded → healthy. If no direct path exists, it finds intermediate waypoints via reachable-set intersection.
U/03
Moral dilemma sequencing - does order matter?
Two forces represent competing duties. The schedule engine runs duty A then duty B, and duty B then duty A. The outcomes differ - the compare_orders() function reports same_outcome=false with consistency rates for each ordering. This is not opinion; it is a topological fact about the energy landscape.
Argument · io-gita
Probability generates sentences.
Topology decides whether they are true.
Next system
Back to all systems