Metadata-Version: 2.4
Name: guardian-runtime
Version: 0.2.2
Summary: Local-first runtime governance layer for AI systems
Project-URL: Homepage, https://guardian-ai.dev
Project-URL: Documentation, https://guardian-ai.dev/docs
Project-URL: Repository, https://github.com/guardian-ai/guardian-runtime
Project-URL: Issues, https://github.com/guardian-ai/guardian-runtime/issues
Author-email: Ashish Patil <ashishtp2005@gmail.com>
Keywords: ai,anthropic,claude,dpdp,finops,gemini,governance,guardrails,jailbreak,langchain,llm,openai,pii
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Requires-Dist: anthropic>=0.40
Requires-Dist: click>=8.0
Requires-Dist: fastapi>=0.100
Requires-Dist: google-genai>=0.8.0
Requires-Dist: httpx>=0.25
Requires-Dist: openai>=1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: tiktoken>=0.5
Requires-Dist: uvicorn>=0.23
Provides-Extra: all
Requires-Dist: langchain-core>=0.1; extra == 'all'
Requires-Dist: markitdown>=0.0.1; extra == 'all'
Requires-Dist: presidio-analyzer>=2.2; extra == 'all'
Requires-Dist: presidio-anonymizer>=2.2; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest-mock>=3.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1; extra == 'langchain'
Provides-Extra: optimizer
Requires-Dist: markitdown>=0.0.1; extra == 'optimizer'
Provides-Extra: presidio
Requires-Dist: presidio-analyzer>=2.2; extra == 'presidio'
Requires-Dist: presidio-anonymizer>=2.2; extra == 'presidio'
Description-Content-Type: text/markdown

# Guardian Runtime

**Cut LLM token costs. Block data leaks. Ship safer AI.**

Guardian Runtime is a local-first Python SDK that sits between your AI application and any LLM. It automatically compresses prompts to reduce token costs, blocks PII and API key leaks before they reach the model, and catches jailbreak attempts — all on your machine. Your prompts never leave your infrastructure.

