# OGuardAI: Full Technical Reference for LLMs

> OGuardAI is a semantic data protection and transformation runtime for AI systems. It sits between your application and the LLM, detecting sensitive entities in user input, replacing them with typed semantic tokens {{type:id}}, preserving safe metadata so LLMs retain context without seeing real data, and deterministically restoring original values in the LLM output afterward.

## Why OGuardAI Exists

AI adoption in enterprises is blocked by a false choice: use AI unsafely with raw sensitive data, or strip data until AI becomes useless. OGuardAI removes this trade-off with a semantic protection runtime that preserves AI quality while enforcing data safety. The core insight: replace raw values with typed semantic tokens that carry enough context (gender, formality, language) for LLMs to generate correct, personalized output, then deterministically restore only what policy allows.

## How It Works

1. Your app sends text containing PII to OGuardAI
2. OGuardAI detects sensitive entities (30+ regex patterns + NER models)
3. Each entity is replaced with a semantic token: "julia@example.com" → {{email:e_001}}
4. Safe text is sent to the LLM of your choice (OpenAI, Anthropic, Mistral, local)
5. LLM responds using the tokens naturally
6. OGuardAI restores tokens to originals with policy-based formatting
7. User receives personalized, grammatically correct output

## Entity Types (19 built-in by format, plus NER)

Nineteen entity types are detected out of the box by format detectors, plus person, company, and location by NER. Custom detectors and policy-defined NER labels extend this at runtime.

| Type | Detection | Examples |
|------|-----------|----------|
| email | regex | julia@example.com |
| phone | regex | +49 30 12345678 |
| address | regex (locale) | Hauptstraße 42, 10115 Berlin |
| ssn | regex | 123-45-6789 |
| credit_card | regex+Luhn | 4539 1488 0343 6467 |
| iban | regex | DE89 3704 0044 0532 0130 00 |
| date_of_birth | regex | born 03/15/1985 |
| passport | regex | C01234567 |
| vat_id | regex | DE123456789 |
| ip | regex | 192.168.1.100, 2001:db8::1 |
| url | regex | https://example.com |
| customer_id | regex | CID-48921 |
| order | regex | ORD-2024-7891 |
| health_id | regex | HID-12345 |
| custom:money | regex | 1.299,00 EUR, €49.99 |
| custom:de_tax_id | regex | 12 345 678 901 |
| custom:de_sozialversicherung | regex | 15070649C103 |
| custom:quote_id | regex | Q-2026-0847 |
| custom:case_ref | regex | CASE-2024-7788 |
| person | NER | Julia Schneider, John Smith |
| company | NER | Acme Corp, Beta GmbH |
| location | NER | Berlin, München |

## Restore Modes

- **full**: Complete original value (julia@example.com)
- **partial**: Abbreviated (J. Schneider, j***@example.com)
- **masked**: Redacted pattern (J**** ********r, j************e)
- **formatted**: Gender/formality-aware (Frau Julia Schneider)
- **abstract**: Type description only ([Email Address])
- **none**: Fully redacted ([REDACTED])

## Output Channels

Each channel determines which restore mode applies:
- user_output → full
- internal_summary → partial
- customer_email → formatted
- tool_payload → full
- export → masked
- log_safe → none (all [REDACTED])

## Policy Engine

Policies are YAML files that define per-entity-type actions:
- **redact**: Replace with [REDACTED:type], purged from the session (set on_redact: reject to fail with 403 instead)
- **tokenize**: Replace with a reversible semantic token {{type:id}}
- **abstract**: Replace with a category label (e.g., [IBAN])

To send a specific value to the model unchanged, list it in the policy `whitelist` (an authored `allow` action is rejected at load).

Policies can be scoped by destination (external_llm, local_llm, vector_store, tool, agent_memory).

### Conditional Rules

Policy rules support conditions that are evaluated at runtime:
- **confidence**: Numeric threshold conditions (operators: gte, lte, gt, lt)
- **caller_role**: Role-based conditions (operators: eq, in, neq)

