odin-engine 0.4.0

Graph intelligence that tells AI agents where to look next.

Multi-signal graph exploration for autonomous AI agents.

Paper • Documentation • PyPI • Quick Start

What is Odin?

Odin is an open-source Python library for navigating connected evidence in knowledge graphs. Given seed entities, it uses Personalized PageRank, bounded beam search, learned edge-plausibility scoring, and pattern aggregation to return ranked, inspectable paths. Odin navigates and ranks graph evidence; the consuming agent interprets that evidence, decides what is missing, and chooses the next seed or action.

Research: Odin is described in Odin: Multi-Signal Graph Intelligence for Autonomous Discovery in Knowledge Graphs by Muyukani Kizito and Elizabeth Nyambere, arXiv:2603.03097 (2026).

Odin-1 is the open-source edition of the Odin graph-intelligence engine, published by Prescott Data under the MIT license so the community can build on it.

Why Odin?

Knowledge graphs are powerful when you already know what you are looking for. You can write an AQL, Cypher, or SPARQL query for a known relationship. But autonomous agents face a different question:

Given these entities, where should I investigate next?

Answering it by traversal alone fails in three ways:

1. Combinatorial Path Growth - Multi-hop exploration in densely connected graphs grows combinatorially, producing large numbers of candidate paths, most of which are irrelevant to the investigation
2. Semantic Invalidity - Naive traversal follows edges that violate domain logic (e.g., Patient → diagnosed_by → Medication)
3. No Prioritization - Without ranking, agents waste turns analyzing low-value paths while missing critical patterns

Where common approaches fall short:

• BFS/DFS: Exponential explosion, no signal filtering
• Fixed Cypher Queries: Only finds patterns you already know exist
• Random Walks: Stochastic exploration can spend budget on low-value regions without task-aware ranking
• LLM Prompting Alone: Hallucinates relationships, can't verify graph structure

Odin treats graph exploration as a ranking problem:

The engine ranks connected evidence. The agent decides what that evidence means.

How Odin Works: COMPASS

At the center of Odin is COMPASS (Composite Oriented Multi-signal Path Assessment), the scoring framework introduced in the Odin research paper. Beam search keeps exploration bounded; COMPASS decides which candidate paths survive each hop.

After ranking, aggregators summarize recurring relationship sequences (motifs), relation shares, and a 0-100 triage signal that helps an agent decide what to inspect next. Signals that are not active for a deployment are reported as inactive in the result rather than silently defaulted.

See Odin Navigate Connected Evidence

This observed run uses Odin 0.3.0 with a synthetic insurance graph containing 66 entities and 190 recorded relationships. Claim 1042 is the selected seed.

The request asked for 12 paths, a 10-hop limit, and a beam width of 32. Odin's adaptive pass returned 24 ranked paths with an effective 4-hop limit and beam width of 64. One retained route connects:

Claim 1042
-> submitted_by -> Ana Torres
-> owns_vehicle -> Vehicle V-204
-> serviced_at -> Central Repairs

The interface labels requested and effective bounds, shows inactive signals as inactive, and traces every edge in the selected path to a source record. The complete raw result is preserved in the canonical run artifact. This is a deterministic demonstration dataset, not a scale or accuracy benchmark. Odin ranks the connected evidence; the consuming agent or investigator interprets it and chooses the next action.

Quick Start

Upgrading from 0.3.0? The engine now takes an explicit backend. Follow the backend migration guide when upgrading existing code.

Installation

pip install "odin-engine[arango]"

Requirements:

• Python 3.9+
• ArangoDB 3.10+ with a populated knowledge graph (reference backend)
• PyTorch 2.0+ (for NPLL)

The example below assumes that the referenced entity IDs already exist in your graph. Follow the Getting Started guide for local ArangoDB setup and data-model requirements.

Minimal Integration

from arango import ArangoClient
from odin import OdinEngine
from odin.backends.arango import ArangoBackend, ArangoGraphConfig

