Metadata-Version: 2.4
Name: agentstateprotocol
Version: 0.1.0
Summary: Checkpointing and recovery protocol for AI agents
Author: AgentStateProtocol Contributors
License: MIT
Project-URL: Homepage, https://github.com/ekessh/agentstateprotocol
Project-URL: Documentation, https://agentstateprotocol.readthedocs.io
Project-URL: Repository, https://github.com/ekessh/agentstateprotocol
Project-URL: Issues, https://github.com/ekessh/agentstateprotocol/issues
Keywords: ai,agents,checkpointing,recovery,state-management,llm,reasoning,rollback,branching
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Dynamic: license-file

# AgentStateProtocol

Checkpointing and recovery protocol for AI agents.

`AgentStateProtocol` lets an agent save state at each reasoning step, branch into alternatives, and roll back safely after failures.

## Install

```bash
pip install agentstateprotocol
```

## Quick Start

```python
from agentstateprotocol import AgentStateProtocol

agent = AgentStateProtocol("my-agent")

agent.checkpoint(
    state={"task": "summarize quarterly report", "stage": "parsed"},
    metadata={"confidence": 0.91},
    description="Initial parse",
    logic_step="parse_input",
)

agent.checkpoint(
    state={"task": "summarize quarterly report", "stage": "drafted"},
    metadata={"confidence": 0.86},
    description="Draft generated",
    logic_step="draft_summary",
)

# Roll back one step if needed
agent.rollback()
```

## Core Operations

- `agent.checkpoint(...)`: save a state snapshot
- `agent.rollback(...)`: restore a previous checkpoint
- `agent.branch(name)`: start an alternate reasoning path
- `agent.switch_branch(name)`: move between branches
- `agent.merge(source_branch)`: merge branch outcomes
- `agent.history()`: inspect checkpoint timeline
- `agent.visualize_tree()`: show decision tree

## Decorators

```python
from agentstateprotocol.decorators import agentstateprotocol_step

@agentstateprotocol_step("analyze")
def analyze(state):
    return {"result": "ok", **state}
```

## Storage

```python
from agentstateprotocol.storage import FileSystemStorage, SQLiteStorage

file_storage = FileSystemStorage(".agentstateprotocol")
sqlite_storage = SQLiteStorage(".agentstateprotocol/agentstateprotocol.db")
```

## CLI

```bash
agentstateprotocol demo
agentstateprotocol log
agentstateprotocol tree
agentstateprotocol branches
agentstateprotocol diff <checkpoint_a> <checkpoint_b>
agentstateprotocol metrics
```

## Project

- Repository: https://github.com/ekessh/agentstateprotocol
- License: MIT
