Metadata-Version: 2.4
Name: uninitial
Version: 0.6.0
Summary: The private layer before intelligence becomes evidence.
Project-URL: Homepage, https://uninitial.com
Project-URL: Repository, https://github.com/olanotolu/Uninitial
Author: Olanotolu
License: MIT
Keywords: ai,anthropic,llm,openai,pii,privacy,sanitization
Requires-Python: >=3.10
Requires-Dist: requests>=2.31.0
Provides-Extra: proxy
Requires-Dist: fastapi>=0.115.0; extra == 'proxy'
Requires-Dist: httpx>=0.28.0; extra == 'proxy'
Requires-Dist: pydantic<2.20.0,>=2.10.0; extra == 'proxy'
Requires-Dist: uvicorn>=0.32.0; extra == 'proxy'
Description-Content-Type: text/markdown

# uninitial SDK

> The private layer before intelligence becomes evidence.

## Quick Start

```bash
pip install uninitial
```

```python
from uninitial import JohnDoe

ai = JohnDoe(
    provider="openai",
    api_key="sk-...",
    custom_entities=["Acme Corp", "Stripe"],
)

response, receipt = ai.ask_with_receipt(
    "We are acquiring Stripe next quarter. Draft the board memo."
)
print(response)
print(f"route: {receipt.route}, leakage: {receipt.leakage_score}")
```

## Architecture

The SDK implements the **Judge-Ghost-Witness** protocol. Every prompt passes through three steps before any token leaves the user's machine.

```
User prompt
    │
    ▼
Judge
  Scans for sensitive entities (regex + custom)
  Builds IntentGraph with entity_map + placeholder_map
  Assigns sensitivity_score (0.0–1.0)
    │
    ▼
Ghost
  Context alienation: secrets → placeholders
  Structural mode: adds privacy preamble
  Stores mappings in Vault
    │
    ▼
Router
  sensitivity_score → public / enclave / local
  ≥0.8 → local (refuse external dispatch)
  ≥0.3 → enclave
  <0.3 → public
    │
    ▼
Provider call (sanitized prompt only)
    │
    ▼
Witness
  Verifies no secret leaked in response
  Detects inference attempts near placeholders
  Computes leakage_score (0.0–1.0)
  Issues AuditReceipt
    │
    ▼
Ghost.restore (placeholders → real values)
    │
    ▼
User response + PrivacyReceipt
```

The model answers. It never learns who asked.

## The Judge-Ghost-Witness Protocol

### Judge

`Judge.analyze(prompt) → IntentGraph`

Scans the raw prompt for sensitive entities using regex-based detectors:
- Emails, SSNs, credit cards, API keys, IPs, URLs with credentials, addresses, phone numbers
- Custom entities (company names, project names, etc.)

Produces an `IntentGraph` with `entity_map` (real→placeholder), `placeholder_map` (placeholder→real), `entity_types`, and a `sensitivity_score` (0.0–1.0).

### Ghost

`Ghost.transform(intent_graph, vault) → str`

Performs **context alienation**: replaces every sensitive entity with a placeholder. In **structural mode** (default), wraps the sanitized prompt with a privacy preamble instructing the model to preserve placeholders and not infer hidden identities.

`Ghost.restore(response, intent_graph) → str`

Reverses placeholder substitution in the provider response, restoring real values.

### Witness

`Witness.verify(response, intent_graph) → AuditReceipt`

After the provider responds, Witness:
1. Checks for exact entity leaks (sensitive entity strings in response)
2. Detects inference attempts (phrases like "likely Stripe" near placeholders)
3. Computes a `leakage_score` (0.0 = clean, 1.0 = exact leak, 0.5–0.9 = inference)

Issues a cryptographic `AuditReceipt` with hashes and metadata.

### Router

`Router.route(intent_graph) → RoutingDecision`

Routes based on sensitivity score:
- `≥0.8` → **local** (refuse external dispatch)
- `≥0.3` → **enclave** (route to secure enclave)
- `<0.3` → **public** (safe for public cloud provider)

### Trace Collection

`TraceCollector` records privacy-safe traces (hashes and counts only — no raw prompts or entities) to `~/.uninitial/traces.jsonl` by default. Enable with `trace=True` in `JohnDoe()`.

## API Reference

### `JohnDoe(provider, mode, policy, api_key, model, custom_entities, ghost_mode, trace, trace_path)`

Main entry point. Orchestrates the full pipeline.

| Parameter  | Default              | Description                              |
|------------|----------------------|------------------------------------------|
| `provider` | `"openai"`           | Target inference provider (`openai`, `anthropic`) |
| `mode`     | `"zero_raw_context"` | Privacy mode                             |
| `policy`   | `"never_send_secrets"` | Secret handling policy                 |
| `api_key`  | `None`               | Provider API key (or set env var)        |
| `model`    | `None`               | Model name (e.g. `gpt-4o`)              |
| `custom_entities` | `None`       | Additional entity names to detect        |
| `ghost_mode` | `"structural"`     | Ghost transform mode (`structural`, `plain`) |
| `trace`    | `False`              | Enable trace collection                  |
| `trace_path` | `None`             | Custom trace file path                   |

### Methods

- `ai.ask(prompt) → str` — full pipeline, returns final response
- `ai.ask_with_receipt(prompt) → (str, PrivacyReceipt)` — full pipeline with receipt
- `ai.judge(prompt) → IntentGraph` — Judge step only
- `ai.ghost(intent_graph) → str` — Ghost step only
- `ai.witness(response, intent_graph) → AuditReceipt` — Witness step only

### Types

- `IntentGraph` — prompt analysis output with entity maps and sensitivity score
- `RoutingDecision` — routing outcome (destination, reason, score)
- `AuditReceipt` — post-response verification with leakage score and inference detection
- `PrivacyReceipt` — full privacy audit record (route, vaulted entities, leakage score, hashes)

### Providers

- `OpenAIProvider(api_key, model)` — OpenAI API client
- `AnthropicProvider(api_key, model)` — Anthropic API client
- `get_provider_client(provider, api_key, model)` — factory function

### Errors

- `UninitialPrivacyError` — base exception
- `SensitiveEntityLeakError` — entity found in outbound payload
- `RoutingError` — no safe routing destination
- `WitnessVerificationError` — response verification failed

## Environment Variables

| Variable | Description |
|----------|-------------|
| `OPENAI_API_KEY` | OpenAI API key |
| `ANTHROPIC_API_KEY` | Anthropic API key |
| `UNINITIAL_API_KEY` | Proxy authentication key |
| `UNINITIAL_HOST` | Proxy host (default `0.0.0.0`) |
| `UNINITIAL_PORT` | Proxy port (default `8000`) |
| `UNINITIAL_CUSTOM_ENTITIES` | Comma-separated custom entities for Judge |
| `UNINITIAL_TRACE` | Enable trace collection (`1`, `true`, `yes`) |
| `UNINITIAL_TRACE_PATH` | Custom trace file path |

```
Zero Data Retention is policy.
Uninitial is architecture.
```
