Metadata-Version: 2.4
Name: solidstate-fsm
Version: 0.1.0
Summary: A high-reliability, lightweight agent state machine runtime.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.7.0
Requires-Dist: openai>=1.0.0
Requires-Dist: google-generativeai>=0.5.0
Requires-Dist: ollama>=0.2.0
Requires-Dist: boto3>=1.34.0
Requires-Dist: redis>=5.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: fastapi>=0.111.0; extra == "dev"
Requires-Dist: uvicorn>=0.30.0; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"
Dynamic: license-file

# SolidState
A high-reliability, lightweight agent state machine runtime.

This project maps to the article/PDF proposal:

```text
receive input
update state
call model
parse tool call
evaluate policy
execute or interrupt
update state
checkpoint
trace
continue or finish
```

The goal is not to replace LangChain, LangGraph, Semantic Kernel, OpenAI Agents SDK, CrewAI, or AutoGen.

The goal is to expose the runtime mechanics clearly.

## Core runtime components

- **Async & Parallel Execution**: Built for non-blocking I/O with parallel tool execution support.
- **StateGraph Engine**: A minimal graph-based orchestrator for multi-agent handoffs and complex workflows.
- **Smart Caching**: Built-in response caching to reduce latency and model costs.
- **Context Management**: Automatic message history trimming to stay within context limits.
- **Streaming Ready**: Architecture supports token-by-token streaming for responsive UIs.
- **Conditional Routing**: Dynamic runtime routing using custom logic functions.
- **Symbolic Syntax**: Clean, expressive chaining using the `>>` operator.
- **Visualization**: Built-in support for generating Mermaid diagrams of your workflows.
- **Multi-Provider**: Adapters for OpenAI, Google Gemini, Anthropic (via AWS Bedrock), and Ollama (local).
- **AWS Ready**: Built-in support for **Amazon Bedrock** (models) and **Amazon DynamoDB** (persistence).
- **Cloud Native**: Distributed state via **Redis** and structured observability via **CloudWatch JSON Tracing**.
- **Message state**: Standardized format for system, user, and assistant/model turns.
- **Tool registry**: Dynamic function registration with multi-tool support.
- **Tool schema generator**: Automatic JSON schema generation with Pydantic support.
- **Policy evaluator**: Extensible rules for tool approval and rejection.
- **Execution engine**: Robust loop with max-step controls and error handling.
- **State store/checkpointer**: JSON-based persistence for pause/resume.
- **Tracing and audit log**: Detailed JSONL logs for every internal decision.

## Install

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

## Run examples

| File | Feature Demonstrated |
| :--- | :--- |
| `01_basic_runtime.py` | Simple agent conversation loop. |
| `02_tool_execution.py` | Tool registration and successful execution. |
| `03_policy_interrupt.py` | Safety policies and automatic rejections. |
| `04_resume_after_approval.py` | Human-in-the-loop (Pause & Resume). |
| `05_credit_review_demo.py` | Real-world banking workflow simulation. |
| `06_ollama_local_run.py` | Running on 100% local hardware. |
| `07_multi_agent_graph.py` | Orchestrating multiple specialized agents. |
| `08_symbolic_chaining.py` | Using the `>>` operator for clean pipelines. |
| `09_conditional_router.py` | Dynamic routing and Mermaid visualization. |
| `10_performance_bench.py` | Smart Caching and Context Trimming. |
| `11_researcher_writer_graph.py` | Complex 3-agent reasoning pipeline. |
| `12_structured_data_extraction.py` | Pydantic model support for tool arguments. |
| `13_error_recovery_retry.py` | Self-healing agents (retrying on tool failure). |
| `14_manual_state_injection.py` | Programmatic state manipulation. |
| `15_aws_lambda_handler.py` | Deployment template for AWS Lambda + DynamoDB. |
| `16_distributed_redis_state.py` | Distributed state management using Redis. |
| `17_cloudwatch_tracing.py` | Structured JSON observability for CloudWatch. |
| `18_parallel_tool_execution.py` | Concurrent execution of multiple tool calls using asyncio.gather. |
| `19_multi_threaded_actor_graph.py` | Graph execution in multi-threaded Actor Mode. |
| `20_token_streaming.py` | Real-time token streaming from the model adapter. |

## Project philosophy

The model reasons.

The runtime controls execution.

Every serious agent framework has to answer the same engineering question:

> How do we let a probabilistic system participate in deterministic business execution without losing control?

## Documentation

The framework is documented in 10 chapters, covering the journey from core state machine philosophy to a production-ready concurrent system:

1.  [**Introduction**](docs/intro.md): Philosophy and core pillars.
2.  [**Chapter 1: Philosophy & The State Machine Pattern**](docs/chapter1_philosophy_state_machine.md): Deterministic control over probabilistic models.
3.  [**Chapter 2: The Core Loop Execution**](docs/chapter2_core_loop_execution.md): Step limits, context trimming, and execution loops.
4.  [**Chapter 3: Message & State Representation**](docs/chapter3_message_state_representation.md): Structuring states, roles, and timestamps.
5.  [**Chapter 4: The Tool Registry & Parameter Introspection**](docs/chapter4_tool_registry_introspection.md): Auto-boxing schemas and execution safety boundaries.
6.  [**Chapter 5: Guardrails, Policies & Human-in-the-Loop**](docs/chapter5_policies_human_in_the_loop.md): Governance, Evaluator decisions, and asymmetric approvals.
7.  [**Chapter 6: Multi-Agent Orchestration & The StateGraph**](docs/chapter6_multi_agent_stategraph.md): Nodes, edges, routers, and symbolic `>>` operator chaining.
8.  [**Chapter 7: Concurrency & The Multi-threaded Actor Model**](docs/chapter7_concurrency_actor_model.md): Multi-threaded queue-based actors and worker threads.
9.  [**Chapter 8: Memory & State Persistence (Checkpointing)**](docs/chapter8_memory_state_persistence.md): BaseCheckpointer contracts, Local files, Redis, and DynamoDB.
10. [**Chapter 9: Observability, Observational Integrity & Tracing**](docs/chapter9_observability_tracing.md): Auditing decisions, JSONL records, and CloudWatch structures.
11. [**Chapter 10: Production Performance, Caching & Cloud Serverless**](docs/chapter10_production_performance_cloud.md): Adapters, flyweight caching, and AWS Lambda serverless handlers.

## Tests

The project includes a robust test suite covering 100% of the core logic:

```bash
pytest
```

| Suite | Focus |
| :--- | :--- |
| `test_runtime_loop.py` | Async turn execution and parallel tool calls. |
| `test_graph.py` | Node transitions and conditional routing. |
| `test_tool_registry.py` | Pydantic schema generation and autoboxing. |
| `test_policy_evaluator.py` | Approval/Rejection logic. |
| `test_checkpoint_resume.py` | Persistence and state recovery. |
| `test_tracing.py` | Audit log integrity. |
| `test_new_features.py` | State serialization and adapter mock streaming. |

## Contributing & Feedback

We welcome contributions! Please feel free to:
* Report bugs or suggest new features by opening a [GitHub Issue](https://github.com/gavarah/solidstate/issues).
* Read our [Contributing Guidelines](CONTRIBUTING.md) to set up your local development environment and submit Pull Requests.
