taivium 0.1.3

Deterministic identity + privacy layer for LLM applications

Taivium

Deterministic identity + privacy layer for LLM applications
Sensitive data in → safe prompts out → coherent responses back

View on GitHub

Taivium sits between your application and any LLM provider, automatically preventing sensitive data leakage — without breaking reasoning, context, or output quality.

No prompt engineering. No degraded responses. No data exposure.

---

---

The Problem

Every LLM call is a potential data leak.

• Support copilots handle customer PII (names, emails, accounts)
• Developers paste secrets (API keys, credentials)
• Healthcare & legal workflows send sensitive records
• RAG pipelines embed confidential company data

Naive redaction breaks AI quality.

"Alice emailed Bob" → "[NAME] emailed [NAME]"

→ Identity is lost → reasoning collapses.

---

The Solution

Taivium preserves identity and privacy.

"Alice emailed Bob" → "PERSON_a1b2 emailed PERSON_c3d4"

• Identity remains distinguishable
• Context stays intact
• Zero sensitive data reaches the LLM

---

How It Works

Your App ──► Taivium ──► LLM (OpenAI / Claude / local)
                │
    ┌──────────────────────────────┐
    │ Detection Layer              │  spaCy · regex · transformer · LLM
    │ Span Canonicalization        │  one entity per span
    │ Identity Engine              │  deterministic pseudonyms
    │ Policy Engine                │  ALLOW · ANONYMIZE · BLOCK
    │ Session Store                │  memory or Redis
    └──────────────────────────────┘
                │
        Optional response restoration

Key idea:
Each real-world entity gets a stable pseudonymous ID across the session.

---

Why Taivium Is Different

Capability	Typical Tools	Taivium
PII detection	✔	✔
Anonymization	Masking	Semantic preservation
Identity tracking	✗	Deterministic + persistent
Coreference	Weak	Cross-session consistent
Utility preservation	✗	Primary objective

---

Determinism

Taivium is fully deterministic by default:

• Same input → same output
• Reproducible + auditable
• No randomness

Optional layers:

• Transformer → deterministic
• LLM → non-deterministic (opt-in)

---

Installation

pip install taivium

With Redis:

pip install taivium[redis]

Model Dependency

Taivium uses spaCy for entity detection. You must manually install the English model:

pip install "en_core_web_sm @ https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl#sha256=1932429db727d4bff3deed6b34cfc05df17794f4a52eeb26cf8928f7c1a0fb85"

With Transformers (deep learning NER):

pip install taivium[transformers]

With multiple options (e.g., Redis and Transformers and dev tools):

pip install taivium[redis,transformers,dev]

Note: Optional dependencies let you install only what you need. For example, if you want transformer-based NER, use the transformers extra. If you want Redis-backed session storage, use the redis extra. You can combine extras as needed.

---

Quick Start

1. Drop-in OpenAI Client

from taivium.client import PrivacyClient
import os

client = PrivacyClient(api_key=os.environ["OPENAI_API_KEY"])

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{
        "role": "user",
        "content": "John Doe's email is [e-mail]. Draft a follow-up."
    }],
    deid_response=True,
)

print(response.choices[0].message.content)

✔ LLM never sees real data
✔ Output still uses real names

---

2. Sanitize Text Directly

from taivium.engine import Taivium

pipeline = Taivium()

result = pipeline.process(
    "Alice Johnson from Acme Corp emailed [e-mail]"
)

print(result["anonymized"])

Example output:

PERSON_xxxx from ORG_xxxx emailed EMAIL_xxxx

---

3. Custom Policies

from taivium.engine import (
    Taivium, PolicyEngine, PolicyRule, PolicyAction, RiskLevel
)

pipeline = Taivium(
    policy_engine=PolicyEngine(policy_table={
        "API_KEY": PolicyRule("API_KEY", PolicyAction.BLOCK, RiskLevel.CRITICAL),
        "LOCATION": PolicyRule("LOCATION", PolicyAction.ALLOW, RiskLevel.LOW),
    })
)

---

4. Redis Persistence

from taivium.engine import Taivium
from taivium.session_store import RedisSessionStore

store = RedisSessionStore(
    session_id="user-123",
    redis_url="redis://localhost:6379",
)

pipeline = Taivium(session_store=store)

---

5. Optional Detection Layers

pipeline = Taivium(
    use_transformer=True,
    use_llm=True
)

• Transformer → higher recall
• LLM → broader detection
• Both optional

---

What Gets Detected

Entity Type	Examples
PERSON	Alice Johnson
ORG	Acme Corp
EMAIL	[e-mail]
PHONE	[phone]
API_KEY	sk-xxxx
LOCATION	New York

---

Why Not Simple Redaction?

	Redaction	Taivium
Identity preserved	✗	✓
Same entity consistency	✗	✓
LLM reasoning intact	✗	✓
Response restoration	✗	✓
Policy control	✗	✓

---

Features

• Multi-layer detection (spaCy + regex + transformer + LLM)
• Deterministic pseudonymous identity
• Policy engine (ALLOW / ANONYMIZE / BLOCK)
• Response restoration
• Redis session persistence
• Audit trail per request
• OpenAI-compatible client

---

Example Output

result = pipeline.process("Alice emailed [e-mail]")

{
    "original": "Alice emailed [e-mail]",
    "anonymized": "PERSON_xxxx emailed EMAIL_xxxx",
    "store_type": "InMemorySessionStore",
    "mapping = {
        "PERSON_7e4a1c2b3d4e5f6a7b8c9d0e": "Alice",
        "EMAIL_1a2b3c4d5e6f7a8b9c0d1e2f": "[e-mail]"
    }": {},
    "entities": [
        {
            "text": "Alice",
            "label": "PERSON",
            "start": 0,
            "end": 5,
            "source": "spacy",
            "evidence_sources": ["spacy", "regex"],
            "confidence": 0.92
        },
        {
            "text": "[e-mail]",
            "label": "EMAIL",
            "start": 14,
            "end": 28,
            "source": "regex",
            "evidence_sources": ["regex"],
            "confidence": 0.95
        }
    ]
}

---

Architecture

engine.py
├── collect_evidence()
├── canonicalize_spans()
├── IdentityEngine.resolve()
├── PolicyEngine.evaluate()
├── transform()
└── session_store

---

Documentation

See docs/ for full design details.

---

Examples

See examples/:

• privacy pipeline
• OpenAI client
• custom detectors

---

Contributing

1. Fork the repo
2. Create a branch
3. Add tests
4. Open PR

---

License

MIT — see LICENSE

---

Support

Open an issue for bugs, questions, or feature requests.