Skip to main content
Glama

QuantaOptima

Tests License: Apache-2.0 OpenSSF Scorecard

Auditable AI Actions — cryptographic audit trails for AI agent workflows.

QuantaOptima authenticates explicitly logged AI agent action records. It ships as an MCP server that any LLM agent can call, and as a Python library that any MCP server developer can embed. Explicitly recorded actions are authenticated with HMAC-SHA256 and linked in a hash chain. Verification detects changes to authenticated record contents; it does not establish that an action occurred or that all actions were recorded.

pip install https://github.com/jdhart81/quantaoptima/releases/download/v0.4.0/quantaoptima-0.4.0-py3-none-any.whl

The package is distributed through GitHub Releases; it is not currently listed on PyPI.

Agents: start with llms.txt and AGENTS.md, which say what a verified chain does and does not show.

Release status and migration

Version 0.4.1 is an unreleased hardening candidate; v0.4.0 remains the latest published alpha. The MCP server persists its audit chain under ~/.quantaoptima/audit (override with QUANTAOPTIMA_AUDIT_DIR). Back up both the database and its private audit key. Imported JSON is unverified until checked with that key; HTML itself is not cryptographic evidence.

Paid licenses now use Ed25519. Existing HMAC licenses must be reissued, and clients need the issuer's trusted public PEM. No production issuer key is bundled in this checkout. See operations and migration, release notes, and security limitations.

Paid sales are disabled. The Pro and Enterprise tiers are previews until a production issuer public key, signed test-mode fulfillment, renewal delivery, durable storage, and customer activation have all been verified end to end.

Related MCP server: agent-gate

Why This Exists

Agent tracing tools help developers inspect workflow activity. QuantaOptima provides a local integrity layer for explicitly recorded actions: authenticate records, check the stored chain, and export it for inspection.

A valid chain authenticates recorded contents under its key; it does not prove actor identity, real-world execution, or completeness. Detecting a removed suffix requires an independent checkpoint. See the security model.

The MCP server exposes these operations:

  • quantaoptima_log_action — Log any action with before/after state to the audit chain

  • quantaoptima_verify_chain — Verify the HMAC-SHA256 chain integrity

  • quantaoptima_export_chain — Export the full audit trail as JSON

  • quantaoptima_chain_status — View chain statistics and health

Plus a built-in quantum-inspired optimizer that demonstrates the audit chain in action:

  • quantaoptima_optimize — Run optimization with every step automatically audited

  • quantaoptima_explain — Human-readable explanation of what the optimizer did

  • quantaoptima_benchmark — Compare against scipy's classical methods [PRO]

  • quantaoptima_observe — Inspect entropy, interference, phase transitions [PRO]

  • quantaoptima_audit — Verify the optimizer's audit trail [PRO]

What Makes It Different

1. Every Action Is Tamper-Evident

Every logged action produces an HMAC-SHA256 signature chained to the previous action. Modifying signed contents makes chain verification fail. This authenticates recorded data; it does not prove actions occurred, authenticate actor names, or detect a deleted suffix without an independent checkpoint. See the security model.

2. Built for AI Agents (MCP-Native)

Ships as an MCP server. After installing the package and configuring a compatible client, an agent can explicitly log actions, verify the chain, and export records. Other agent actions are not automatically captured merely because this server is connected.

3. Works as a Library Too

Other MCP server developers can embed QuantaOptima's audit chain in their own tools:

from quantaoptima import AuditChain, auditable

chain = AuditChain(scope="my-mcp-server")

# Log actions explicitly
chain.log("query", {"question": "What's the revenue?"}, {"answer": "$4.2M", "source": "db"})
chain.log("decision", {"options": ["A", "B"]}, {"chosen": "A", "reason": "lower risk"})

# Or use the decorator to auto-audit any function
@auditable(chain, action_type="calculation")
def compute_risk(portfolio: dict) -> dict:
    return {"risk_score": 0.42}

result = compute_risk({"stocks": ["AAPL", "GOOG"]})

# Verify and export
assert chain.verify()
chain.export_json("audit_trail.json")