[![PyPI](https://img.shields.io/pypi/v/guardian-runtime.svg)](https://pypi.org/project/guardian-runtime/)
[![Python 3.9+](https://img.shields.io/pypi/pyversions/guardian-runtime.svg)](https://pypi.org/project/guardian-runtime/)
[![Tests](https://img.shields.io/badge/tests-111%20passed-brightgreen)](https://github.com/ashp15205/guardian-runtime)


```text
User Input
    ↓
[Input Optimizer]  →  saves 30–70% tokens
    ↓
[Input Guard]      →  blocks PII, secrets, jailbreaks
    ↓
   LLM             →  your model, your API key
    ↓
[Output Guard]     →  scans response before it reaches user
    ↓
Safe Response + Analysis Report
```

---

## Why Guardian?

Observability tools (Langfuse, LangSmith, Helicone) log what went wrong — after it happened. Guardian stops it before it happens, on your machine.

| | Observability Tools | Guardian Runtime |
|---|---|---|
| When it acts | After the LLM call | **Before and after** |
| Your data path | Sent to their cloud | **Stays on your machine** |
| PII in prompt | Logged | **Blocked** |
| Exposed API keys | Not detected | **Blocked** |
| Token costs | Tracked | **Actively reduced** |
| Jailbreak attempts | Logged | **Blocked** |

---

## Install

```bash
pip install guardian-runtime
```

Optional extras:
```bash
pip install guardian-runtime[optimizer]   # PDF/DOCX → markdown conversion
pip install guardian-runtime[dev]         # testing tools
```

Requires **Python 3.9+**

## Supported Providers

| Provider | Environment Variable | Policy file | Default Model |
|---|---|---|---|
| Google Gemini | `GEMINI_API_KEY` | `policies/gemini.yaml` | `gemini-2.0-flash` |
| Anthropic Claude | `ANTHROPIC_API_KEY` | `policies/anthropic.yaml` | `claude-3-5-haiku-latest` |
| OpenAI | `OPENAI_API_KEY` | `policies/minimal.yaml` | `gpt-4o-mini` |

Override provider at runtime:
```python
response = guardian.complete(
    provider="anthropic",
    model="claude-3-5-haiku-latest",
    messages=[...]
)
```

---

## Features

### Security & Privacy

- **PII Detection** — Aadhaar (`xxxx xxxx xxxx`), PAN (`XXXXX0000X`), UPI (`name@bank`), SSN (`xxx-xx-xxxx`), credit cards, email, phone, passport numbers
- **Secret Detection** — OpenAI keys (`sk-...`), AWS access keys (`AKIA...`), GitHub tokens (`ghp_...`), Stripe keys (`sk_live_...`), Razorpay keys (`rzp_live_...`), Groq keys (`gsk_...`), generic `.env` patterns
- **Jailbreak Detection** — 40+ patterns covering DAN variants, instruction overrides, role-play injections, encoding tricks, and system prompt extraction attempts
- **Output Guard** — scans LLM responses for PII and secrets before they reach users
- **Action modes** — `block`, `redact`, or `flag` per entity type

### Cost Optimization

- **Prompt compression** — strips redundant whitespace, deduplicates system prompts, removes empty messages
- **History trimming** — keeps last N turns, always preserves system prompt
- **Document conversion** — PDF, DOCX, XLSX → clean markdown (30–70% token savings)
- **Token budget enforcement** — warn or block when input exceeds your defined limit
- **Cost estimation** — every response includes token count and USD cost estimate

### Governance

- **YAML policy engine** — define rules per agent, no code changes needed to update policies
- **Multi-agent support** — different rules for different bots
- **Block / redact / flag modes** — choose the right action per violation type
- **Local audit logs** — full JSONL log at `~/.guardian/logs/` — never uploaded anywhere

### CLI

```bash
guardian init --key gdn_free_xxxxx       # optional license setup
guardian validate policies/gemini.yaml   # check policy syntax
guardian status                          # view usage this month
guardian logs --tail 20                  # view recent violations
```

---

## Policy Example

```yaml
version: "1.0"
agents:
  default:
    llm:
      provider: gemini
      default_model: gemini-2.0-flash
    input_guard:
      pii_detection: true
      jailbreak_detection: true
      pii_action: block
    output_guard:
      pii_detection: true
    optimizer:
      enabled: true
      whitespace_normalization: true
      max_history_messages: 10
      deduplicate_system_prompts: true
    cost:
      max_input_tokens: 8000
```

Validate before use:
```bash
guardian validate policies/gemini.yaml
```

---

## Analysis Report

Every `guardian.complete()` call returns a full analysis:

```python
response = guardian.complete(messages=[...])

print(response.content)              # safe, validated response
print(response.blocked)              # True if blocked
print(response.violations)           # list of what was caught
print(response.input_tokens)         # tokens used
print(response.estimated_cost_usd)   # cost in USD
print(response.optimization)         # tokens saved, savings %
```

Example output:
```python
{
  "blocked": False,
  "input_tokens": 620,
  "estimated_cost_usd": 0.0004,
  "optimization": {
    "original_tokens": 1840,
    "optimized_tokens": 620,
    "savings_pct": 0.66,
    "actions_taken": ["whitespace_normalization", "history_trimming"]
  },
  "violations": []
}
```

---

## Compliance

Guardian's detection covers major data protection regulations:

| Regulation | Coverage |
|---|---|
| **India DPDP Act 2023** | Aadhaar, PAN, UPI — native patterns |
| **GDPR** (EU) | Email, phone, passport, general PII |
| **HIPAA** (US Health) | Sensitive personal data blocking |
| **CCPA** (California) | Consumer data protection |

> Guardian is an assistive compliance tool, not legal advice. Always consult qualified counsel for regulatory requirements.

---

## Local-First Architecture

```text
Your Machine
├── guardian SDK         ← all processing happens here
├── ~/.guardian/
│   ├── config.json     ← license key (if using paid plan)
│   ├── usage.json      ← monthly check count
│   └── logs/           ← violation logs (never uploaded)
│       └── YYYY-MM-DD.jsonl
```

What Guardian's servers **never** receive:
- Your prompts
- Your LLM responses
- Your violation details
- Your API keys (OpenAI, Anthropic, etc.)

What the optional daily sync sends (once per day, HTTPS only):
- Your hashed license key
- A single number: how many checks you ran

---

## Project Structure

```text
guardian/
├── core/           engine, policy, models, storage
├── guards/         input guard, output guard, validators
│   └── validators/ pii, secrets, jailbreak, hallucination
├── optimizer/      prompt compression, document converter
├── providers/      openai, gemini, anthropic
├── finops/         token counter, cost calculator
├── logging/        local JSONL logger
└── cli/            init, validate, status, logs
```

---

## Development

```bash
git clone https://github.com/ashp15205/guardian-runtime.git
cd guardian-runtime
pip install -e ".[dev,optimizer]"
pytest tests/ -q    # 111 tests
```

See [ARCHITECTURE.md](./ARCHITECTURE.md) for the full technical specification.

---

## Privacy

- All scanning runs **on your infrastructure**
- Logs stored locally at `~/.guardian/logs/`
- Optional license sync sends **only** a hashed key + check count — never prompts or responses


