Metadata-Version: 2.4
Name: agent-context-recovery
Version: 0.1.0
Summary: Context recovery for AI agents — analyze fatigue, compress context, improve token efficiency
Author: ai-agent-recovery
License-Expression: MIT
Project-URL: Homepage, https://agent-cop.dev
Project-URL: Source, https://github.com/ai-agent-recovery/agent-spa
Keywords: ai,agents,context,recovery,llm,tokens
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: deep
Requires-Dist: openai>=1.0; extra == "deep"

# agent-cop

Context recovery for AI agents. Analyze fatigue, compress context, improve token efficiency.

```python
from agent_cop import analyze, recover

# Detect context bloat
report = analyze(messages)
# → { fatigue_score: 73, issues: [...], ... }

# Recover with algorithmic compression (free, no API key needed)
result = await recover(messages, budget_ratio=0.4)
# → { messages: [...], stats: { compression_ratio: "62.3%", ... } }

# Recover with LLM-based deep summarization (requires openai key)
result = await recover(messages, deep=True, openai_api_key="sk-...")
```

## Quick install

```bash
pip install agent-cop
```

For deep LLM summarization:

```bash
pip install "agent-cop[deep]"
```

## API

### `analyze(messages)`

Detect context fatigue and bloat in a message history.

### `recover(messages, budget_ratio=0.5, deep=False, openai_api_key=None)`

Compress a message history to fit within a budget. Algorithmic by default (free). Pass `deep=True` with an OpenAI key for semantic LLM-based summarization.

## LangChain integration

```python
from agent_cop.langchain import CopCallback
from langchain.agents import AgentExecutor

callback = SpaCallback(threshold=0.8)
agent = AgentExecutor(..., callbacks=[callback])
# Auto-recovers context at 80% token usage
```

## REST API

```bash
curl -X POST https://api.agent-spa.dev/v1/recover \
  -H "x-api-key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages": [...], "budget_ratio": 0.4, "deep": true}'
```

Generate a free API key at [https://agent-cop.dev](https://agent-cop.dev).

## License

MIT