4. Built-In Optimizer Demo

The quantum-inspired optimizer shows the audit chain at work. Every optimization step is explicitly recorded and cryptographically signed. This authenticates the recorded trace; it does not prove execution, completeness, or optimality.

  • Quantum-inspired Measurement-Collapse Pruner algorithm

  • Built-in interpretability: entropy trajectories, interference metrics, phase transitions

  • Six built-in benchmark objectives; convergence quality depends on the problem and budget

Quick Start

MCP Server (for Claude, GPT, or any MCP-compatible agent)

pip install https://github.com/jdhart81/quantaoptima/releases/download/v0.4.0/quantaoptima-0.4.0-py3-none-any.whl
quantaoptima-server

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "quantaoptima": {
      "command": "quantaoptima-server"
    }
  }
}

Then ask Claude:

  • "Log a decision to the audit chain: I chose option A because it had lower risk."

  • "Verify the audit chain and show me the status."

  • "Optimize the Rastrigin function in 10 dimensions, then verify the audit trail."

  • "Export the full audit chain to audit_trail.json."

Python Library (for MCP server developers)

from quantaoptima import AuditChain

# Create a chain for your server
chain = AuditChain(scope="my-server", actor="my-agent")

# Log any action
chain.log(
    action_type="api_call",
    state_before={"endpoint": "/users", "method": "GET"},
    state_after={"status": 200, "count": 42},
    metadata={"duration_ms": 150},
)

# Verify chain integrity
print(chain.verify())        # True
print(chain.summary())       # Stats and health
print(chain.verify_detailed())  # Per-block verification

# Export
chain.export_json("trail.json")

Decorator Pattern

from quantaoptima import AuditChain, auditable

chain = AuditChain(scope="data-pipeline")

@auditable(chain, action_type="transform")
def clean_data(raw: list) -> list:
    return [x for x in raw if x is not None]

@auditable(chain, action_type="analysis")
def compute_stats(data: list) -> dict:
    return {"mean": sum(data) / len(data), "count": len(data)}

# Both calls are automatically logged to the audit chain
clean = clean_data([1, None, 3, None, 5])
stats = compute_stats(clean)

assert chain.verify()
print(f"Audit trail: {len(chain)} blocks, verified")

Pricing

Community (Free)

Pro preview

Enterprise preview

Audit Chain

Unlimited

Unlimited + analytics

Custom

Log Actions

✓

✓

✓

Verify Chain

✓

✓

✓

Export Chain

✓

✓

✓

Optimizer Objectives

3

All 6

All + custom

Max Dimensions

10

100

Unlimited

Max Iterations

100

5,000

Unlimited

Benchmark vs scipy

—

✓

✓

Observability

—

✓

✓

Support

Community

Email

Priority + SLA

Availability

Install Free

Not for sale

Not for sale

Preview pricing is historical and not an active purchase offer.

How the Audit Chain Works

Action 1                    Action 2                    Action 3
┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│ action: "query"  │         │ action: "decide" │         │ action: "execute"│
│ before: {...}    │         │ before: {...}    │         │ before: {...}    │
│ after: {...}     │         │ after: {...}     │         │ after: {...}     │
│ sig: HMAC(       │──chain──│ sig: HMAC(       │──chain──│ sig: HMAC(       │
│   prev_sig +     │         │   prev_sig +     │         │   prev_sig +     │
│   data           │         │   data           │         │   data           │
│ )                │         │ )                │         │ )                │
└─────────────────┘         └─────────────────┘         └─────────────────┘

Each block's signature depends on the previous block's signature. Verification checks each block’s content signature, block number, and link to its predecessor. A content change fails verification. A key holder can re-sign history; completeness requires an independently retained checkpoint.

How the Optimizer Works

The built-in quantum-inspired optimizer runs a loop of four steps:

  1. Encode — Map population fitness to complex amplitudes via Boltzmann weighting

  2. Evolve — Apply three quantum-inspired operators: Rotation R(θ), Entanglement E(λ), Scrambling S(γ)

  3. Collapse — PCA-derived measurement basis + Born rule probabilities + entropy constraint = adaptive selection

  4. Audit — Every step is HMAC-SHA256 signed and hash-chained

