# Pramana Engine

**Deterministic AI verification. No LLM in the loop.**

Pramana is a mathematically grounded verification engine for AI agents. It replaces probabilistic LLM-based guardrails with deterministic constraint satisfaction — sub-millisecond, 100% reproducible, zero compute cost.

```python
from pramana import Pramana

engine = Pramana()
result = engine.verify_quick(
    data={"cpu": 0.82, "memory": 0.71},
    constraints={"cpu": 0.85, "memory": 0.90}
)

if result.verdict == "VERIFIED":
    execute_action()
else:
    halt(result.reasoning)
```

## Why not LLM guardrails?

| | LLM Guardrails | Pramana |
|---|---|---|
| Deterministic | No — different answer each run | Yes — same input, same output, always |
| Speed | 200-2000ms | < 1ms |
| Cost | $0.01-0.05 per check | ~$0 |
| Hallucination risk | Yes | Impossible — it's math |
| Audit trail | "The model said so" | Full epistemological provenance |
| Dependencies | API key + network | None — runs locally |

## Installation

```bash
pip install pramana-engine
```

With REST API:
```bash
pip install pramana-engine[api]
```

With LangChain integration:
```bash
pip install pramana-engine[langchain]
```

## Three Verification Gates

Pramana runs data through three independent gates. The strictest verdict wins.

### 1. Nyaya Gate — Evidence Evaluation

Classifies evidence using the four pramana types from Nyaya epistemology, detects logical fallacies, and computes weighted reliability.

```python
from pramana import Pramana, PramanaType
from pramana.core.nyaya import Evidence

engine = Pramana()
result = engine.verify_claim(
    claim="System is healthy",
    evidence=[
        Evidence(value=0.95, pramana_type=PramanaType.PRATYAKSHA,
                 source="monitoring_api", reliability=0.95),
        Evidence(value="uptime 99.9%", pramana_type=PramanaType.SHABDA,
                 source="status_page", reliability=0.7),
    ]
)
print(result.verdict)  # "VERIFIED"
```

**Pramana types** (evidence strength):
- `PRATYAKSHA` (direct observation) — weight: 1.0
- `ANUMANA` (inference) — weight: 0.85
- `SHABDA` (testimony) — weight: 0.7
- `UPAMANA` (analogy) — weight: 0.5

### 2. Vedic Gate — Constraint Verification

16 mathematical verification methods (sutras) that auto-detect and apply based on your data shape:

| Sutra | What it checks |
|-------|---------------|
| Nikhilam | Complement — how far from the limit? |
| Urdhva Tiryak | Multi-dimensional — all dimensions simultaneously |
| Shunyam | Equilibrium — inputs balance outputs? |
| Anurupyena | Proportionality — ratios hold across scale? |
| Sankalana | Additive — parts sum to whole? |
| Puranapurana | Completeness — all required fields present? |
| Chalana | Delta — changes within bounds? |
| Yavadunam | Gap — deficit within tolerance? |

```python
result = engine.verify_quick(
    data={"parts": {"steel": 45.2, "copper": 30.1, "zinc": 24.7}},
    constraints={"total": 100, "sum_tolerance": 0.01}
)
# Sankalana sutra auto-detects: 45.2 + 30.1 + 24.7 = 100.0 ✓
```

### 3. Arthashastra Gate — Strategy Assessment

Risk assessment using strategic postures, resource evaluation, and cost-benefit analysis.

```python
from pramana.core.arthashastra import StrategicContext

result = engine.verify_action(
    action_type="send_message",
    action_params={"to": "client", "content": "proposal"},
    agent_context={"agent_id": "sales-bot"}
)
print(result.verdict)  # "PROCEED" or "HALTED"
```

## Domain Tuning

Pre-built profiles adjust all three gates for industry-specific thresholds:

```python
from pramana.tuning import apply_profile

engine = Pramana()
apply_profile(engine, "healthcare")  # Conservative — patient safety first
apply_profile(engine, "finance")     # Strict on balance, tolerant on growth
apply_profile(engine, "cybersecurity")  # Zero trust — flag everything
```

**Available profiles:** healthcare, finance, manufacturing, logistics, cybersecurity, construction, agent_safety, marketing

## LLM Output Verification

```python
from pramana.constraints.agent_safety import verify_llm_output

result = verify_llm_output(
    output='{"name": "John", "email": "john@example.com"}',
    expected_format="json",
    required_fields=["name", "email"],
    banned_patterns=["password", "ssn"],
    max_length=1000
)
print(result.verdict)  # "VERIFIED"
```

## REST API

```bash
pramana serve --port 8108
```

```bash
curl -X POST http://localhost:8108/verify/quick \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{"data": {"cpu": 0.75}, "constraints": {"cpu": 0.85}}'
```

## LangChain Integration

```python
from pramana.integrations.langchain import PramanaGuard

# As a chain step — verifies output before returning
chain = my_llm_chain | PramanaGuard(
    constraints={"max_length": 500},
    banned_patterns=["password", "secret"]
)

# As a callback — auto-verifies every LLM call
from pramana.integrations.langchain import PramanaVerifier

llm = ChatOpenAI(callbacks=[PramanaVerifier()])
```

## CLI

```bash
# Verify data against constraints
pramana verify --data '{"cpu": 0.9}' --constraints '{"cpu": 0.85}'

# Verify an agent action
pramana action --type send_message --params '{"to": "user"}'

# Verify LLM output
pramana llm --output "Hello world" --max-length 100

# Start API server
pramana serve --port 8108
```

## Benchmarks

| Suite | Tests | Accuracy |
|-------|-------|----------|
| Standard | 43 | 100% |
| Adversarial | 28 | 100% |
| Cross-domain (tuned) | 57 | 96.5% |
| **Total** | **128** | **~98%** |

100% recall across all domains — zero false negatives.

## Architecture

```
Input → [Nyaya Gate] → [Vedic Gate] → [Arthashastra Gate] → Verdict
         Evidence       Constraints     Strategy
         Classification Verification    Assessment

Verdict: VERIFIED | FLAGGED | HALTED
```

- **No LLM dependencies** — pure Python, math only
- **Sub-millisecond** — runs in < 1ms on commodity hardware
- **Deterministic** — same input always produces same output
- **Auditable** — every verdict includes full reasoning chain

## License

MIT — Barbarian Labs
