# Purple8 DocIntel (v0.12.5) — AI Agent & Developer Reference (llms.txt)

> **Universal Document Intelligence for AI Agents & Enterprise Pipelines.**
> Parse **70+ document formats** across **75+ languages** into structured entities, relationships, and tables — standalone or auto-committed directly into **Purple8 Hyper Graph**.

Purple8 DocIntel (`https://docs.docintel.purple8.ai`) is a self-hosted, container-native document intelligence engine combining format-specific parsers, Lingua 75+ language detection, fine-tuned GLiNER v4.1 zero-shot NER, two-pass domain-ontology LLM extraction, temperature-scaled confidence calibration, and an embedded durable job store (`p8l` — zero external Redis dependency).

---

## 1. Connect an AI Agent Over MCP (`/mcp`)

DocIntel exposes a native **MCP 1.x Streamable HTTP endpoint** at `https://<your-host>/mcp`.
It accepts **`X-API-Key: <key>`**, **`Authorization: Bearer <key>`**, or `?api_key=<key>` (works seamlessly with both production `SERVER__API_KEY` and Cloud Sandbox keys).

```bash
# Claude Code CLI
claude mcp add --transport http purple8-docintel "https://<your-host>/mcp" \
  --header "X-API-Key: <your-docintel-or-sandbox-key>"
```

```json
// Cursor (.cursor/mcp.json) or VS Code
{
  "mcpServers": {
    "purple8-docintel": {
      "url": "https://<your-host>/mcp",
      "headers": {
        "X-API-Key": "<your-docintel-or-sandbox-key>"
      }
    }
  }
}
```

### All 5 Built-in DocIntel MCP Tools

| Tool Name | Purpose | Key Parameters |
|---|---|---|
| **`docintel_ingest_text`** | Extract entities, relationships, and metadata from raw text. | `text` (req), `source_app`, `profile_hint` (`aec`\|`contract`\|`financial`\|`scientific`\|`general`), `auto_commit` (defaults to `false` when standalone/sandbox; `true` when `graph_base_url` is supplied), `graph_base_url`, `graph_api_key` |
| **`docintel_ingest_url`** | Fetch a document from an HTTP/HTTPS URL, parse it (PDF, DOCX, XLSX, IFC, CAD, etc.), and extract structured entities + tables. | `url` (req), `source_app`, `profile_hint`, `auto_commit`, `wait_seconds`, `graph_base_url`, `graph_api_key` |
| **`docintel_get_job`** | Poll or retrieve the full extraction result (`entities`, `relationships`, `tables`, `metadata`) for an async `job_id`. | `job_id` (req), `wait_seconds` (optional long-poll) |
| **`docintel_list_formats`** | List all 70+ supported document extensions and format categories. | *(no required params)* |
| **`docintel_health`** | Check DocIntel service health and version (`v0.12.5`). | *(no required params)* |

---

## 2. REST API Quick Reference

All endpoints accept either `X-API-Key: <key>` or `Authorization: Bearer <key>`:

- **`POST /process`** (`multipart/form-data`, `file=@...`): Upload any file (PDF, DOCX, XLSX, PPTX, IFC, DXF, STEP, EML, SAP IDoc, image). Query params: `profile_hint`, `source_app`, `auto_commit` (`true`/`false`), `graph_base_url`, `graph_api_key`. Returns `{"job_id": "...", "status": "queued"}`.
- **`POST /process-url`** (`application/json`, `{"url": "https://..."}`): Process a remote document by URL (protected by SSRF guard).
- **`GET /jobs/{job_id}`**: Retrieve job status (`queued` | `processing` | `DONE` | `FAILED`) and extracted `entities`, `relationships`, `tables`, and `confidence` scores.
- **`GET /jobs/{job_id}/stream`**: Real-time Server-Sent Events (SSE) stream of partial extraction windows as they complete.
- **`GET /formats`**: List all 70+ supported file formats.
- **`GET /health`**: Unauthenticated liveness probe (`{"status": "ok", "version": "0.12.5"}`).

---

## 3. Verified Performance & Capabilities (v0.12.5)

| Metric / Capability | Verified Value |
|---|---|
| **Supported Formats** | **70+ formats** across Office, PDF, CAD & BIM (`IFC 2x3/4/4x3`, `IFCZIP`, `DXF`, `DWG`, `STEP`, `STL`, `OBJ`, `GLTF/GLB`, `G-code`), Web/Email, Code/Config, SAP (`IDoc`, `ABAP`), and OCR images |
| **Supported Languages** | **75+ languages** (Lingua detector + language-aware extraction prompts) |
| **Parse + Layout Throughput (8 CPU workers)** | **35.34 docs/s** (**353.4 pages/s**, **70.7 structured tables/s**) |
| **Zero-Shot Local NER (`GLiNER v4.1`)** | **0.91 docs/s** (**3,276 docs/hr** on CPU, zero external LLM calls) |
| **Coupled Graph Commit (`POST /ingest/commit`)** | **7.11 docs/s** (**71.1 pages/s**), **0.65 ms P50** structured table row query in Purple8 Hyper Graph |
| **Job Persistence** | Embedded durable `p8l` log (`SessionContentStore`) with lazy worker initialisation — **no external Redis required** |

---

## 4. Key Documentation Links
- AI Agents & MCP Guide: https://docs.docintel.purple8.ai/getting-started/mcp-agents
- Docker Quickstart: https://docs.docintel.purple8.ai/getting-started/quickstart
- Competitor Comparison Matrix: https://docs.docintel.purple8.ai/compare
- Supported Formats (70+): https://docs.docintel.purple8.ai/capabilities/formats
- Domain Extraction Profiles: https://docs.docintel.purple8.ai/capabilities/profiles
- REST API Reference: https://docs.docintel.purple8.ai/reference/api
- Purple8 Hyper Graph Docs: https://docs.graph.purple8.ai/