Project Structure

quantaoptima/
├── audit.py           # Core: AuditChain, AuditBlock, @auditable decorator
├── core.py            # Quantum state encoder + evolution operators
├── mcp_algorithm.py   # Measurement-Collapse Pruner
├── optimizer.py       # Full optimizer orchestration
├── licensing.py       # Ed25519 license issuance and public-key verification
├── storage.py         # Durable SQLite audit chain and separate HMAC key
├── server.py          # MCP server (10 tools)

Patent Status

US Provisional Patent Application filed May 25, 2025. Covers:

  • Cryptographic audit trail for AI agent actions

  • Quantum-inspired optimization with measurement collapse

  • Entropy-constrained adaptive selection

  • Foundation model integration architecture

Citation

@software{hart2025quantaoptima,
  author = {Hart, Justin},
  title = {QuantaOptima: Auditable AI Actions},
  year = {2025},
  url = {https://github.com/jdhart81/quantaoptima}
}

License

Apache 2.0 — use it freely, including commercially. A U.S. provisional patent application was filed on May 25, 2025. Your rights to use this software, including patent rights, are those in LICENSE (Apache-2.0).

Available Tools

10 tools
quantaoptima_auditA

[PRO] Verify the cryptographic audit trail from the last optimization.

Each step is HMAC-SHA256 signed and hash-chained. Any tampering invalidates subsequent signatures.

Requires Pro license. Get one at https://buy.stripe.com/8x24gze0edtu1FwgSUfYY04

Args: export_path: Optional file path to export audit JSON.

Inputs: export_path. Returns: result

quantaoptima_benchmarkA

[PRO] Compare QuantaOptima against classical optimizers on the same problem.

Runs QuantaOptima, Differential Evolution, and Dual Annealing with the same evaluation budget. Returns side-by-side comparison.

Requires Pro license. Get one at https://buy.stripe.com/8x24gze0edtu1FwgSUfYY04

Args: objective: Built-in function (sphere, rastrigin, rosenbrock, ackley, griewank, levy). dimensions: Problem dimensionality (2-50). max_evals: Total function evaluation budget (1000-50000).

Inputs: max_evals, objective, dimensions. Returns: result

quantaoptima_chain_statusB

View audit chain statistics and health.

Shows the current state of the session's audit chain: how many actions are logged, verification status, action type breakdown, and actors.

Available on all tiers (Community, Pro, Enterprise).

Returns: JSON with chain statistics.

Inputs: no named parameters. Returns: result

quantaoptima_explainB

Human-readable explanation of the last optimization run.

Describes what happened, how quantum operators contributed, and whether the result is likely optimal.

Available on all tiers (Community, Pro, Enterprise).

Inputs: no named parameters. Returns: result

quantaoptima_export_chainA

Export the full audit chain as JSON or as an interactive HTML viewer.

The exported file contains every block with its HMAC-SHA256 signature, timestamps, before/after state, and chain linkage.

JSON exports can be independently verified by anyone with the HMAC key. HTML exports produce a self-contained interactive timeline that anyone can open in a browser — perfect for sharing with stakeholders, compliance officers, or collaborators.

Available on all tiers. Pro adds: advanced analytics and compliance reports.

Args: filepath: File path to save the export. If empty, returns data inline. For HTML format, use a .html extension (e.g., "audit_trail.html"). format: "json" (default) or "html" (interactive timeline viewer).

Returns: JSON with the exported chain data or confirmation of file save.

Inputs: format, filepath. Returns: result

quantaoptima_log_actionA

Log any action to the cryptographic audit chain.

Every logged action is HMAC-SHA256 signed and hash-chained to the previous action. Tampering with any entry invalidates the entire chain from that point forward.

Use this to make any AI agent workflow auditable:

  • Decisions and their reasoning

  • API calls and responses

  • File operations

  • Data transformations

  • Queries and answers

  • Tool invocations

Available on all tiers (Community, Pro, Enterprise).

Args: action_type: What happened (e.g., "query", "decision", "file_write", "api_call", "calculation", "approval"). state_before: JSON string of state/input before the action. state_after: JSON string of state/output after the action. metadata: JSON string of extra context (tags, parameters, etc.). actor: Who performed the action (default: "ai-agent").

Returns: JSON with block details including signature and chain position.

Inputs: action_type (required), actor, metadata, state_after, +1 more. Returns: result

quantaoptima_observeA

[PRO] Inspect the optimization landscape from the last run.

Returns interpretability data: how the optimizer explored the search space, where entropy concentrated, which dimensions carried the most information, and how interference shaped the selection trajectory.

This is the AI safety / interpretability tool — it reveals what the black-box optimizer is "thinking" by exposing its quantum measurement structure.

Requires Pro license. Get one at https://buy.stripe.com/8x24gze0edtu1FwgSUfYY04

Inputs: no named parameters. Returns: result

quantaoptima_optimizeA

Run quantum-inspired optimization using the Measurement-Collapse Pruner.

Uses interference-enhanced selection to solve black-box optimization problems with built-in cryptographic auditing and interpretability telemetry.

Every optimization step is automatically logged to the audit chain.

FREE tier: sphere, rastrigin, rosenbrock | 10 dims | 100 iters PRO tier: all 6 objectives | 100 dims | 5000 iters

Args: objective: Built-in function name (sphere, rastrigin, rosenbrock, ackley, griewank, levy). The optimizer MAXIMIZES, so built-ins are negated. dimensions: Number of variables (2-100). bounds_low: Lower bound for all variables. bounds_high: Upper bound for all variables. max_iterations: Maximum iterations (10-5000). population_size: Candidate solutions per iteration (10-200). temperature: Boltzmann temperature. Higher = more exploration. seed: Random seed for reproducibility.

Returns: JSON with best_solution, best_fitness, quantum_metrics, and audit status.

Inputs: seed, objective, bounds_low, dimensions, +4 more. Returns: result

quantaoptima_statusB

Check your QuantaOptima license status and available features.

Shows current tier, limits, available tools, and upgrade options.

Inputs: no named parameters. Returns: result

quantaoptima_verify_chainA

Verify the cryptographic integrity of the audit chain.

Checks every HMAC-SHA256 signature and hash link. If any block has been tampered with, verification fails from that point forward.

Available on all tiers (Community, Pro, Enterprise).

Args: detailed: If true, return per-block verification results.

Returns: JSON with verification status and chain statistics.

Inputs: detailed. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 10 tools

    Disambiguation3/5

    Most tools have distinct purposes, but there is real overlap between quantaoptima_verify_chain (verify chain integrity) and quantaoptima_audit (verify audit trail from last optimization), as well as between quantaoptima_chain_status and quantaoptima_status. Similarly, observe and explain both inspect the last run, which could cause misselection.

    Naming Consistency4/5

    All tools share the quantaoptima_ prefix and snake_case, which is predictable. There is minor mixing between verb_noun forms (log_action, verify_chain, export_chain, chain_status) and bare verbs (optimize, benchmark, observe, explain, audit, status), but it remains readable.

    Tool Count5/5

    10 tools is well within the ideal range and each earns its place, splitting cleanly between optimization (optimize, benchmark, observe, explain) and audit (log_action, verify_chain, export_chain, chain_status, audit) plus a license status check.

    Completeness4/5

    The optimization and audit lifecycles are well covered: run, compare, inspect, explain, log, verify, export, and report. Minor gaps exist around retrieving/listing past runs or re-inspecting older results, since observe/explain/audit only target the last run.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      An MCP server that enforces fail-closed deterministic checks, independent refute-first review, and tamper-evident hash-chained receipts for AI agent outputs before claiming completion.
      4
      3
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Tamper-evident audit logging for AI agents. Append-only, hash-chained, optionally Ed25519-signed log. The MCP server lets an agent keep and verify a record of what it actually did.
      8
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server providing immutable audit logging, policy enforcement, and compliance reporting for AI agent workflows, enabling regulatory compliance and chain integrity verification.
      1
      MIT