Metadata-Version: 2.4
Name: wail-runtime
Version: 1.0.0
Summary: AI Runtime Control and Governance Layer for existing provider clients. WAIL observes execution, detects unhealthy runtime behavior, retries or reroutes when intervention is justified, and records decisions as signed, verifiable evidence.
Author: WOVO Inc.
License-Expression: LicenseRef-Proprietary
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=42.0.0
Requires-Dist: rich
Requires-Dist: python-ulid>=2.5.0
Requires-Dist: filelock>=3.17.0
Dynamic: license-file

<p align="center">
  <img src="docs/images/wail-logo.png" alt="WAIL" width="650">
</p>

<h3 align="center">AI Runtime Control & Governance Layer</h3>

<p align="center">
  Runtime detection · Runtime control · Governance · Signed execution evidence
</p>

<p align="center">
  <a href="docs/getting-started.md">Getting Started</a> ·
  <a href="docs/architecture.md">Architecture</a> ·
  <a href="docs/runtime-control.md">Runtime Control</a> ·
  <a href="docs/evidence-model.md">Evidence Model</a> ·
  <a href="docs/why-wail.md">Why WAIL</a> ·
  <a href="docs/telemetry.md">Telemetry</a>
</p>

AI requests don't always behave as expected.

They slow down, time out, fail, or become unreliable.

Most applications can detect these runtime issues. Few can control what happens next.

WAIL is an AI runtime control and governance layer for your existing provider clients. It observes execution as it happens, detects unhealthy runtime behavior, and can retry or reroute execution when intervention is justified. Every decision and action can be recorded as signed, verifiable evidence.

WAIL is not a gateway. It works with your existing provider SDK and request flow instead of replacing them.

Runtime reroute applies to the next request and does not permanently change the model or provider configured by your application.

---

## Architecture

![WAIL Architecture](docs/images/overview-architecture.png)

---

## What WAIL Does

- **Detect Runtime Issues** — Observe AI execution and identify abnormal latency, streaming behavior, errors, timeouts, and other runtime degradation.
- **Assess Execution Health** — Determine how serious a runtime issue is and whether it justifies intervention.
- **Evaluate Alternatives** — Compare observed models and providers using live runtime measurements when another execution path may be needed.
- **Control Runtime Execution** — Retry or reroute when runtime conditions and policy justify intervention; otherwise preserve the application's current execution path.
- **Record What Happened** — Produce signed, verifiable runtime evidence for decisions, actions, and execution outcomes.
- **Support Governance** — Preserve structured incident and execution records for governance, audit, and compliance workflows where enabled.

### Runtime Control Loop

```text
Runtime measurements
        ↓
Baseline + anomaly detection
        ↓
Risk / severity evaluation
        ↓
Candidate scoring
        ↓
Runtime decision
        ↓
Intervention when required
(next request for runtime reroute)
        ↓
Signed execution evidence
```

WAIL does not route requests simply because another model scores better. Candidate ranking informs runtime control; intervention remains driven by observed runtime conditions and control policy.

---

## Installation

Install WAIL from PyPI:

```bash
pip install wail
```

---

## Quick Start

Wrap your existing AI client with WAIL.

```python
from openai import OpenAI
import wail

client = wail.wrap(OpenAI())
```

Use it exactly as you normally would.

```python
response = client.responses.create(
    model="gpt-4o-mini",
    input="Explain what WAIL does."
)

print(response.output_text)
```

After each request, WAIL prints a runtime summary.

```text
[WAIL] AI Runtime Control Layer
----------------------------------------------------------------------

[14:33:10] Plan                   Developer
[14:33:10] Provider               openai
[14:33:10] Model                  gpt-4o-mini

[14:33:10] Duration               842 ms   (1.08x)
[14:33:10] TTFT                   186 ms   (0.94x)
[14:33:10] Throughput             42.50 tok/s
[14:33:10] Mean Token Gap         24 ms

[14:33:10] Active Signals         0
[14:33:10] Runtime Severity       NONE
[14:33:10] Risk Score             0.00
[14:33:10] Dominant Surface       NONE

[14:33:10] Decision               OBSERVE
[14:33:10] Trace                  SAVED · 01M00N3X...
----------------------------------------------------------------------
```

Every execution also generates a signed runtime artifact that includes:

- Runtime observations
- Execution assessment
- Runtime decisions
- Control actions
- Execution outcome
- Cryptographic integrity metadata

---

## Supported Providers

| Provider | Runtime Detection | Runtime Control | Runtime Evidence |
|----------|:-----------------:|:---------------:|:----------------:|
| OpenAI | ✅ | ✅ | ✅ |
| Anthropic | ✅ | ✅ | ✅ |
| Google Gemini | ✅ | ✅ | ✅ |
| OpenAI-compatible Local LLM | ✅ | ✅ | ✅ |
| OpenRouter | ✅ | ✅ | ✅ |

The runtime evidence model remains consistent across all supported providers.

---

## CLI

Inspect and verify runtime artifacts directly from the command line.

```bash
wail traces incidents

wail trace show <TRACE_ID>

wail verify <ARTIFACT_FILE>
```

---

## Documentation

Learn more about WAIL:

- [Getting Started](docs/getting-started.md)
- [Why WAIL](docs/why-wail.md)
- [Architecture](docs/architecture.md)
- [Runtime Control](docs/runtime-control.md)
- [Runtime Evidence Model](docs/evidence-model.md)
- [Provider Integration](docs/provider-integration.md)
- [Runtime Artifact Reference](docs/artifact-reference.md)
- [CLI Reference](docs/CLI.md)
- [Telemetry](docs/telemetry.md)
