# Purple8 Hyper Graph (v0.72.0) — AI Agent & Developer Reference (llms.txt)

> **AI-Native Execution Infrastructure.** Built for AI, Operated by AI and Supervised by Humans.
> **Read · Remember · Reason · Answer · Run · Protect · Prove** — One Engine built to solve complex problems.

Purple8 Hyper Graph (`https://docs.graph.purple8.ai`) is an in-process, multi-model AI execution engine (Property + Hyper + Temporal Graph, Semantic Vector Search, Document & Structured Table Store, Full-Text Search, Hybrid GraphRAG, Stateful Journey Workflows with SLAs & HITL Gates, AES-256-GCM KMS, 4-Tier RBAC, and Autonomous SOC Containment) shipped as a single container.

---

## 1. Connect an AI Agent Over MCP (Zero Backend Glue Code)

Purple8 exposes **125 MCP tools across 16 namespaces** natively on `/mcp` (Streamable HTTP, MCP 1.x) and `/mcp/sse` (SSE). Both endpoints accept `X-API-Key: <key>` or `Authorization: Bearer <token>` (including Sandbox keys).

### Focused MCP Tool Profiles (`?profile=`)
To keep agent context windows fast and focused, append `?profile=` to the MCP URL (or send `X-MCP-Profile`):
- **`?profile=starter` (22 tools):** Recommended default for Claude Desktop, Cursor, and rapid app building (`rag.query`, `rag.hybrid_query`, `rag.profile_collection`, core `graph.*` CRUD/search/traverse, `data.ingest_text`, `data.ingest_file`, and `journey.*` workflows + HITL).
- **`?profile=builder` (72 tools):** All Starter tools + `schema.*`, `memory.*`, `models.*`, `egress.*`, `scheduler.*`, `feedback.*`, and `registry.*`.
- **`?profile=ops` (33 tools):** Operational monitoring, `journey.*`, `sentinel.*`, `guardrails.*`, `feedback.*`, and `admin.*`.
- **`?profile=full` (125 tools):** All 16 namespaces including `quantum.*` and `evolution.*`.

### Client Configurations
```bash
# Claude Code CLI
claude mcp add --transport http purple8 "https://<your-host>/mcp?profile=starter" \
  --header "X-API-Key: <your-api-or-sandbox-key>"
```

```json
// Cursor (.cursor/mcp.json) or Claude Desktop
{
  "mcpServers": {
    "purple8-graph": {
      "url": "https://<your-host>/mcp?profile=starter",
      "headers": { "X-API-Key": "<your-api-or-sandbox-key>" }
    }
  }
}
```

---

## 2. How an AI Agent Builds a Complete Application (5-Step Playbook)

1. **Model the Schema (`schema.*`):**
   - `schema.define_node_type(type_name="Applicant", properties={"name": {"type": "string", "required": true}, "risk_score": {"type": "number"}})`
   - `schema.define_edge_type(type_name="APPLIED_FOR", source_node_types=["Applicant"], target_node_types=["Loan"])`
2. **Ingest Knowledge & Documents (`data.*` & `graph.*`):**
   - `data.ingest_text(text="...", source_name="policy-v1")`
   - `data.ingest_file(url="https://.../packet.pdf", source_name="kyc-packet", profile_hint="financial")`
   - `graph.add_node(node_id="app:101", type="Applicant", properties={"name": "Acme Logistics", "risk_score": 0.12})`
   - `graph.add_edge(source_id="app:101", target_id="loan:501", edge_type="APPLIED_FOR")`
3. **Profile & Query with Hybrid GraphRAG (`rag.*`):**
   - `rag.profile_collection()` → returns topology class and recommended `fusion_alpha`, `max_hops`, `seed_k`
   - `rag.hybrid_query(question="What are the compliance risks for Acme Logistics?", mode="balanced", max_hops=2)`
4. **Define & Run Stateful Workflows with SLAs & HITL Gates (`journey.*`):**
   - `journey.define(journey_type="loan_approval", stages=[{"name": "submitted", "sla_warn_seconds": 3600}, {"name": "underwriting", "sla_breach_seconds": 86400}, {"name": "approved"}])`
   - `journey.start(journey_type="loan_approval", entity_id="app:101")`
   - `journey.advance(instance_id="...", to_stage="underwriting", notes="KYC passed")`
   - `journey.list_hitl(status="pending")` / `journey.resolve_hitl(task_id="...", action="complete", actor="officer@bank.com", decision="approved")`
5. **Automate & Govern (`scheduler.*`, `egress.*`, `sentinel.*`, `guardrails.*`):**
   - `scheduler.add_trigger(...)` for cron or event/drift-triggered actions
   - `egress.add_sink(...)` for HMAC-signed outbound webhooks
   - `sentinel.list_findings()` for self-tuning drift & risk proposals (human approval required to apply)

### Critical Tool Rules for AI Agents
- `graph.add_node` takes `type` (singular string label, e.g. `"Person"`), NOT `labels` (array).
- Always call `journey.define` before `journey.start` for a new `journey_type`.
- In `rag.hybrid_query`, `fusion_alpha` overrides `mode` — pass one or the other.
- Tools marked `human_only=True` (`schema.delete_node_type`, `graph.retract_statement`, `admin.smtp_configure`, `admin.retention_delete`) cannot be executed by API-key agents; surface them to a human operator.

---

