# UASS - Unified Agent State System

A universal state management system that enables cross-framework communication between AI agent frameworks (LangGraph, AutoGen, CrewAI, etc.) through a unified state store.

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    Framework Layer                           │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │LangGraph │  │ AutoGen  │  │ CrewAI   │  │  Custom  │   │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘   │
│       │             │              │             │          │
│       └─────────────┴──────────────┴─────────────┘          │
│                          │
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                    UASS SDK Layer                            │
│  ┌──────────────────────────────────────────────────────┐   │
│  │         Unified State API (Python/TypeScript)        │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                    Backend Layer                             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                  │
│  │  Redis   │  │PostgreSQL│  │  Memory  │  (pluggable)     │
│  └──────────┘  └──────────┘  └──────────┘                  │
└─────────────────────────────────────────────────────────────┘
```

## Features

- **Unified State Schema**: Standardized state format across all frameworks
- **Cross-Framework Communication**: Any node from any framework can read/write state
- **Pluggable Backends**: Redis, PostgreSQL, in-memory, etc.
- **Framework Adapters**: Easy integration with LangGraph, AutoGen, CrewAI
- **MCP Protocol Support**: Native Model Context Protocol server for AI-native access
- **Type Safety**: Full type definitions for state structures
- **Session Management**: Multi-session support with isolation
- **State Versioning**: Track state changes over time

## 🚀 Try it in 30 Seconds (Zero Setup)

Want to see it in action without installing Redis? Run our zero-setup quickstart script:

```bash
python3 quickstart.py
```

This simulates two agents talking to each other using the in-memory backend.

## Quick Start (Production)

```python
from uass import UASSClient, RedisBackend

# Initialize client
client = UASSClient(backend=RedisBackend(host='localhost', port=6379))

# Write state from any framework
client.write_state(
    session_id="session_123",
    agent_id="agent_1",
    framework="langgraph",
    state={"tokens": 100, "context": "processing..."}
)

# Read state from any other framework
state = client.read_state("session_123", "agent_1")
```

## Backend Options

UASS supports multiple backends - choose based on your needs:

### Redis (Default - Best for Real-time)
```python
from uass import UASSClient, RedisBackend
client = UASSClient(backend=RedisBackend())
```
**Best for:** Real-time access, high-frequency updates, pub/sub events

### PostgreSQL (Best for Analytics)
```python
from uass import UASSClient, PostgreSQLBackend
client = UASSClient(backend=PostgreSQLBackend())
```
**Best for:** Complex queries, large states, analytics, ACID transactions

### Hybrid (Best of Both Worlds)
```python
from uass import UASSClient, RedisBackend, PostgreSQLBackend, HybridBackend
redis = RedisBackend()
postgres = PostgreSQLBackend()
client = UASSClient(backend=HybridBackend(redis, postgres))
```
**Best for:** Production systems needing both speed and analytics

### Memory (Testing Only)
```python
from uass import UASSClient, MemoryBackend
client = UASSClient(backend=MemoryBackend())
```
**Best for:** Development and testing

See [Backend Comparison Guide](docs/BACKEND_COMPARISON.md) for detailed recommendations.

## Installation

### Basic Installation

```bash
pip install uass
```

This installs UASS with Redis support (default backend).

### Optional Dependencies

```bash
# With PostgreSQL support
pip install uass[postgresql]

# With hybrid backend (Redis + PostgreSQL)
pip install uass[hybrid]

# With test dependencies (includes LangGraph for integration tests)
pip install uass[test]

# With all optional dependencies
pip install uass[all]
```

### For Development

```bash
# Clone repository
git clone https://github.com/yourusername/uass.git
cd uass

# Install in development mode
pip install -e .

# Install test dependencies (includes LangGraph, etc.)
pip install -r requirements-test.txt
```

See [INSTALL.md](INSTALL.md) for detailed installation instructions.

## Testing

### Unit Tests (No Dependencies)

```bash
pytest tests/unit/ -v
```

### Integration Tests (Requires Frameworks)

```bash
# Install test dependencies first
pip install -r requirements-test.txt

# Run integration tests
pytest tests/integration/ -v
```

## Documentation

- [Installation Guide](INSTALL.md)
- [Quick Start Guide](docs/QUICKSTART.md)
- [MCP Integration](docs/MCP_INTEGRATION.md)
- [Backend Comparison](docs/BACKEND_COMPARISON.md)
- [Backend Recommendations](docs/BACKEND_RECOMMENDATION.md)
- [State Schema Reference](docs/STATE_SCHEMA.md)
- [Architecture Overview](docs/ARCHITECTURE.md)

## Examples

- [Basic Usage](examples/basic_usage.py)
- [Cross-Framework Communication](examples/cross_framework.py)
- [Token Tracking](examples/token_tracking.py)
- [LangGraph Integration](examples/langgraph_integration_example.py)

