graqle

<div align="center">

<img alt="GraQle — Query your architecture. Prove your AI's decisions." src="https://raw.githubusercontent.com/quantamixsol/graqle/master/assets/hero-dark-hq.png" width="800">

# GraQle — query your architecture, prove your AI's decisions

> Index any codebase as a knowledge graph so AI agents reason about **architecture** instead of grepping files. Every decision they make — at build-time or in production — gets a cryptographic receipt anchored to a public transparency log. One Python package, two surfaces: **dev intelligence** for engineers, **runtime governance** for regulators.

[![PyPI](https://img.shields.io/pypi/v/graqle?color=%2306b6d4&label=PyPI)](https://pypi.org/project/graqle/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-06b6d4.svg)](https://python.org)
[![LLM Backends](https://img.shields.io/badge/backends-14-06b6d4.svg)]()
[![Model Agnostic](https://img.shields.io/badge/model-agnostic-06b6d4.svg)]()
[![EU AI Act–aligned](https://img.shields.io/badge/EU%20AI%20Act-aligned-22c55e.svg)](./docs/compliance/eu-ai-act/)
[![Patent-pending](https://img.shields.io/badge/patent-pending%20EP26167849.4-7c3aed.svg)](#patent--license)

```bash
pip install graqle
```

[Website](https://graqle.com) · [Quickstart](#90-second-quickstart) · [Runtime governance](#run-time--attach-governance-to-a-deployed-ai-in-one-line) · [EU AI Act docs](./docs/compliance/eu-ai-act/) · [Changelog](./CHANGELOG.md) · [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=graqle.graqle-vscode)

<!-- mcp-name: io.github.quantamixsol/graqle -->

</div>

---

## Two surfaces, one substrate

|  | **Build-time** (dev intelligence) | **Run-time** (production governance) |
|---|---|---|
| Governs | how your AI **writes code** | what your deployed AI **decides** |
| Trigger | a code change | a production decision (loan, hiring, triage, …) |
| Emits | reviewed, impact-analysed, audit-logged changes | a tamper-evident, third-party-verifiable record per decision |
| Built on | typed code knowledge graph + multi-agent reasoning | Layer 5 cryptographic substrate (RFC 8785 JCS → RFC 6962 Merkle → ed25519 → Sigstore Rekor) |
| Status | **GA** | **GA** — `attest()` capture (v0.60.0) + FastAPI middleware / `@governed` (v0.61.0) + continuous anchoring worker `graqle govern serve` (**v0.62.0**) |

> **Build-time governance proves *we hold ourselves to this standard* — GraQle is developed through its own governance. Run-time governance lets you hold *your deployed AI* to the same cryptographically-verifiable standard. Same substrate, both surfaces.**

---

## 90-second quickstart

### Build-time — query your codebase as a graph

```bash
# 1. Scan any codebase into a knowledge graph
graq scan repo .
# → typed graph: functions, classes, modules, imports, calls — full architecture mapped in seconds

# 2. Ask GraQle to audit it
graq run "find every authentication bypass risk"
# → Graph-of-agents activates across relevant nodes
# → Traces cross-file attack chains the LLM alone cannot see
# → Returns: confidence score + evidence trail + active nodes + tool hints

# 3. Fix it — GraQle shows exact before/after for each file (governed)

# 4. Teach it back — the graph never forgets
graq learn "cancel endpoint must require admin auth"
# → Lesson persists. Every future audit activates this rule.
```

### Run-time — attach governance to a deployed AI in one line

```python
from graqle.governance.runtime import GovernedRuntime

gov = GovernedRuntime(salt="your-deploy-salt")

def score_application(app):
    decision = model.predict(app)                # your deployed AI, untouched
    gov.attest(                                  # <-- the one added line
        domain="loan", model_id="credit-risk-v4",
        inputs={"applicant_ref": gov.pseudonymize_ref(app.id)},   # PII-safe
        output={"decision": decision.label, "reason_code": decision.reason},
    )
    return decision
```

Each call produces a durable, PII-safe governed record. Its leaf hash is computed with the same shipped primitive the build-time batcher uses, so a runtime record is byte-compatible with the cryptographic substrate (RFC 8785 JCS → RFC 6962 Merkle → ed25519 → Sigstore Rekor). Capture is out-of-band — it adds **0 ms to your write path**.

See [`examples/runtime_attest_production_decisions.py`](./examples/runtime_attest_production_decisions.py) and [`examples/runtime_govern_serve_anchoring.py`](./examples/runtime_govern_serve_anchoring.py).

### Run it as a continuous service (v0.62.0)

```bash
# Long-lived anchoring worker — flushes batches + drains the replay queue every tick
graqle govern serve --config graqle.yaml

# Cron-style one-shot tick (single flush + single replay-drain)
graqle govern serve --once

# Article-72-style monitoring snapshot — JSON suitable for any external monitor
graqle govern health
# → { "running": true, "ticks": 47, "records_anchored": 3120, "replay_queue_depth": 0, ... }
```

The serve loop writes `.graqle/govern.health.json` atomically after every tick — pipe it into your existing monitoring (Prometheus, Datadog, an oncall dashboard, a simple curl).

> **Independently verifiable, by anyone.** Committed batches anchor to the public Sigstore Rekor transparency log. Any third party can verify a record — auditor, regulator, counter-party — **without access to your infrastructure, or ours.** Verification doesn't depend on Quantamix staying online.

---

## 💰 Token economics — a worked case study

A 4-developer team on a 50,000-node enterprise codebase **burns ~$40 per developer per day** on flat-file AI-coding tokens in 2026. The same team using GraQle's substrate:

| Scenario | Annual (4 devs) | Saving |
|---|---|---|
| Flat-file baseline (Cursor / Claude Code default) | **$42,240** | — |
| GraQle + frontier API (Sonnet 4.6) | **$19,874** | **−53%** |
| GraQle + local SLM (Year 2, 90% migrated) | **$5,174** | **−88%** |

Every number is auditable. Every assumption is sourced (Anthropic pricing, Cursor power-user data, Microsoft's killed Claude Code pilot, NCBI biomedical-KG research showing >50% token reduction, Qwen3-Coder SWE-Bench benchmarks). Scale linearly to a 40-developer enterprise: **~$224k/year saved in Year 1, ~$371k/year in Year 2**.

Plus six things Cursor / Copilot / Codex do not offer at any subscription tier: cryptographic audit trail, EU AI Act Article 26 readiness (€15M fine exposure), patent-defensible substrate, survive-vendor-disappearance, multi-agent governance, public Sigstore Rekor anchoring.

→ **[Read the full case study](./docs/case-study-token-economics.md)** — math, sources, and a `bash` snippet to re-run it on your own team's numbers.

---

## What is GraQle

A **governance-led multi-agent reasoning system for code**, with a built-in cryptographic audit substrate for the AI you ship to production. Scan any codebase into a persistent knowledge graph. Every module becomes a reasoning agent. Agents decompose, debate, and synthesize answers with clearance-level governance. Every change — and every production decision — is impact-analysed, gate-checked, and cryptographically committed.

> *AI assistants see files. GraQle sees architecture. That's why it catches the cross-file bugs they can't, and why its audit trail survives every level of tampering.*

**Built for engineering teams who need:**

- **Cross-file reasoning** — impact analysis, lesson recall, dependency-aware refactor (the kind of thing that requires reading 5 files; we read the graph instead).
- **Auditable AI decisions** — confidence scores, evidence trails, tamper-evident logs anchored to a public transparency log.
- **EU AI Act–aligned behaviour out of the box** — for European customers, regulated deployments, and analyst-grade due diligence.
- **Model-agnostic operation** — 14 LLM backends, offline-capable via Ollama, runs entirely on your machine by default. No telemetry. Code stays on your machine.

---

## How it works

1. **Scan** → AST + dependency analysis builds a typed graph (functions, classes, modules, imports, calls).
2. **Activate** → A pre-reasoning safety layer scores each node for relevance, confidence, and risk **before** the LLM runs.
3. **Reason** → Multiple agents debate. Outputs carry `confidence`, `graph_health`, `active_nodes`, evidence pointers.
4. **Gate** → Governance gates (CG-01..CG-20) intercept write-class operations. Plans required. Risks surfaced. Trade-secret + path-traversal hardening enforced.
5. **Audit** → Every tool call is logged to `.graqle/governance/audit/` with redaction + secret scanning.
6. **Commit** → For runtime decisions, the audit record gets canonicalised (RFC 8785), Merkle-rooted (RFC 6962), ed25519-signed, and anchored to the public Sigstore Rekor log.
7. **Learn** → Lessons become weighted edges. The graph remembers across sessions, teams, and git operations.

The pipeline runs through five named phases — **ANCHOR → ACTIVATE → GENERATE → VALIDATE → COMMIT**. Each phase is governance-gated, evidence-attached, and audit-logged.

API defaults: `confidence_threshold=0.65` (refusal floor), `gate_threshold=0.60` (gate-status floor). Both are configurable per-call.

---

## Model agnostic

Anthropic · OpenAI · AWS Bedrock · Ollama · Gemini · Groq · DeepSeek · Together · Mistral · OpenRouter · Fireworks · Cohere · Azure OpenAI · custom HTTP.

```yaml
# graqle.yaml — smart task routing
backends:
  reasoning:  anthropic/claude-sonnet-4-6   # quality work
  embedding:  bedrock/titan-v2              # cheap + fast
  summaries:  ollama/llama3                 # local + free
```

Runs **fully offline** with Ollama. No telemetry. Code stays on your machine. API keys stay in your local `graqle.yaml`.

---

## Governance gate — drop-in for Claude Code, Cursor, VS Code

```bash
graq init              # sets up a governed project (writes the constitution → CLAUDE.md)
graq gate-install      # one-time, project-local — enforce it for Claude Code
```

**`graq init` writes the GraQle constitu