uass 0.1.0

Unified Agent State System - Cross-framework state management for AI agents

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
• 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:

python3 quickstart.py

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

Quick Start (Production)

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)

from uass import UASSClient, RedisBackend
client = UASSClient(backend=RedisBackend())

Best for: Real-time access, high-frequency updates, pub/sub events

PostgreSQL (Best for Analytics)

from uass import UASSClient, PostgreSQLBackend
client = UASSClient(backend=PostgreSQLBackend())

Best for: Complex queries, large states, analytics, ACID transactions

Hybrid (Best of Both Worlds)

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)

from uass import UASSClient, MemoryBackend
client = UASSClient(backend=MemoryBackend())

Best for: Development and testing

See Backend Comparison Guide for detailed recommendations.

Installation

Basic Installation

pip install uass

This installs UASS with Redis support (default backend).

Optional Dependencies

# 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

# 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 for detailed installation instructions.

Testing

Unit Tests (No Dependencies)

pytest tests/unit/ -v

Integration Tests (Requires Frameworks)

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

# Run integration tests
pytest tests/integration/ -v

Documentation

• Installation Guide
• Quick Start Guide
• Backend Comparison
• Backend Recommendations
• State Schema Reference
• Architecture Overview

Examples

• Basic Usage
• Cross-Framework Communication
• Token Tracking
• LangGraph Integration