## 3. Complete 16-Namespace MCP Tool Catalog (125 Tools)

- **`rag.*` (6):** `query`, `graph_query`, `hybrid_query`, `profile_collection`, `tune_collection`, `rerank`
- **`graph.*` (28):** `labels`, `counts`, `query`, `semantic_query`, `assert_statement`, `retract_statement` *(human_only)*, `import_nquads`, `vector_search`, `hybrid_search`, `traverse`, `add_node`, `get_node`, `update_node`, `delete_node` *(human_only)*, `add_edge`, `get_edge`, `delete_edge`, `edges_exist`, `pagerank`, `communities`, `centrality`, `link_prediction`, `shortest_path`, `poll_changes`, `wait_for_changes`, `auto_config`, `morans_i`, `local_morans_i`
- **`data.*` (10):** `ingest_text`, `ingest_file`, `commit`, `replace_file`, `patch_file_properties`, `list_file_versions`, `get_table`, `link_table_rows`, `index_table_columns`, `query_table_rows`
- **`journey.*` (9):** `define`, `list`, `start`, `advance`, `status`, `sla_alerts`, `list_hitl`, `resolve_hitl`, `audit`
- **`schema.*` (12):** `get`, `define_node_type`, `get_node_type`, `update_node_type`, `delete_node_type` *(human_only)*, `list_node_types`, `define_edge_type`, `get_edge_type`, `update_edge_type`, `delete_edge_type` *(human_only)*, `list_edge_types`, `validate`
- **`memory.*` (2):** `history`, `search`
- **`registry.*` (6):** `list_tools`, `register_tool`, `register_mcp_server`, `register_a2a_agent`, `remove_tool`, `test_tool`
- **`models.*` (7):** `list`, `search_known`, `upsert`, `remove`, `get_policy`, `set_policy`, `route_explain`
- **`egress.*` (4):** `add_sink`, `list_sinks`, `remove_sink`, `status`
- **`feedback.*` (4):** `open`, `record`, `resolve`, `summary`
- **`scheduler.*` (4):** `add_trigger`, `list_triggers`, `remove_trigger`, `status`
- **`quantum.*` (8):** `anneal`, `optimize`, `simulate`, `encode_state`, `measure`, `vqe_step`, `compare`, `profile`
- **`evolution.*` (8):** `create_experiment`, `list_experiments`, `propose`, `suggest`, `report`, `production`, `rag_retrieval`, `routing_policy`
- **`sentinel.*` (5):** `summary`, `list_findings`, `get_finding`, `reject`, `drift_check`
- **`guardrails.*` (1):** `evaluate`
- **`admin.*` (11):** `smtp_status`, `smtp_configure` *(human_only)*, `audit_verify`, `recovery_status`, `hold_place`, `hold_release`, `hold_list`, `retention_set`, `retention_list`, `retention_sweep`, `retention_delete` *(human_only)*

---

## 4. Verified Single-Node Benchmarks (October 2026)

| Workload / Metric | Measured Result | Notes |
|---|---|---|
| **Single-Node Scale Ceiling** | **20,000,000 nodes + 30,000,000 edges (50M objects)** | Single 16-vCPU cloud node · `~42.3 GB` RAM · `25.35 GB` NVMe |
| **Point Node Lookup (`get_node`) @ 20M** | **52.0 µs P50** · **106.0 µs P95** · **1.26 ms P99** | Sustained `3,453 nodes/s` & `9,291 edges/s` (`<1.1%` drift) |
| **2-Hop Transaction Walk @ 20M** | **0.38 ms P50** · **0.49 ms P95** · **0.87 ms P99** | `4,180.7 QPS` concurrent 16-thread read storm (`P99: 13.8 ms`) |
| **6,000,000-Edge Super-Hub Walk @ 20M** | **53.1 ms P50** · **58.8 ms P95** · **58.8 ms P99** | Guarded intermediate hub fan-out (`0` timeouts) |
| **Bounded-Memory Corpus (8.84M MS MARCO)** | **~9 GB peak RSS** · **~5.4 GB steady-state** | 24 GB machine · zero swap · `-3,626 MB` returned to OS post-ingest |
| **VectorDBBench (1M × 768d)** | **916 QPS** · **0.946 recall@10** | `0.33 ms` P99 @ 100K nodes · `40,551 docs/s` batch ingest |
| **3-D Structural Engineering (AEC)** | **240.5 ms** 3-D rigidity · **3.53 s** critical members | 250-storey frame (`100,000` 3-D joints, `478,840` members) in `352.5 MB` RSS |
| **Sustained Soak & Test Suite** | **1.18M requests @ 0% error rate** (500 users) | **14,500+ automated tests** passing |

---

## 5. Key Documentation Links
- Quickstart (Docker): https://docs.graph.purple8.ai/getting-started/docker
- AI Agent Build Blueprint: https://docs.graph.purple8.ai/guides/ai-agent-blueprint
- MCP Integration & Tool Profiles: https://docs.graph.purple8.ai/guides/mcp
- Benchmarks & Architecture Comparison: https://docs.graph.purple8.ai/guides/benchmarks
- REST API Reference: https://docs.graph.purple8.ai/reference/rest-api
- Cypher Query Reference: https://docs.graph.purple8.ai/reference/cypher
- Purple8 DocIntel Docs (70+ formats): https://docs.docintel.purple8.ai/