Nexus KG Path: Automated Knowledge Graph Path Discovery Engine

A deterministic knowledge graph traversal engine for rare disease drug repurposing.

Status: Core pipeline (Davonte -> Muhammad -> Dennis -> Leviticus -> Alejandra) is real and wired end to end inside Octavius_Aurifaber, verified by real execution against real dependencies (NetworkX, DuckDB, RDKit, aiohttp). See HANDOFF_VERIFIED.md for the fix-by-fix verification history.

Core Thesis

• Deterministic multi-hop graph pathfinding: no LLM speculation, no probabilistic weights
• Ingest baseline knowledge graphs (ChEMBL, PubChem, Reactome, Open Targets) into memory (NetworkX)
• Validate compound SMILES and chemical properties (RDKit valency checks)
• Traverse graph to find paths from approved compounds to rare disease pathways (DFS + nx.shortest_path, capped at 10 results)
• Score paths deterministically (edge validation count x RDKit integrity x distance penalty)
• Persist paths and metadata to DuckDB, export to Snappy-compressed Parquet

Zero-Token Guarantee (non-negotiable): 100% deterministic execution. NetworkX graph logic, RDKit, DuckDB, aiohttp. No LLM calls anywhere in the execution pipeline.

---

Architecture

Active Agent Roster

Agent	Role	Status
Octavius Aurifaber (Manager)	Orchestration & routing	Real. _process_disease() wires the full pipeline end to end.
Davonte (Agent 1)	Signal ingestion	Real. CSV/Parquet loading + live PubChem/ChEMBL streaming via shared http_pool.
Muhammad (Agent 2)	Structural validation	Real. RDKit SMILES/valency/Lipinski checks. No-arg constructor -- no ProcessPoolExecutor yet (CPU-bound RDKit work is not yet offloaded via run_in_executor).
Dayton (Agent 3)	Live API orchestration	Real, working agent (circuit breakers, EMA trust scoring, shared http_pool) but not currently instantiated inside Octavius -- not part of the live pipeline.
Dennis (Agent 4)	Graph traversal	Real. DFS (find_paths_dfs) + nx.shortest_path, capped at 10 paths. No hub-degree capping, no bidirectional BFS.
Leviticus (Agent 7)	Deterministic scoring	Real. Multiplicative gate formula. Exact-match provenance validation. Confidence threshold can be overridden per DiseaseRequest, falling back to the Octavius-level default (0.65) when not set.
Alejandra (Agent 8)	Persistence & export	Real. DuckDB single-writer + Snappy Parquet export. Reports true post-dedup row counts.

Permanently cut: Kelly (LLM-based MOA synthesis -- violates the Zero-Token Guarantee), Titus Caupo (regulatory manager -- no regulatory gate needed for pure graph paths), Nicole (export formatting -- source was never uploaded to this project and is no longer imported anywhere). Redis was declared but never implemented, and has been removed from setup.py.

Data Flow

Octavius_Aurifaber.load_baseline_graph(csv_path=..., parquet_path=...)   [optional, once]
  |  caches self.baseline_nodes / self.baseline_edges via Davonte
  v
Octavius_Aurifaber.run(requests) -> asyncio.gather batches of _process_disease()
  |
  +-- Davonte: per-request CSV ingestion + live PubChem/ChEMBL streaming,
  |            combined with the pre-loaded baseline corpus
  |
  +-- Muhammad: RDKit validation, gates traversal -- only valid compounds proceed
  |
  +-- Dennis: DFS + nx.shortest_path, capped at 10 paths, graph reset per call
  |
  +-- Leviticus: multiplicative-gate scoring, exact-match provenance,
  |              per-request confidence_threshold override
  |
  +-- Alejandra: DuckDB insert + Snappy Parquet export

---

Multiplicative Gate Scoring

FinalScore = edge_validation_count x rdk_integrity x (1 - (graph_distance / max_hops))

• rdk_integrity (1.0 or 0.0): strict boolean multiplier -- any invalid compound drops score to 0
• edge_validation_count (0..N): scales by number of exact-matched high-confidence sources verifying edges
• Distance penalty: favors shorter, tighter pathways
• Confidence floor: 0.65 by default, overridable per DiseaseRequest.confidence_threshold

---

Installation & Quick Start

pip install -r requirements.txt
python run_engine.py

python -c "
import duckdb
conn = duckdb.connect('nexus_kg_path.duckdb')
print(conn.execute('SELECT * FROM paths LIMIT 5').fetchall())
"

---

Known Gaps (real, not hidden, not fixed)

• Dayton is a real, working agent but is never instantiated inside Octavius_Aurifaber.
• Muhammad's RDKit calls are still synchronous -- loop.run_in_executor(process_pool) offloading remains unimplemented.
• Dennis has no hub-degree capping, no bidirectional BFS.
• tests/ now exists with real regression coverage for the Edge default-id fix, the Leviticus provenance exact-match fix, the Leviticus/Dennis shared-instance state-reset fixes, and the Octavius empty-request contract. Not yet run against a live package install in this environment -- syntax-verified only.
• All six parked math modules (Spectral Partitioning, LSH, Hungarian Matching, Convex Optimization, FFT, Queueing Theory) remain parked. None target a mechanism that exists in the real code.

See HANDOFF_VERIFIED.md for the complete, execution-verified fix history and PROJECT_CONTEXT.md for the full working-principles reference.

License

Currently unlicensed. MIT license pending approval.