uninitial 0.6.0

The private layer before intelligence becomes evidence.

uninitial SDK

The private layer before intelligence becomes evidence.

Quick Start

pip install uninitial

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.