# 1. Connect to your knowledge graph
client = ArangoClient(hosts="http://localhost:8529")
db = client.db("my_database", username="user", password="pass")

# 2. Map your graph, then initialize Odin (auto-trains NPLL on first run)
graph = ArangoGraphConfig(
    node_collection="CaseRecords",
    edge_collection="EvidenceLinks",
    relation_field="predicate",
)
backend = ArangoBackend(db, graph)
engine = OdinEngine(backend)

# 3. Explore from seed entities
result = engine.retrieve(
    seeds=["CaseRecords/claim_123", "CaseRecords/provider_456"],
    max_paths=50,
    hop_limit=3,
)

# 4. Access scored paths
print(f"Found {len(result['paths'])} paths")
print(f"Triage Score: {result['triage']['score']}/100")

for p in result['paths']:
    edges = p['edges']
    nodes = [edges[0]['u'], *(e['v'] for e in edges)] if edges else []
    print(f"  [{p['score']:.2f}]", " -> ".join(str(n) for n in nodes))

Output Example (illustrative; your IDs, counts, and scores will differ):

Found 47 paths
Triage Score: 87/100
  [0.94] CaseRecords/claim_123 -> CaseRecords/provider_456 -> CaseRecords/audit_07
  [0.89] CaseRecords/claim_123 -> CaseRecords/sepsis_dx -> CaseRecords/nursing_home_cluster
  [0.82] CaseRecords/provider_456 -> CaseRecords/medication_999 -> CaseRecords/patient_history

Use Odin with a coding agent

Odin ships skills that teach coding agents (GitHub Copilot, Claude Code, Cursor and others) the API installed on your machine. Install Odin first, then from your project root:

odin init --skill

The skills come from the installed package, so they always match its version. Re-run the command after upgrading Odin; files you edited are kept and reported. See AI editor setup.

Automatic NPLL Lifecycle

Odin automatically manages its NPLL model lifecycle:

1. First Run: Extracts edge patterns from your graph and trains the NPLL model
2. Stores Weights: Saves learned parameters in ArangoDB collection (NPLLWeights)
3. Subsequent Runs: Loads weights from the database and rebuilds the model

For the default setup, Odin manages training and weight persistence without requiring a separate model-serving pipeline.

What Agents Get Back

Every retrieve() call returns ranked paths with per-edge provenance, plus aggregates an agent can act on (see the Result Schema for the full shape):

{
    "topk_ppr": [...],
    "paths": [
        {
            "id": "path_0",
            "score": 0.94,
            "edges": [
                {"u": "entity/A", "v": "entity/B", "relation": "billed_by",
                 "confidence": 0.89, "created_at": "...", "provenance": {...}}
            ]
        }
    ],
    "insight_score": 0.82,
    "aggregates": {
        "motifs": [{"pattern": "billed_by->flagged_in", "edge_count": 12, "path_count": 6}],
        "relation_share": {"billed_by": {"count": 42, "share": 0.42}},
        "summary": {...}
    },
    "triage": {"score": 87, "components": {...}, "dominant_relation": {...}}
}

Beyond retrieve(), the engine exposes companion capabilities: edge plausibility scoring, anchor discovery, motif aggregates, and runtime schema introspection, summarized in API at a Glance and fully documented on the docs site.

Research

📄 Odin: Multi-Signal Graph Intelligence for Autonomous Discovery in Knowledge Graphs

Muyukani Kizito · Elizabeth Nyambere

Prescott Data · 2026

arXiv:2603.03097 · DOI: 10.48550/arXiv.2603.03097

The paper introduces:

• the autonomous knowledge-graph discovery problem: surfacing meaningful patterns from seed entities without specifying the target pattern in advance;
• the COMPASS multi-signal path scoring framework;
• NPLL used as a discriminative filter over existing graph relationships rather than a generative model;
• bridge-entity and community-affinity guidance for the "echo chamber" problem in dense graph communities;
• bounded beam-search exploration with O(b·h) complexity relative to exhaustive traversal; and
• provenance-preserving exploration for regulated environments.