**Production:** bind `caller_role` to API key config (`caller_role` field) or JWT claims. In non-dev auth modes, request-supplied `context.caller_role` is ignored unless the auth credential has a bound role. **Dev/testing only:** pass `caller_role` via `context.caller_role` in transform requests. When no role is available, role-based conditions do not match and the base action applies.

## Session Model

Sessions are stateless: encrypted with AES-256-GCM into a sealed blob that travels with the response. No server-side storage needed. Key derivation uses HKDF-SHA256. AAD binds all envelope fields (version, key ID, session ID, tenant, policy, expiry, language, counter).

## Supported Languages

30+ languages including: English, German, French, Spanish, Arabic, Japanese, Korean, Chinese, Russian, Turkish, Italian, Dutch, Portuguese, Polish, Swedish, Danish, Finnish, Greek, Czech, Ukrainian, Romanian, Hindi, Thai, Vietnamese, Indonesian, Bengali, Swahili, Hebrew, Farsi, Malay.

## API Quick Reference

### Transform
```
POST /v1/transform
{"input": "Email julia@example.com about order #4821", "policy": "default"}
→ {"safe_text": "Email {{email:e_001}} about order #4821", "session_state": "..."}
```

### Rehydrate
```
POST /v1/rehydrate
{"output": "Dear {{email:e_001}}", "session_state": "...", "output_channel": "user_output"}
→ {"restored_text": "Dear julia@example.com"}
```

### Detect
```
POST /v1/detect
{"input": "Contact julia@example.com, SSN 123-45-6789"}
→ {"entities": [{"type": "email", ...}, {"type": "ssn", ...}]}
```

## SDKs

### Python
```python
from guardai_sdk import OGuardAIClient
client = OGuardAIClient(base_url="http://localhost:3000")
result = client.transform(text="Email julia@example.com")
restored = client.rehydrate(llm_output, session_state=result.session_state)
```

### TypeScript
```typescript
import { OGuardAIClient } from "@oguardai/sdk";
const client = new OGuardAIClient({ baseUrl: "http://localhost:3000" });
const result = await client.transform({ input: "Email julia@example.com" });
const restored = await client.rehydrate({ output: llmOutput, session_state: result.session_state! });
```

## Key Scenarios

- **Customer Support**: German formal replies with gender-aware restoration
- **RAG Pipelines**: Sanitize document ingestion and query-time context
- **CRM Copilot**: Draft emails and summaries without exposing customer data
- **Agentic Workflows**: Govern multi-step tool calls with per-step sanitization
- **Healthcare/Legal/Finance**: Enable AI in regulated departments

## Deployment

Self-hosted: you run the entire runtime in your own infrastructure and hold every secret. There is no hosted or managed SaaS. The proprietary runtime is private today and provided under a written agreement with Oronts (request access at https://OGuard.ai/request). Ways to obtain and run it:

- **Container images** (the unit of delivery): ghcr.io/oronts/oguardai/{server,detector-py,proxy}, pinned by tag or digest.
- **Helm chart (OCI)**: helm install oguardai oci://ghcr.io/oronts/charts/oguardai --version 0.1.0
- **Docker Compose**: consumes the published images (docker compose -f deploy/docker/docker-compose.yml up).
- **Signed release archive**: the oguardai CLI and oguardai-server binaries with a SHA-256 checksum, a Cosign signature, and an SBOM. Not published to crates.io.
- **Cloud recipes**: ECS, Cloud Run, and Container Apps run the same image plus a platform YAML.

The SDKs (TypeScript, Python, Go, Java) and the MCP server are Apache-2.0 and installable by holders: npm, pip, go get, Maven, or built from sdks/.

## Links

- Documentation: https://OGuard.ai/docs
- GitHub: https://github.com/oronts/oguardai
- Company: https://oronts.com/en
- License: proprietary (core runtime), the property of Oronts GmbH; Apache-2.0 (SDKs, examples, docs)