solidstate-fsm 0.1.0

A high-reliability, lightweight agent state machine runtime.

SolidState

A high-reliability, lightweight agent state machine runtime.

This project maps to the article/PDF proposal:

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

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

Tests

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

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.
• Read our Contributing Guidelines to set up your local development environment and submit Pull Requests.