Metadata-Version: 2.4
Name: autourgos-summarizer
Version: 1.0.1
Summary: Scratchpad compression middleware for Autourgos agents — prevents token overflow by auto-summarizing long reasoning chains.
Author-email: Jitin Kumar Sengar <devxjitin@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/devxjitin/autourgos-summarizer
Project-URL: Repository, https://github.com/devxjitin/autourgos-summarizer
Project-URL: Issues, https://github.com/devxjitin/autourgos-summarizer/issues
Keywords: autourgos,agent,middleware,summarizer,llm,token,scratchpad
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# autourgos-summarizer

Scratchpad compression middleware for [Autourgos](https://github.com/devxjitin) agents.

Automatically summarizes long reasoning chains so your agent never runs out of token space — even on tasks with dozens of iterations.

---

## Why use this?

LLM agents accumulate a **scratchpad** — a growing log of thoughts, tool calls, and observations. On long tasks this scratchpad can:

- Hit the LLM's context window limit and crash
- Slow down responses (more tokens = more cost and latency)
- Confuse the LLM with too much irrelevant history

`AutoSummarizeMiddleware` solves this by compressing the scratchpad in the background every N iterations (or when it exceeds a size limit), keeping only what matters: key findings, tool results, and current status.

---

## Install

```bash
pip install autourgos-summarizer
```

Zero dependencies. Works with any Autourgos agent.

---

## Quick Start

```python
from autourgos_summarizer import AutoSummarizeMiddleware
from autourgos_react_agent import ReactAgent

summarizer = AutoSummarizeMiddleware(
    summarize_every=5,          # compress every 5 iterations
    max_scratchpad_chars=15000, # also compress if scratchpad exceeds 15k chars
)

agent = ReactAgent(llm=my_llm, middleware=[summarizer])
result = agent.invoke("Research the latest breakthroughs in quantum computing")
print(result)
```

---

## How it works

`AutoSummarizeMiddleware` hooks into `on_iteration_start`. Before each iteration it checks:

1. Is this a multiple of `summarize_every`? (e.g. iteration 5, 10, 15…)
2. Is the scratchpad longer than `max_scratchpad_chars`?

If either is true, it calls the LLM (middleware's own `llm` if set, otherwise `agent.llm`) with a compression prompt that asks it to distill the scratchpad into:

```
[Summary of steps 1-N]
Key findings: ...
Tool results: ...
Current status: ...
```

This summary replaces the full scratchpad before the next LLM call. The agent continues from where it left off, but with a much smaller context.

Summarization runs **synchronously** (the agent loop is paused at this point), and a `threading.Lock` prevents duplicate summarizations when parallel tool callbacks fire.

---

## Use a dedicated LLM for summarization

You can pass a separate `llm` to `AutoSummarizeMiddleware`. This LLM is used **only** for compressing the scratchpad — great for keeping costs low by using a cheaper/faster model just for this job.

```python
from autourgos_summarizer import AutoSummarizeMiddleware
from autourgos_openaichat import OpenAIChatModel

# Main agent uses a powerful model
main_llm = OpenAIChatModel(model="gpt-4o")

# Summarizer uses a cheap fast model
cheap_llm = OpenAIChatModel(model="gpt-4o-mini")

summarizer = AutoSummarizeMiddleware(
    summarize_every=5,
    llm=cheap_llm,  # overrides agent.llm for summarization
)

agent = ReactAgent(llm=main_llm, middleware=[summarizer])
result = agent.invoke("Research the latest breakthroughs in quantum computing")
print(result)
```

If `llm` is not provided, it falls back to `agent.llm` automatically.

---

## Parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `summarize_every` | `int \| None` | `5` | Summarize every N iterations. `None` = disable iteration-based trigger. |
| `max_scratchpad_chars` | `int` | `15000` | Also trigger if scratchpad exceeds this many characters. |
| `llm` | any | `None` | LLM for summarization. Needs `.invoke(prompt)`. Falls back to `agent.llm` if not set. |

---

## Combine with other middleware

```python
from autourgos_summarizer import AutoSummarizeMiddleware
from autourgos_history import AgentHistoryMiddleware

history    = AgentHistoryMiddleware()
summarizer = AutoSummarizeMiddleware(summarize_every=5)

agent = ReactAgent(llm=my_llm, middleware=[summarizer, history])
```

---

## Requirements

- Python 3.9+
- Any Autourgos agent that exposes `agent.scratchpad`, `agent.llm`, and `agent.query`

---

## License

MIT — see [LICENSE](LICENSE)
