⚛️ QDB: Quantum-Inspired Deductive Database & RAG Fusion Architecture

QDB (qdb-ai) is the world's first Quantum-Inspired Database × RAG Fusion Engine.

It bridges the gap between structured relational databases, knowledge hypergraphs, and neural retrieval by reformulating knowledge deduction, state mutation, and factual consistency as a Physical Energy Minimization & Quadratic Optimization System (QUBO).

QDB replaces flat, stateless vector distance metrics and brittle graph traversals with an Energy-Based Stateful Deductive Hypergraph—delivering unbroken 15-hop causal reasoning, automatic contradiction suppression, and deterministic arithmetic in $< 50\text{ms}$ on standard CPU or GPU hardware with $0 cloud API billing.

🏛️ The Paradigm Shift: Why Database × RAG Fusion?

Standard Retrieval-Augmented Generation (RAG) pipelines suffer from critical structural bottlenecks:

⚡ Core Engine Architecture & Capabilities

1. 🗄️ Embedded Zero-Copy Footprint ($< 150\text{MB}$ RAM)

QDB is completely self-contained with zero external database dependencies (No Neo4j, No Qdrant, No Milvus, No Postgres, No JVM). It integrates an in-memory hypergraph tensor store coupled with a zero-copy memory-mapped SQLite engine, executing queries in sub-50 milliseconds while persisting millions of state transitions on disk.

2. 🧠 Domain-Adaptive Multi-Model Neural Ensemble

QDB embeds an automatic domain controller that detects the linguistic context of incoming text in $< 1\text{ms}$ and binds the optimal domain-specific neural backbone on the fly:

• Codebases & Software AST: microsoft/codebert-base (Call graphs, imports, class hierarchies)
• Financial Analysis & Filings: ProsusAI/finbert (SEC 10-Ks, revenue, capital allocations)
• Scientific & Biomedical Papers: allenai/scibert_scivocab_uncased (Clinical findings, molecular structures)
• Legal & Contractual Intelligence: nlpaueb/legal-bert-base-uncased (Compliance, clauses, covenants)
• General Factual Knowledge: bert-base-uncased (768-dim normalized semantic manifold)

3. 🛡️ Anti-Ferromagnetic Contradiction & Revocation Suppression

When facts mutate over time (e.g., an executive is terminated, security clearance is revoked, a contract is amended), standard vector DBs retrieve both old and new facts. QDB injects an explicit $+50.0\text{Joules}$ mathematical energy barrier between opposing states, mathematically forbidding stale, superseded, or contradictory facts from appearing in the verified answer.

4. ⏳ Point-in-Time Bi-Temporal Lineage (Time-Travel Engine)

Every knowledge state carries an immutable temporal validity interval $[t_{\text{valid_from}}, t_{\text{revoked_at}})$. Passing as_of_time=2021.0 dynamically masks subsequent mutations, reconstructing the exact state of reality at any historical timestamp without destructive database rollbacks.

5. 🔢 Deterministic AST Numeric & Financial Verification

To eliminate arithmetic hallucinations in financial balance sheets and engineering metrics, QDB pairs semantic nodes with an embedded Abstract Syntax Tree (AST) evaluator, guaranteeing $0.0%$ calculation errors.

6. 🛡️ In-VRAM Thermodynamic Logit Interceptor (+50J Shield)

A real-time GPU/CPU interceptor that monitors model token logits during generation, subtracting $+50.0\text{J}$ heat penalties from untruthful or hallucinated tokens and crushing false generation probabilities to $\le 1.9 \times 10^{-22}$.

📦 Installation

pip install --upgrade qdb-ai pypdf

🚀 Complete Quickstart Guide

1. Ingest Full Codebase & Query Architecture

Recursively parse AST hierarchies, functions, decorators, package manifests, and imports into relational hyperedges:

from qdb import Vault

vault = Vault("codebase_intelligence")

# Recursively ingest repository
report = vault.ingest_codebase("./src/")
print(f"Parsed {report['files_parsed']} files into {report['nodes_created']} AST nodes and {report['edges_created']} hyperedges.")

