# P3AK vault

**Encrypted, portable, AI-searchable single-file knowledge store.**

Part of the [P3AK platform](https://p3ak.ai) — use standalone or with P3AK room and P3AK harness.

---

## What It Does

P3AK vault stores any document collection in a single encrypted `.vault` file with hybrid AI search built in. No database, no server, no cloud dependency. One file you can move, back up, or delete.

- **AES-256-GCM encryption** at rest with Argon2id key derivation
- **Hybrid search** — BM25 (Tantivy) + TF-IDF ZVec + PageIndex tree at ≥91% top-1 accuracy
- **34 file formats** — markdown, PDF, DOCX, HTML, CSV, images (OCR), audio (transcribe), and more
- **Hash-linked WAL** — tamper-evident audit log of every read and write
- **Canary monitoring** — automatic recall health checks
- **Multi-vault federation** — search across multiple vaults in one query
- **.mdr support** — ingests P3AK Documents (multi-layer versioned format)

---

## Quick Start

```bash
# Install
cargo install p3ak-vault

# Create a vault
p3ak-vault create --path company.vault

# Ingest documents
p3ak-vault ingest --path company.vault --dir ./documents --recursive --room legal

# Search
p3ak-vault search --path company.vault --query "renewal terms" --mode hybrid

# REST API
p3ak-vault serve --path company.vault --port 8080
```

---

## CLI Commands

| Command | Description |
|---|---|
| `p3ak-vault create` | Create a new empty vault |
| `p3ak-vault ingest` | Ingest a file or directory (34 formats) |
| `p3ak-vault search` | Hybrid search with room/store filters |
| `p3ak-vault read` | Read docs, goals, or WAL entries |
| `p3ak-vault write` | Write goal, doc, plan, or review entries |
| `p3ak-vault classify` | AI-classify documents into 10 knowledge stores |
| `p3ak-vault delete` | Soft-delete a document |
| `p3ak-vault export` | Export a store subset to a new vault |
| `p3ak-vault sync` | Sync documents between two vaults |
| `p3ak-vault watch` | Watch a directory and ingest new files |
| `p3ak-vault canary-add` | Register a canary recall check |
| `p3ak-vault canary-check` | Verify recall health (exit 2 if below threshold) |
| `p3ak-vault accuracy-test` | Run benchmark against ground-truth queries |
| `p3ak-vault serve` | Start REST API server (127.0.0.1 only) |

Global flags: `--path` / `$P3AK_VAULT_PATH`, `--passphrase` / `$P3AK_VAULT_PASSPHRASE`

---

## Supported Formats

**Tier 1 (pure Rust):** md, markdown, txt, text, log, csv, tsv, json, jsonl, svg  
**Tier 2 (compiled-in):** pdf, html, htm, docx  
**Tier 3 (external tools):** png, jpg, jpeg, webp, tiff, gif (OCR via tesseract), mp4, mov, webm, mp3, m4a, wav (transcribe via Groq/whisper), ai, eps (Ghostscript), epub, odt, rtf, pptx (pandoc)  
**P3AK native:** .mdr (P3AK Document — extracts current layer for indexing)

---

## SDKs

```python
# Python subprocess SDK
from p3ak_vault import VaultClient
vault = VaultClient("/path/to/company.vault", passphrase="secret")
results = vault.search("renewal terms", mode="hybrid")

# Python native (PyO3 — sub-millisecond, no subprocess)
from p3ak_vault_native import P3AKVault
vault = P3AKVault.open("/path/to/company.vault", passphrase="secret")
results = vault.search("renewal terms", mode="hybrid")
```

---

## Configuration

```toml
# ~/.p3ak/config.toml
[vault]
path = "/path/to/default.vault"

[security]
passphrase_env = "MY_VAULT_KEY"
```

---

## Environment Variables

| Variable | Description |
|---|---|
| `P3AK_VAULT_PATH` | Default vault path |
| `P3AK_VAULT_PASSPHRASE` | Vault passphrase |
| `ANTHROPIC_API_KEY` | Enables Claude Haiku LLM classifier fallback |
| `GROQ_API_KEY` | Enables Groq Whisper audio transcription |

---

## Test Suite

```bash
cargo test --lib -p vault-core              # 265 unit tests
cargo test -p p3ak-vault-cli               # 54 integration tests
cargo test --test accuracy -p vault-core   # 12 accuracy tests
cargo test --test stress -p vault-core     # stress tests
cd packages/p3ak-vault-py && pytest        # 35 Python SDK tests
cd packages/p3ak-vault-native && maturin develop && pytest  # 44 native tests
```

---

## Part of P3AK

| Product | Role |
|---|---|
| **P3AK vault** (this repo) | Encrypted storage + search infrastructure |
| [P3AK room](https://github.com/p3ak/p3ak-room) | AI data room + document management |
| [P3AK harness](https://github.com/p3ak/p3ak-harness) | Agent orchestration (FORGE protocol) |

→ [P3AK ecosystem docs](https://github.com/p3ak/p3ak)

---

## License

MIT — see [LICENSE](LICENSE)
