Metadata-Version: 2.4
Name: steer-sdk
Version: 0.1.2
Summary: The Active Reliability Layer for AI Agents
Author: Steer Dev
Author-email: imtt.dev.contact@gmail.com
Requires-Python: >=3.13,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: fastapi (>=0.122.0,<0.123.0)
Requires-Dist: google (>=3.0.0,<4.0.0)
Requires-Dist: google-cloud-storage (>=3.6.0,<4.0.0)
Requires-Dist: httpx (>=0.28.1,<0.29.0)
Requires-Dist: langchain (>=1.1.0,<2.0.0)
Requires-Dist: langchain-openai (>=1.1.0,<2.0.0)
Requires-Dist: litellm (>=1.80.5,<2.0.0)
Requires-Dist: opentelemetry-api (>=1.38.0,<2.0.0)
Requires-Dist: pydantic (>=2.12.4,<3.0.0)
Requires-Dist: python-dotenv (>=1.2.1,<2.0.0)
Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
Requires-Dist: rich (>=14.2.0,<15.0.0)
Requires-Dist: uvicorn (>=0.38.0,<0.39.0)
Project-URL: Bug Tracker, https://github.com/imtt-dev/steer/issues
Project-URL: Homepage, https://github.com/imtt-dev/steer
Project-URL: Repository, https://github.com/imtt-dev/steer
Description-Content-Type: text/markdown

# ⚡ Steer
### The Active Reliability Layer for AI Agents.

**Stop debugging. Start teaching.**  
Steer is an open-source telemetry and verification SDK designed to catch "Confident Idiot" agents in production before they break trust with your users.

[![PyPI version](https://badge.fury.io/py/steer-sdk.svg)](https://badge.fury.io/py/steer-sdk)

---

## 🛑 The Problem

Agents fail in dangerous ways that standard evaluations miss:
1.  **Strict JSON failures:** Wrapping output in markdown.
2.  **Safety leaks:** Outputting PII despite system prompts.
3.  **Ambiguity:** Guessing "Springfield, IL" when the user didn't specify a state.

**Steer wraps your agent in a Verification Layer that catches these logic, context, and format failures in real-time.**

---
## 🚀 See Steer in Action

The Steer workflow is simple: **Catch → Teach → Fix.**

### 1. Fix Broken JSON
**The Problem:** Agents often wrap JSON in Markdown (```json), breaking your app.
**The Fix:** Steer blocks the bad output. You click "Strict JSON" in the UI. The agent learns.

```text
# Run 1: Failure
[Steer] 🤖 Generating profile...
[Steer] 🚨 BLOCKED: Structure Guard Triggered (Detected Markdown).
[Steer] 👉 Go to 'steer ui' to teach the agent.

# Run 2: Success (After Teaching)
[Steer] 🧠 Context loaded: Rules found! Applying fix...
[Steer] ✅ SUCCESS: Agent output valid JSON.
```

### 2. Prevent Data Leaks
**The Problem:** Agents accidentally output PII (emails/keys) despite system prompts.
**The Fix:** Steer's regex guard halts the execution before data leaves the server.

```text
[Steer] 🤖 Summarizing ticket...
[Steer] 🚨 BLOCKED: PII Shield Triggered (Visible email address).
[Steer] 🛡️ Action Blocked.
```

### 3. Enforce Business Logic
**The Problem:** An agent guesses an ambiguous answer (e.g., "Springfield") instead of asking the user.
**The Fix:** Steer forces the agent to ask clarifying questions when search results are ambiguous.

```text
# Run 1: Failure
[Steer] 🤖 Searching for 'Springfield'...
[Steer] 🚨 BLOCKED: Business Logic Guard (34 results found, expected clarification).

# Run 2: Success (After Teaching)
[Steer] 🧠 Context loaded: Ambiguity rules active.
[Steer] ✅ SUCCESS: Agent asked: "Which state are you interested in?"
```

---

## 🔮 Roadmap: From Verification to Learning

Steer v0.1 provides deterministic guardrails (The "Fast Path").
Steer v0.2+ will provide probabilistic improvement (The "Slow Path").

**Coming Soon:**

*   **Query by Committee:** Automated consensus checks for ambiguous prompts.
*   **The Teaching Dashboard:** A UI to review failures and provide human corrections.
*   **Automated Fine-Tuning:** A pipeline to turn your (failure, correction) logs into a fine-tuned model that stops making those mistakes.

---

## 📦 Installation

```bash
pip install steer-sdk
```

## ⚡ Quickstart

The fastest way to see Steer in action is to generate the interactive examples.

### 1. Generate Demos
Run this in your terminal to create 3 example agents:
```bash
steer init
```
*> Created 01_structure_guard.py*
*> Created 02_safety_guard.py*
*> Created 03_logic_guard.py*

### 2. The Workflow (Fail → Teach → Fix)
Steer is designed to be interactive. Try the **Structure Guard** demo:

1.  **Run & Fail:**
    The agent attempts to output JSON but wraps it in Markdown (a common LLM error). Steer blocks it.
    ```bash
    python 01_structure_guard.py
    # 🚨 BLOCKED: Detected Markdown code blocks.
    ```

2.  **Teach:**
    Open the dashboard to see the incident and provide a fix.
    ```bash
    steer ui
    ```
    *   Go to **http://localhost:8000**
    *   Click **Teach** on the active incident.
    *   Select **"Strict JSON Mode"** (or write a custom rule) and click **Save**.

3.  **Run & Succeed:**
    Run the script again. The agent detects the new rule and self-corrects.
    ```bash
    python 01_structure_guard.py
    # 🧠 Context loaded: Rules found! Applying fix...
    # ✅ SUCCESS: Agent output valid JSON.
    ```

## 🛠️ Integration

To add Steer to your own existing agent:

```python
from steer import capture
from steer.verifiers import JsonVerifier

# 1. Define Verifiers
json_check = JsonVerifier(name="Strict JSON")

# 2. Decorate your Agent Function
@capture(verifiers=[json_check])
def my_agent(user_input):
    # Your LLM call here
    return llm_response
```