# Multi-hop transitive architectural query (<50ms)
res = vault.query("What modules depend on the database layer and what functions are called?")
print(res["answer_narrative"])

2. Multi-Hop Factual Knowledge & Contradiction Resolution

from qdb import Vault

vault = Vault("enterprise_vault", purge=True)

# Ingest stateful facts with timestamps and locations
vault.ingest("Dr. Aris Thorne was appointed Chief Cryptographer in 2021.", timestamp=2021.0, location="London")
vault.ingest("Project Hyperion constructed the antimatter confinement torus in 2021.", timestamp=2021.0, location="London")
vault.ingest("The antimatter torus stabilized the graviton field in 2022.", timestamp=2022.0, location="London")
vault.ingest("Dr. Aris Thorne was removed and his clearance was revoked in 2024.", timestamp=2024.0, location="London")

# 1. Multi-Hop Causal Lineage
ans1 = vault.ask("Trace the technological lineage from Dr. Thorne to the graviton field.")
print(ans1)

# 2. Contradiction Suppression (2021 clearance is suppressed automatically)
ans2 = vault.ask("Is Dr. Thorne currently an authorized Chief Cryptographer?")
print(ans2)

# 3. Point-in-Time Time Travel (Snapshot as of 2021)
ans3 = vault.ask("Who is the Chief Cryptographer?", as_of_time=2021.0)
print(ans3)

3. Full PDF Book / Document Ingestion

Ingest 200+ page books, SEC 10-Ks, or research papers in seconds with automatic paragraph vectorization:

from qdb import Vault

vault = Vault("baskervilles_vault", purge=True)

# Fast-ingest entire PDF book with live progress indicator
vault.ingest_file("baskervilles.pdf")

# Ask deep multi-hop deductive questions across the book
ans = vault.ask("Who was Jack Stapleton originally and what was his true motive regarding the Baskerville estate?", hops=5, budget=8)
print(ans)

# Export interactive force-directed HTML graph
vault.to_html("baskervilles_topology.html")

4. In-Memory SQL & OLAP Analytics Over Knowledge States

# Execute instant SQL aggregation queries over mirrored knowledge states
sql_res = vault.query("SELECT id, numeric_val, content FROM states_sql WHERE numeric_val > 1000 ORDER BY numeric_val DESC LIMIT 5")
print(sql_res["sql_results"])

5. In-VRAM Thermodynamic Logit Shield (+50J)

import torch
from qdb import Shield

shield = Shield()
shield.register_ground_truth(
    entity_name="JPMorgan",
    aliases=["JPMC", "$JPM"],
    truth_token_ids=[1042],
    statement="JPMorgan Chase acquired First Republic Bank on May 1, 2023."
)

raw_logits = torch.randn(1, 32000)
penalized_logits, intercepted, telemetry = shield.evaluate("Tell me about $JPM", raw_logits)
print(f"Interception Fired: {intercepted} | Layer: {telemetry['detection_layer']}")

6. Interactive Visual Graph Topology

# ASCII/Unicode terminal topology inspection
vault.show_graph()

# High-resolution force-directed network diagram (NetworkX + Matplotlib)
vault.draw()

💻 Command Line Interface (CLI)

# Ingest structured knowledge from terminal
qdb ingest "Astra Defense Systems was founded in Cambridge in 2018." --vault enterprise --location Cambridge

# Perform deductive queries directly from shell
qdb ask "When and where was Astra Defense Systems founded?" --vault enterprise

🔒 Enterprise Security & Air-Gapped Architecture

• 100% Local Execution: Runs entirely on local CPU/GPU hardware with zero outbound network calls.
• Multi-Tenant RBAC: Built-in Role-Based Access Control (Admin, Contributor, Viewer) with SHA-256 signed audit ledgers.
• Zero Telemetry: Fully private by default.

📄 License & Attribution

Distributed under the MIT License. Developed and maintained by Prannesshkva.

• PyPI: https://pypi.org/project/qdb-ai/
• GitHub: https://github.com/prannesshkva/qdb-quantum-studio