See Citation to cite the paper or the software.

Architecture

Odin turns seed entities into ranked, inspectable graph evidence:

Odin navigates and ranks connected evidence. The consuming agent interprets the returned paths and either acts on them or selects another seed for retrieval.

Component Details:

Illustrative Use Cases

The entity IDs and outputs below are illustrative, not measured results.

1. Healthcare Fraud Detection

Scenario: Find providers billing unusual procedure combinations

from dataclasses import replace

scoped_graph = replace(graph, membership_collection="Memberships",
                       membership_entity_field="entity_id", membership_community_field="community_id")
engine = OdinEngine(ArangoBackend(db, scoped_graph), community_id="medicare_claims",
                    community_mode="mapping")
result = engine.retrieve(
    seeds=["CaseRecords/high_volume_clinic"],
    max_paths=100,
)
# Illustrative: Odin surfaces recurring procedure-combination motifs

2. Supply Chain Risk Analysis

Scenario: Identify cascading supplier dependencies

result = engine.retrieve(
    seeds=["supplier/critical_vendor"],
    hop_limit=5,  # Deep supply chain exploration
)
# Illustrative: surfaces multi-hop dependencies on downstream products

3. Regulatory Compliance Checks

Scenario: Validate entity relationships against compliance rules

score = engine.score_edge(
    "entity/investment_fund",
    "managed_by",
    "entity/sanctioned_entity",
)
if score > 0.5:
    compliance_agent.flag_for_review()

Documentation

API at a Glance

from odin import OdinEngine
from odin.backends.base import GraphBackend

engine = OdinEngine(
    backend: GraphBackend,             # Graph access and optional NPLL capabilities
    community_id: str = "global",      # Scope for exploration
    cache_size: int = 5000,            # LRU cache size
    auto_train: bool = True,           # Auto-train NPLL if needed
    community_mode: str = "none"       # "none" | "mapping"
)

Full parameter and result documentation lives in the API reference.

Performance

Runtime depends on graph density, database latency, retrieval bounds, cache state, and whether NPLL weights are already available. The repository includes performance and memory regression tests in tests/performance and benchmark utilities in benchmarks. Publish workload-specific measurements with the dataset, parameters, hardware, and Odin version used.

Testing

# Run all tests
pytest tests/ -v

# Unit tests only
pytest tests/unit/ -v

# Integration tests
pytest tests/integration/ -v

# With coverage report
pytest tests/ --cov=odin --cov=npll --cov=retrieval --cov-report=html

Contributing

We welcome contributions! Areas of interest:

• Scalability: Large-graph benchmarking and optimization
• Algorithms: Alternative PPR implementations, new aggregators
• Database Support: Neo4j, Neptune adapters
• Benchmarks: Academic dataset comparisons

License

MIT License - see LICENSE for details.

Authors

Prescott Data

• Muyukani Kizito - Lead Engineer
• Elizabeth Nyambere - NPLL & GNN Research

Citation

If Odin contributes to your research, please cite the paper:

@article{kizito2026odin,
  title={Odin: Multi-Signal Graph Intelligence for Autonomous Discovery in Knowledge Graphs},
  author={Kizito, Muyukani and Nyambere, Elizabeth},
  journal={arXiv preprint arXiv:2603.03097},
  year={2026},
  doi={10.48550/arXiv.2603.03097}
}

To cite the software implementation specifically:

@software{odin_engine,
  title={Odin: Graph Intelligence for Autonomous AI Agents},
  author={Prescott Data},
  year={2026},
  url={https://github.com/Prescott-Data/Odin-1}
}

Links

• PyPI Package
• Documentation
• GitHub Repository
• Prescott Data