Metadata-Version: 2.4
Name: lore-agents
Version: 0.2.0
Summary: Agent reliability layer: circuit breakers, dead letter queues, cost guards, and verification loops for any AI agent framework
Project-URL: Homepage, https://github.com/overseerclaw/lore-agents
Project-URL: Repository, https://github.com/overseerclaw/lore-agents.git
Project-URL: Issues, https://github.com/overseerclaw/lore-agents/issues
Author: Miles
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,circuit-breaker,dlq,llm,lore,reliability
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: rich>=13.0
Provides-Extra: all
Requires-Dist: click>=8.1; extra == 'all'
Requires-Dist: redis>=4.0; extra == 'all'
Requires-Dist: rich>=13.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: redis
Requires-Dist: redis>=4.0; extra == 'redis'
Description-Content-Type: text/markdown

# lore-agents

[![PyPI](https://img.shields.io/pypi/v/lore-agents)](https://pypi.org/project/lore-agents/)
[![Python](https://img.shields.io/pypi/pyversions/lore-agents)](https://pypi.org/project/lore-agents/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**Agent reliability layer.** Adds circuit breakers, dead letter queues, cost guards, model routing, and execution tracing to any AI agent framework.

## Install

```bash
pip install lore-agents
```

## Quick Start

```python
from lore import CircuitBreaker, CostGuard, DeadLetterQueue, LoreTrace, lore_wrap

# Wrap any LLM call with full reliability stack
safe_call = lore_wrap(
    my_llm_function,
    name="openai",
    failure_threshold=3,
    session_limit_usd=5.0,
)
result = safe_call("Hello, world!")
```

## Features

### Circuit Breaker
Prevents cascading failures when LLM providers go down.

```python
from lore import CircuitBreaker

cb = CircuitBreaker(name="openai", failure_threshold=3, recovery_timeout=30)
result = cb.call(openai_chat, prompt="hello")

# Or use as a decorator
from lore import circuit_breaker

@circuit_breaker(name="anthropic", threshold=5)
def call_claude(prompt: str) -> str:
    return client.messages.create(...)
```

**States:** CLOSED (normal) -> OPEN (rejecting) -> HALF_OPEN (probing) -> CLOSED

### Dead Letter Queue
SQLite-backed queue that captures failed tasks with automatic error classification.

```python
from lore import DeadLetterQueue

dlq = DeadLetterQueue()

try:
    result = agent.run(task)
except Exception as e:
    dlq.push("task-123", e, context='{"model": "gpt-4o"}')

# Replay transient failures
entries = dlq.replay_transient(rate=10)
```

**Classification:** Transient (retry) | Permanent (park) | Ambiguous (one retry)

### Cost Guard
Per-task and per-session spending limits with alerting.

```python
from lore import CostGuard

guard = CostGuard(session_limit_usd=5.00, task_limit_usd=0.50)
guard.check_budget("task-1")  # Pre-flight check
guard.record("gpt-4o", input_tokens=1000, output_tokens=500, task_id="task-1")
print(guard.get_summary())
```

### Model Router
3-tier routing (budget/mid/frontier) with latency tracking and fallback cascades.

```python
from lore import ModelRouter, ModelTier

router = ModelRouter(
    task_type_map={"crud": ModelTier.BUDGET, "architecture": ModelTier.FRONTIER}
)
model = router.route("crud")  # -> cheapest healthy model
```

### Execution Tracing
Step-level cost and duration tracking, exportable to JSON.

```python
from lore import LoreTrace

tracer = LoreTrace("customer_support")
with tracer.step("classify", model="gpt-4o-mini") as s:
    result = classify(query)
    s.input_tokens = 150
    s.output_tokens = 20

tracer.finish()
print(tracer.to_json())
```

### Audit Scanner
Scans agent code for missing reliability patterns.

```python
from lore import LoreAudit

audit = LoreAudit("/path/to/project")
report = audit.scan()
print(report.to_json())
```

## CLI

```bash
lore install .          # Install reliability rules + pre-commit hooks
lore audit .            # Scan for missing patterns
lore audit . -j         # JSON output
lore trace trace.json   # View a trace file
lore wrap               # Show wrap usage examples
```

## Optional Dependencies

```bash
pip install lore-agents[redis]  # Redis-backed circuit breaker persistence
pip install lore-agents[dev]    # Development tools (pytest, mypy, ruff)
```

## CI/CD Integration

[![Lore Audit](https://github.com/Miles0sage/lore-agents/actions/workflows/lore-audit.yml/badge.svg)](https://github.com/Miles0sage/lore-agents/actions/workflows/lore-audit.yml)

Run `lore audit` automatically on every PR with GitHub Actions.

### Quick Setup

```bash
mkdir -p .github/workflows
curl -o .github/workflows/lore-audit.yml \
  https://raw.githubusercontent.com/Miles0sage/lore-agents/main/.github/workflows/lore-audit.yml
git add .github/workflows/lore-audit.yml
git commit -m "ci: add lore agent reliability audit"
git push
```

This will:
- Audit every PR that changes Python files and post a comment with the reliability score
- Run on every push to `main`
- Run weekly (Monday 6am UTC) to catch drift

See [`examples/github-actions-setup.md`](examples/github-actions-setup.md) for customization options.

## License

MIT
