Metadata-Version: 2.4
Name: cellstate
Version: 0.5.7
Summary: Python SDK for CELLSTATE -- the memory & orchestration layer for AI agents
Project-URL: Homepage, https://cellstate.batterypack.dev
Project-URL: Repository, https://github.com/TheFreeBatteryFactory/CellState
Project-URL: Documentation, https://cellstate.batterypack.dev
Project-URL: Issues, https://github.com/TheFreeBatteryFactory/CellState/issues
Author-email: Eassa Ayoub <hello@heyoub.dev>
License-Expression: Apache-2.0
Keywords: agent,ai,cellstate,context,hierarchical,llm,memory
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software 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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: msgpack>=1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: websockets>=13.0
Provides-Extra: all
Requires-Dist: crewai>=0.30; extra == 'all'
Requires-Dist: langgraph>=0.2; extra == 'all'
Requires-Dist: langmem>=0.1; extra == 'all'
Requires-Dist: pydantic-ai>=0.1; extra == 'all'
Provides-Extra: crewai
Requires-Dist: crewai>=0.30; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.2; extra == 'langgraph'
Provides-Extra: langmem
Requires-Dist: langmem>=0.1; extra == 'langmem'
Provides-Extra: pydantic-ai
Requires-Dist: pydantic-ai>=0.1; extra == 'pydantic-ai'
Description-Content-Type: text/markdown

# cellstate

Python SDK for [CELLSTATE](https://cellstate.batterypack.dev) -- the memory and orchestration layer for AI agents.

## Installation

```bash
pip install cellstate
```

With framework adapters:

```bash
pip install cellstate[langgraph]    # LangGraph checkpointer
pip install cellstate[langmem]      # LangMem memory store
pip install cellstate[pydantic-ai]  # PydanticAI state
pip install cellstate[all]          # Everything
```

## Quick Start

```python
from cellstate import CellstateClient

client = CellstateClient(
    api_key="cst_...",
    tenant_id="your-tenant-id",
)

# Create a trajectory (task container)
trajectory = await client.trajectories.create(
    name="Build feature X",
    description="Implement the new feature",
)

# Create a scope (context window)
scope = await client.scopes.create(
    trajectory_id=trajectory["trajectory_id"],
    name="Implementation",
    token_budget=8000,
)

# Store an artifact
artifact = await client.artifacts.create(
    trajectory_id=trajectory["trajectory_id"],
    scope_id=scope["scope_id"],
    artifact_type="Code",
    name="feature.py",
    content="def feature(): ...",
    source_turn=1,
    extraction_method="Explicit",
    ttl="Persistent",
)
```

## Framework Adapters

### LangGraph

```python
from cellstate.adapters.langgraph import CellstateCheckpointer

checkpointer = CellstateCheckpointer(
    api_key="cst_...",
    tenant_id="...",
)
graph = StateGraph(State)
graph.compile(checkpointer=checkpointer)
```

### LangMem

```python
from cellstate.adapters.langmem import CellstateMemoryStore

store = CellstateMemoryStore(api_key="cst_...", tenant_id="...")
await store.add_memory("User prefers dark mode")
results = await store.search_memories("UI preferences")
```

## Adapter Conformance Guardrails

Adapter layering and surface-area drift are enforced by tests:

- `tests/test_adapter_conformance.py` checks module complexity budgets.
- Public adapter method surfaces are pinned to golden fixtures.
- Allowed `self.client.<manager>` usage is pinned per adapter module.

Golden fixture location:

- `tests/fixtures/adapter_protocol_golden.json`

When intentionally changing adapter APIs or architecture, update the fixture in
the same PR so drift is explicit and reviewable.

## License

Apache-2.0
