Execution Architecture
SolidState isolates execution logs, state checkpoints, and safety decisions into distinct logical adapters.
Allow / Reject / Interrupt gate
File, DynamoDB, or Redis storage
Audit trail of runtime events
Core Pillars
Tool Governance & Safety Policies
Expose standard Python functions to agent systems safely. Introspect Pydantic function signatures to generate dynamic tool schemas. Before execution, the PolicyEvaluator guards invocations:
- Allow: Execute the tool concurrently using
asyncio.gather. - Reject: Halt execution and notify the model with standard error messages.
- Interrupt: Pause the runtime context, checkpoint progress, and wait for human approval.
- Exception Trap: Intercept unhandled tool errors and return them as failed results, preventing process crashes.
Checkpoint Persistence Layers
SolidState is completely stateless, enabling quick scaling. Persistence is handled via pluggable Checkpointers, saving state contexts after every execution turn:
- FileCheckpointer: Local JSON storage for testing.
- DynamoDBCheckpointer: Scalable, AWS-native persistence for serverless Lambdas.
- RedisCheckpointer: Sub-millisecond distributed caching for active agent states.
StateGraph & Symbolic Chaining
When tasks demand multi-agent coordination, link nodes and edges into complex DAG structures. Implement custom routers based on conversational intent:
- StateGraph: Map state transitions and execute nodes sequentially, or concurrently in separate OS threads using the actor-based
multithreaded=Truemodel. - Symbolic operator (
>>): Chain agents with intuitive piping syntax (researcher >> writer >> editor). - Mermaid Export: Print structured graphical representations of active workflows.
SolidState Studio
A visual IDE dashboard currently under development. Once launched, it will allow you to visually inspect active agent graphs, trace conversation histories, render live Mermaid charts of multi-agent execution routes, and trigger human-in-the-loop approvals.
Performance Benchmarks
Measuring SolidState's caching layers and state management against generic agents execution.
| Execution Phase | SolidState (Optimized) | Standard Execution Loop |
|---|---|---|
| Smart Response Cache Hit | < 0.5 ms | 1,450 ms (API call delay) |
| History Context Trimming | Auto-trimmed (Keeps system prompt) | Context overflow / Out of limits |
| Checkpointer RTT (Redis) | 1.2 ms | 80 ms (Standard database saves) |
| Memory Overhead | 4.2 MB (Stateless context wrapper) | 120+ MB (Fat framework wrapper) |
Quickstart Installation
Set up a high-reliability state machine runtime in Python.
pip install solidstate-runtime1. Safety Tool Configuration
from pydantic import BaseModel
from solidstate import ToolRegistry
class TransferArgs(BaseModel):
amount: float
to_account: str
def transfer_funds(args: TransferArgs):
"""Executes account transactions."""
return f"Transferred {args.amount}"
registry = ToolRegistry()
# Register tool with human-in-the-loop check
registry.register(
transfer_funds,
risk_level="high",
requires_approval=True
)2. Initializing checkpointer & runtime
from solidstate import AgentRuntime, RuntimeState
from solidstate.persistence import FileCheckpointer
# Setup checkpointing and policy evaluators
runtime = AgentRuntime(
model=OpenAIModelAdapter("gpt-4o"),
tool_registry=registry,
policy_evaluator=policy,
checkpointer=FileCheckpointer("checkpoints/")
)
state = RuntimeState.new("Transfer $100 to Acc 409")
# Triggers tool policy, checkpoints state, pauses run
final_state = await runtime.run(state)
# Resume execution upon human validation approval
resumed_state = await runtime.resume_after_approval(
run_id=final_state.run_id,
approved=True
)