# Entropic Core

Entropic Core is a reliability addon for agentic systems: it instruments long-running (single- and multi-agent) workflows with entropy-derived signals and provides hooks for regulation (interventions, healing, consensus) plus evidence (metrics, dashboards, artifacts).

## Core Value (1 sentence)
For developers building AI agents, Entropic Core adds observability + entropy-guided control so agent systems remain stable and auditable during long runs.

## What We Sell
Verifiable reliability for agent systems: fewer measurable failures with reproducible evidence.

## What It Guarantees (and What It Does Not)

### Guarantees
- A consistent control loop you can integrate: measure -> diagnose -> intervene -> record.
- Structured evidence: metrics, logs, and optional dashboards.
- Configurable policies to reduce manual tuning and make behavior more predictable.

### Does NOT Guarantee
- "Zero hallucinations" universally. It can only reduce measurable failure modes under defined tasks and verification.
- Factual truth without grounding. If the system has no tools/data or reference, claims may be unverifiable.
- Scientific proof of "physics of information" claims. Strong claims require formal methodology and peer review.

## Installation
```bash
pip install entropic-core
```

## Fast Adoption: 1 Install, 1 Command, 1 Report

```bash
pip install "entropic-core[evals]"
entropic-killer-demo --provider mock --model mock-v1 --out entropic_dx_runs --max-cases 20 --no-smokes
```

Open:
- `entropic_dx_runs/.../report.html`

## Commercial Clarity

### What You Get Today (OSS)
- Drop-in runtime reliability loop for agent calls.
- Reproducible A/B evals with verifiable checks.
- One shareable report per run (`report.html`) plus artifacts (`run.json`, JSONL, CSV).

### Commercial Roadmap
- Pro self-serve: hosted run history, scheduled evaluations, private dashboards, alerts.
- Team controls: shared workspaces, role-based access, audit timeline.
- Enterprise later: private deployment, SSO/RBAC hardening, compliance bundles, support SLA.

### Not Available Yet
- 24/7 support and guaranteed incident response.
- Full compliance packages (SOC2/ISO) and formal procurement process.
- Custom enterprise integrations and dedicated success team.

### Optional Extras
```bash
pip install "entropic-core[openrouter]"
pip install "entropic-core[dash]"
pip install "entropic-core[otel]"
pip install "entropic-core[evals]"
```

## Quickstart
```python
import entropic_core

# Recommended (drop-in): start a runtime session with an explicit mode.
# This creates a per-run folder with events + an HTML runtime report.
with entropic_core.protect(mode="balanced", provider="openrouter", run_dir="entropic_runs") as sess:
    # client = sess.wrap(client, provider="openrouter")
    pass

# Alternative: create middleware + wrap a provider client in-place
# (see docs/getting-started-openrouter.md for OpenRouter).
# mw = entropic_core.create_middleware()
# entropic_core.wrap(client, provider="openrouter", middleware=mw)

# Legacy: zero-config import-hook protection (kept for compatibility).
# entropic_core.protect()
```

## Docs and Examples
- Manual: `docs/README.md`
- Examples: `examples/README.md`
- Public benchmark: `evals/README.md` (includes `standard_v2` + `entropic-killer-demo`)

## API Stability
- Stable API surface (SemVer, intentionally small):
- `entropic_core.protect(...)` (import-hook mode or runtime session mode)
- `entropic_core.unprotect()`
- `entropic_core.create_middleware()`
- `entropic_core.wrap(client)`

- Experimental APIs:
- `entropic_core.experimental` (modules)
- `entropic_core.experimental.api` (legacy convenience symbols; may change in MINOR/PATCH)

See `DEPRECATION_POLICY.md` and `CHANGELOG.md`.
