Tortus

The hard part of internal knowledge work is often not finding a relevant document. It is figuring out how several relevant documents connect.

In an incident review, the evidence might be split across an auth migration note, a gateway retry runbook, an observability guide, and the incident timeline. Search can find each fragment. A normal RAG answer can summarize the retrieved text. The painful part is still left to the user:

Tortus is built for that gap. It tries to answer “why did this happen?” or “what should we fix?” by returning the evidence path across documents, not only a list of matching chunks.

Most production RAG systems are strong at retrieving nearby text and weak at preserving relationships between ideas. That creates recurring failures:

A semantic graph embedded on a toroidal coordinate space can make retrieval more navigable by combining vector search for fast candidates, typed graph edges for explainable hops, toroidal locality for wraparound neighborhoods, GraphQL directives for developer-controlled traversal, and budget-aware synthesis over explicit evidence paths.

The torus is not treated as magic. It is a systems hypothesis to validate against measurable baselines — and replace if it does not hold.

Tortus is a complete, package-distributable RAG engine designed to run locally or integrate as a service. Two pipelines — ingest on the left, query on the right — meet at the graph and toroidal embedding.

Data model

At query time, Tortus follows a bounded retrieval plan:

1. Parse query intent, constraints, and GraphQL directives.
2. Generate seed candidates with ANN vector search.
3. Map candidates to graph nodes and toroidal coordinates.
4. Estimate local density around each seed.
5. Expand through typed edges using a density-aware radius.
6. Score frontier nodes with similarity, edge weight, freshness, evidence quality, and policy.
7. Trigger portal hops when frontier coverage is low or the query implies domain switching.
8. Select evidence paths under hop, latency, and token budgets.
9. Synthesize an answer only from selected evidence.
10. Return the answer, confidence, path, and degraded-mode warnings.

Traversal score

score(next) =
    semantic_similarity(query, next)
  + edge_weight(current, next)
  + evidence_quality(next)
  + freshness_bias(next)
  − traversal_cost(next)
  − uncertainty_penalty(next)

The exact scoring function is intentionally replaceable. Tortus is built to make retrieval policies easy to compare, not to hard-code one strategy.

A scale sweep over 10 public engineering sources (Kubernetes, OpenTelemetry, W3C, RFCs, the Google SRE book), split into source-preserving doclets at 50, 200, 500, and 1000 documents. At the 1000-doclet point, graph-aware strategies recovered labeled path structure that rank-only baselines did not.

Table 1 · Strategy at 1000 docs

Benchmark · 118 questions · 1,652 rows

Useful failure modes

• Weather or stock queries return “not enough source-backed evidence” rather than forcing a path.
• Broad incident queries can over-expand through portals if shared terms are too generic.
• Local-only graph policies can find sources but miss expected boundary-crossing labels.
• Layout-only probes can retrieve nearby nodes without proving a reasoning path.

1 · Install

# Python 3.12+
pip install tortus-rag

# optional extras
pip install "tortus-rag[baselines]"
pip install "tortus-rag[api]"

2 · Solve in one command

tortus solve "Why did this incident happen, and what should we fix?" \
  ./docs https://example.com/runbook

Creates a hidden local project under ~/.tortus/projects/, snapshots the supplied files & URLs, builds the graph and vector index, traverses the evidence path, and returns a cited diagnosis, the likely root-cause path, recommended actions, and missing-evidence warnings.

3 · Try the packaged demo

tortus ingest --corpus acme-payments-demo --data-dir .tortus/acme-demo
tortus index  --corpus acme-payments-demo --data-dir .tortus/acme-demo
tortus query "What should Acme fix to stop EU refund trace fragmentation?" \
  --corpus acme-payments-demo --data-dir .tortus/acme-demo --explain

4 · Open the dashboard

pip install "tortus-rag[api]"
tortus serve --port 8010
# → http://127.0.0.1:8010

5 · Or use it from Python

import tortus
from tortus.config import Settings
from tortus.pipeline import build_index, load_engine

settings = Settings(TORTUS_CORPUS="public-engineering")
build_index(settings)
engine = load_engine(settings)

result = engine.answer("How do service accounts connect to tracing?")
print(result.answer)
for hop in result.reasoning_path:
    print(f"{hop.from_node} --[{hop.edge_type}]--> {hop.to_node}")

• Make retrieval inspectable before making it clever.
• Treat LLMs as synthesis and policy helpers, not hidden databases.
• Return evidence paths for claims that cross concepts.
• Put budgets in the API, not only in deployment config.
• Prefer replaceable retrieval policies over one monolithic agent loop.
• Measure against boring baselines before adding exotic machinery.

Tortus is a fully functional v2, but the retrieval space is evolving rapidly. The roadmap is built to push the limits of multi-hop recall and scale the toroidal engine under extreme data pressure.

• Distributed graph sharding. Push beyond local memory toward partitioned graph databases (e.g. PostgreSQL + Apache AGE) so the toroidal policy scales to millions of nodes without latency degradation.
• Learned portal routing. Replace hand-tuned edge-weight thresholds with a lightweight portal router that dynamically optimizes cross-domain jumps from path-level user feedback.
• Streaming traversal paths. An async generator-based traversal engine that emits reasoning hops as they are visited, so client UIs can render live retrieval steps in real time.
• Adversarial benchmark suites. A benchmark family built specifically to break path retrieval — contradictory source claims, semantic decoy bridges, duplicate context blocks.
• Unified ingest connectors. Native connectors for enterprise sources (Postgres CDC, Notion, Confluence, Slack archives) under strict cryptographic provenance contracts.