valoricore 0.1.0

Deterministic Knowledge Graph & Vector Engine with Bit-Exact Audit Trails

Valoricore 🛡️

The Deterministic Knowledge Graph & Vector Engine with Bit-Exact Audit Trails

valoricore is the official Python SDK for the Valoricore Kernel. It provides a high‑performance, async-capable interface for applications where determinism and auditability are absolute requirements.

---

🔒 What Makes Valoricore Different?

• True Determinism – Fixed‑point arithmetic ensures identical results on x86, ARM, and RISC‑V, forever.
• Cryptographic Audit Trails – Every insert, update, and delete is logged. The BLAKE3‑based Merkle root proves the exact state at any point in time.
• Unified Graph + Vector – Seamlessly combine semantic search with structured knowledge graph relationships (nodes and edges).
• Embedded & Distributed – Run as a lightweight, embedded engine via FFI or scale to a multi‑node cluster.
• Zero‑Config – Vector dimensions and pool capacities are auto‑detected. No manual tuning required.

---

📦 Installation

Valoricore ships with a pre‑compiled native extension for most platforms. A Rust compiler is only required when building from source.

pip install valoricore

---

🚀 Quick Start

Local embedded engine

No server required – import and go.

from valoricore import Valoricore

# Create or open a local database
db = Valoricore(path="./my_knowledge_base")

# Insert a vector
record_id = db.insert(
    vector=[0.1, 0.2, 0.3, 0.4],   # any dimension
    tag=101
)

# Set binary metadata (up to 64KB)
db.set_metadata(record_id, b"{\"title\": \"Project Alpha\"}")

# Semantic search (with optional tag filter)
results = db.search(query=[0.1, 0.2, 0.3, 0.5], k=5, filter_tag=101)

# Get a cryptographic proof of the full state
state_hash = db.get_state_hash()

# --- Offline Verification ---
# You can verify an embedding's integrity WITHOUT the database running
from valoricore import verify_embedding
is_valid = verify_embedding(vector=[0.1, 0.2, 0.3, 0.4], claimed_hash="a3f8c2d1...")

# --- Auto-Snapshots ---
# Automatically take and save a snapshot to the db directory every 1,000,000 inserts
db.snapshot(auto_interval=1_000_000)

# --- Restoring from a Snapshot ---
# Read the binary file into memory, then pass the bytes to restore()
with open("valoricore_db/auto_snapshot_1000000.snap", "rb") as f:
    snapshot_bytes = f.read()
    
db.restore(snapshot_bytes)

Async support

For non‑blocking operations inside FastAPI or modern async applications, use the built‑in async factory:

from valoricore import AsyncValoricore

# Use AsyncValoricore for high-performance non-blocking I/O
db = AsyncValoricore(remote="http://localhost:3033")
results = await db.search(query=[...], k=10)

💡 The async client uses httpx and is fully compatible with asyncio event loops.

---

🧠 Key Abstractions

• Record – A vector with an optional tag (integer) and arbitrary binary metadata.
• Node – A higher‑level entity (e.g., “Document”, “User”) that wraps one or more records.
• Edge – A directed relationship between nodes (e.g., “parentOf”, “authoredBy”).
• Proof – A BLAKE3‑based Merkle inclusion proof that verifies a record’s presence in a given global state.

---

🔐 Cryptographic Determinism

Valoricore’s core engine performs all distance calculations in fixed‑point arithmetic (Q16.16). This guarantees that the same sequence of operations will produce the exact same score values, state hashes, and proofs—regardless of the hardware or operating system.

The global state hash is a single 32‑byte BLAKE3 Merkle root that represents the entire database.

---

📚 Documentation

• Getting Started Guide – Your first 5 minutes with Valoricore.
• API Reference – Complete method signatures, types, and error codes.

---

🛠 Forensic CLI

Valoricore comes with a powerful valori CLI tool that lets you inspect and replay the internal append-only event logs generated by your Python applications.

1. Installation

You can install the CLI globally from the source directory using Cargo:

cargo install --path crates/cli --force

2. Inspecting the Database

To run a deep forensic inspection of the Phase 23 Event Log and Snapshot generated by valoricore:

valori inspect --dir data/my_test_db --snapshot-path data/my_test_db/state.snap

3. Viewing the Event Timeline

To view a chronological breakdown of every single state transition (InsertRecord, CreateNode, CreateEdge, Checkpoint):

valori timeline data/my_test_db/events.log

---

Built with ❤️ by the Valoricore team – integrity‑first AI infrastructure.