Give your Python runtime 100% ownership of workflow transitions, guard conditions, and stage-scoped memory dispatch tables. Restrict Large Language Models strictly to bounded slot extraction (Pass 1) and response rendering (Pass 2).
blockstate verify proves mathematically via the Lengauer-Tarjan algorithm in under 50ms that mandatory compliance checkpoints (such as step_up_mfa_kyc) strictly dominate privileged actions (such as faster_payments_uk) before code reaches production.
# 1. Static AST Extraction via ast.parse (Zero Bytecode Execution)
$ blockstate check wire_agent.py
✔ [AST-OK] RetailWireTransferAgent: 6 stages, 6 edges, 0 unreachable nodes (7.1ms)
✔ [DCG-OK] Zero dynamic getattr() reflection ([Blockstate E014] guard passed)
# 2. Lengauer-Tarjan Dominator Proof across all payment rails
$ blockstate verify wire_agent.py \
--dominates "step_up_mfa_kyc -> [faster_payments_uk, sepa_euro_transfer, swift_international]"
✔ [DOMINANCE PROVEN] 'step_up_mfa_kyc' strictly dominates all 3 payment rails.
# 3. Mount inside LangGraph / Semantic Kernel as a verified enclave tool
from blockstate.adapters.langchain import as_tool
langgraph_router.bind_tools([
as_tool(RetailWireTransferAgent, name="verified_wire_transfer_enclave")
])
Eliminate combinatorial graph edge spaghetti with declarative @Stage and @Transition decorators, Pydantic v2 slot hydration, and pushdown TaskStack digression handling. Mounts directly into LangGraph or Semantic Kernel via as_tool().
Replace probabilistic prompt guardrails with sub-50ms compile-time Lengauer-Tarjan dominance proofs, stage-scoped MappingProxyType memory gates, checksum PII vaulting, and tamper-evident RFC 8785 JCS SHA-256 audit ledgers.
Pull any of the four colour-coded mechanical levers below or switch scenario tabs to test how Blockstate blocks unverified fast-track edges at build time, halts prompt-injected tool calls at the Python MappingProxyType memory boundary, and absorbs customer FAQ tangents on the LIFO TaskStack.
Lengauer-Tarjan (8.4ms): idom(faster_payments_uk) = step_up_mfa_kyc | idom(sepa_euro_transfer) = step_up_mfa_kyc | idom(swift_international) = step_up_mfa_kyc
@Stage in RuntimePassing a global tool catalogue to a ReAct loop or unconstrained graph runner conflates conversational comprehension with workflow control flow. In banking, insurance, healthcare, and telecommunications, this creates three structural blockers.
Standard agent frameworks bind every registered tool into the prompt context and rely on system prompt instructions to prevent premature calls (for example, telling the LLM to verify identity before calling authorise_bacs_payout). Adversarial prompt injection bypasses prompt wording because the function pointer remains live in the active execution scope.
Blockstate Fix: Ephemeral per-stage MappingProxyType tool gating (BLK-SEC-001).
Real customers ask clarifying questions mid-form (such as asking whether a windscreen claim affects their no-claims discount right after giving their postcode). Supporting tangents across N collection steps and M FAQ handlers in directed graph runners requires wiring O(N × M) manual edges, frequently overwriting or dropping previously validated fields.
Blockstate Fix: LIFO TaskStack pushdown automaton reducing complexity to O(N + M).
Under UK FCA SYSC 13.7, PRA SS1/23, EU AI Act Articles 12 & 14, and HIPAA, Model Risk Management (MRM) committees cannot sign off on a "97% empirical eval pass rate". Furthermore, under Rice's Theorem, unconstrained Python reflection (getattr) is mathematically undecidable by static analysis.
Blockstate Fix: Static DCG AST compiler ([Blockstate E014]) + Lengauer-Tarjan proofs + SHA-256 TurnLedger.
Every subsystem is implemented in strict PEP 695 typed Python 3.12+ and verified by automated interface contract suites and Hypothesis property-based fuzzers.
Under Rice's Theorem, unconstrained dynamic dispatch makes static graph verification undecidable. Blockstate parses agent source files via ast.parse without executing bytecode. It enforces static @Stage, @Transition, and @Guard declarations and immediately halts the build with DynamicTransitionError (BLK-AST-014 / [Blockstate E014]) if a stage calls getattr, passes a non-literal variable to Transition.to(), or embeds a transition directive inside a Pydantic @field_validator.
@Stage(name="verify_identity", initial=True, max_turns=3)
@Guard(requires=("is_authenticated",))
@Transition(targets=("collect_refund", "security_lockout"))
async def verify_identity(self) -> Transition["collect_refund" | "security_lockout"]:
# Static string literal targets pass ast.parse verification in <25ms:
if not self.session.get("is_authenticated", False):
return Transition.to("security_lockout")
return Transition.to("collect_refund")
# Any dynamic reflection or computed target halts CI immediately:
[Blockstate E014] Dynamic transition destination detected at mortgage_flow.py:42.
Transitions must reference static State definitions to enable Lengauer-Tarjan dominator verification.
During CI/CD, blockstate verify constructs the directed Control Flow Graph (including deterministic fallback edges on_refusal, on_max_turns_exceeded, on_breach, and on_security_violation), verifies BFS reachability from initial_stage, and computes depth-first numbering (dfnum), semidominators (sdom), and immediate dominators (idom) via LengauerTarjanSolver using path compression (_link, _eval, _compress). On violation, it synthesises the exact breadth-first counterexample bypass path in G \ {u}.
$ blockstate verify wire_agent.py \
--dominates "step_up_mfa_kyc -> [faster_payments_uk, sepa_euro_transfer, swift_international]"
✔ [DOMINANCE PROVEN] 'step_up_mfa_kyc' strictly dominates all 3 target stages (8.4ms).
$ blockstate export wire_agent.py --format json
# Exports verified CFG topology, stage tool whitelists, and guard contracts
# for automated MRM compliance archival and PR review certificates.
Upon entering any @Stage, ToolGatekeeper constructs an ephemeral, read-only types.MappingProxyType dispatch table and outbound LLM tool schema restricted exclusively to stage_def.tools. Context is injected via a deep-frozen ReadOnlySessionView, parameters annotated with Detokenise[T] are unwrapped in volatile RAM solely for the duration of that call, and string or mapping tool outputs are automatically re-sanitised through PIIVault.
@Stage(
name="ncd_policy_faq",
tools=["query_policy_handbook_rag"], # Only this function exists in MappingProxyType
max_turns=2,
)
async def ncd_policy_faq(self, query: str) -> Transition[None]:
# If prompt injection attempts self.tools.authorise_bacs_payout(...):
# Raises SecurityViolationError (BLK-SEC-001) before function lookup!
excerpt = await self.tools.query_policy_handbook_rag(topic=query)
return Transition.pop_frame(message=f"Policy Handbook: {excerpt}")
Blockstate separates persistent SessionState from a bounded Last-In, First-Out (LIFO) TaskStack of TaskFrame contexts (raising StackOverflowError BLK-SEC-003 if depth exceeds the configured circuit breaker). When a user digresses to an allowed FAQ stage, Blockstate pushes a child frame, locks parent dot-separated slot paths against mutation (UnauthorisedMutationError BLK-SEC-002 when allow_slot_overrides=False), answers the query, and executes Transition.pop_frame() to resume parent slot collection.
@Stage(
name="intake_claim",
initial=True,
collect=MotorClaimSlots,
allow_digressions=["ncd_policy_faq"],
allow_slot_overrides=False, # Child frame cannot mutate parent slots (BLK-SEC-002)
on_breach="commercial_fleet_desk",
on_max_turns_exceeded="human_claims_handler",
max_turns=6,
)
Stages bind to standard Pydantic v2 models up to max_nesting_depth (BLK-CFG-002). Blockstate synthesises a recursive PartialSlotModel using the singleton UNSET sentinel. Candidate values are validated at individual flattened leaf paths, preserving valid sibling leaves when one leaf fails (BLK-VAL-002). Custom @field_validator methods unwrap Vaulted[T] tokens in volatile memory via wrap_detokenising_validator, immediately re-bind tokens, scrub PII from validation exceptions, and route immediately to on_breach on DisqualifyingBreachError (BLK-VAL-003).
class MotorClaimSlots(BaseModel):
policy_number: str = Field(pattern=r"^POL-\d{6}$")
vehicle_usage: str
estimated_damage_gbp: float = Field(gt=0)
location: IncidentLocation # Nested model hydrated progressively across turns
@field_validator("vehicle_usage", mode="after")
@classmethod
def check_commercial_eligibility(cls, v: str) -> str:
if v.lower() == "commercial_haulage":
raise BreachError("Commercial policies require Specialist Fleet Desk.")
return v
Ingress utterances are scanned by deterministic checksum detectors (including Luhn modulo-10 for payment cards and NHS Modulus-11 check-digit validation, plus UK National Insurance numbers and postcodes) with longest-span and priority-rank overlap resolution that protects existing <VAULT:...> tokens. Entities are deduplicated per session via keyed HMAC-SHA256 into <VAULT:CATEGORY_NN> tokens, and the token map is encrypted with AES-256-GCM using a 12-byte random nonce and colon-separated session_id:schema_version:revision_id Associated Authenticated Data (AAD).
from blockstate import Detokenise
# LLM prompts, SessionState, and TurnLedger only ever see "<VAULT:NHS_NUMBER_01>"
async def lookup_patient_ehr_record(
nhs_number: Detokenise[str],
postcode: Detokenise[str],
) -> dict[str, str]:
# Unwrapped to plaintext "485 777 3456" solely inside this volatile call frame
return {"registration_status": "ACTIVE", "gp_practice_code": "Y00124"}
Every turn generates a 12-field TurnLedgerRecord chained from a genesis hash of 64 zeroes ("0" * 64), serialised via RFC 8785 JSON Canonicalisation Scheme (JCS) UTF-8 and hashed with SHA-256. Records stream through a SessionPartitionedRingBuffer with os.fsync spill to .blockstate/wal/ledger.wal and causal startup replay (recover_wal). Distributed state persists via the async StorageBackend SPI (In-Memory, SQLite WAL, PostgreSQL) with fenced LeaseHandle tokens (BLK-CON-409), SessionLeaseHeartbeat renewal, Compare-And-Swap revision checks (BLK-STO-002), and sequential SchemaUpcaster migrations.
$ blockstate trace --session 0192ce18-7b40-7000-8000-4a91f0012c9a
Turn 1 | [START] -> collect_patient_identifiers | Tools: [] | SHA-256: 8f9c2b1a...e401 (prev: 0000...0000)
Turn 2 | collect_patient_identifiers -> verify_ehr | Tools: [lookup_patient_ehr_record] | SHA-256: 3d41a90c...99b2
✔ Cryptographic Hash Chain Verified (2/2 records intact, 0 raw PII tokens leaked)as_tool()Keep your existing high-level conversational router for open-domain search and concierge dialogue. When a customer triggers a regulated transaction, invoke Blockstate as a deterministic compliance enclave returning a frozen discriminated union.
from blockstate.adapters.langchain import as_tool
from my_insurance_agent import MotorInsuranceClaimAgent
# Wrap the verified statechart as a standard tool for LangGraph
claim_enclave_tool = as_tool(
agent_cls=MotorInsuranceClaimAgent,
name="motor_claim_enclave",
description="Executes FNOL motor insurance claims under FCA compliance.",
)
langgraph_router.bind_tools([claim_enclave_tool])from blockstate import (
BlockstateTurnYield,
BlockstateTurnComplete,
BlockstateTurnAborted,
)
outcome = await claim_agent.run_as_subflow(
session_id=session_id,
user_message=user_utterance,
initial_context={"is_authenticated": True},
)
match outcome:
case BlockstateTurnYield(message=prompt_msg, missing_slots=delta):
return prompt_msg
case BlockstateTurnComplete(result=claim, ledger_head_hash=h):
return f"Approved (Audit SHA-256: {h[:12]})"
case BlockstateTurnAborted(error_code=code, reason=reason):
return f"[{code}] Escalating to specialist: {reason}"Compare Blockstate's compile-time verification and hardware-boundary memory gating with general-purpose orchestrators and DSL guardrails. For deep code-level comparisons, visit the Technical Comparison Hub.
| Architectural Capability | LangGraph | NeMo Guardrails (Colang 2.0) | LlamaIndex Workflows | PydanticAI (pydantic-graph) | Blockstate (blockstate) |
|---|---|---|---|---|---|
| Primary Architectural Role | High-level outer orchestrator | Proprietary Colang .co DSL |
Event-driven async steps | Typed node return unions | Transactional Compliance Execution Enclave |
| Physical Tool Containment | Global ToolNode superset | DSL action rail checks | Imperative event handlers | Dynamic prepare callbacks | Ephemeral per-stage MappingProxyType |
| Static AST Graph Compiler | Runtime graph inspection | Colang syntax check | Runtime reflection | mypy type checking only | Zero-execution DCG AST compiler ([Blockstate E014]) |
| Mathematical Dominator Proofs | None | None | None | None | Lengauer-Tarjan (<50ms KYC dom Payout) |
| Multi-Turn Digression Stack | Manual subgraphs O(N × M) | Concurrent DSL flows | Manual event state | Manual node branching | LIFO TaskStack Pushdown Automaton O(N + M) |
| Nested Multi-Turn Slot Filling | Custom state boilerplate | Colang dialog scripts | Manual state dicts | Single-turn structured output | Recursive PartialSlotModel Δ-Hydration + Leaf Locking |
| Turn Latency Architecture | 1 to 3s serialised LLM calls | 3 to 6s multi-hop rails | Single-pass async LLM | Single-pass async LLM | Two-Pass (<50ms ONNX + <15ms Template/LLM) |
| Ingress PII Tokenisation | Manual middleware | Presidio text masking | Manual hooks | Manual preprocessing | Checksum PIIVault (<VAULT:ID>) + Detokenise[T] |
| Tamper-Evident Audit Log | State checkpoints only | Unstructured event logs | Telemetry traces only | Message history JSON | RFC 8785 JCS SHA-256 TurnLedger + WAL Spill |
Blockstate is distributed under the Blockstate Source-Available & Commercial Dual Licence (v1.0) and is protected by a pending United Kingdom Patent Application. Developers evaluate and run CI verification free of charge; regulated production deployments license the runtime and patent portfolio annually. Machine-readable specification: /pricing.md.
blockstate check & blockstate verify) in CI/CD pipelinesInMemoryStorageBackend, and SQLiteStorageBackend (WAL)PostgresStorageBackend (async SQLAlchemy + asyncpg) with fenced leases and SchemaUpcaster migrationsTurnLedger archival adapter & OpenTelemetry GenAI 1.30 integration supportLICENSE Section 2(b))| Third-Party Component Layer | Audited Packages | SPDX Licences | Copyleft (GPL/AGPL/LGPL) Risk |
|---|---|---|---|
| Core Runtime & InMemory Backend | python (3.12+), pydantic, pydantic-settings, cryptography, typer, rich |
PSF-2.0, MIT, Apache-2.0 / BSD-3-Clause |
None (0%) |
| Model & Classifier Extras | pydantic-ai-slim, litellm (<1.107.0), onnxruntime |
MIT |
None (0%) |
| v1 StorageBackend & Ledger Extras | aiosqlite (SQLite WAL), SQLAlchemy + asyncpg (PostgreSQL), aioboto3 (S3 WORM) |
MIT, Apache-2.0 |
None (0%) |
| Observability Extra | opentelemetry-api, opentelemetry-sdk |
Apache-2.0 |
None (0%) |
as_tool() adapter. Blockstate executes the verified statechart enclave and returns a strictly typed discriminated union (BlockstateTurnYield | BlockstateTurnComplete | BlockstateTurnAborted).
if/else trees lack five critical compliance primitives that you would otherwise have to build and maintain from scratch: (1) zero-execution static AST extraction and Lengauer-Tarjan dominator verification in CI/CD (blockstate verify), (2) automatic recursive PartialSlotModel Δ-hydration with per-leaf locking across multi-turn conversations, (3) a LIFO TaskStack pushdown automaton for mid-flow customer digressions, (4) stage-scoped types.MappingProxyType memory tool gating, and (5) an RFC 8785 JCS SHA-256 hash-chained TurnLedger with WAL crash recovery.
getattr(self, state_name)(), no compiler can prove before deployment that step_up_mfa_kyc dominates faster_payments_uk. Enforcing static string literals in the Declarative Control Grammar via ast.parse makes Lengauer-Tarjan dominator tree verification 100% sound and decidable in under 50ms.
@field_validator methods, and pure Python @Guard predicates before the Python statechart engine executes a transition.
PIIVault.sanitise() detects sensitive entities using Luhn modulo-10 and NHS Modulus-11 check-digit algorithms, replacing them with session-consistent HMAC-SHA256 tokens (such as <VAULT:NHS_NUMBER_01>) and encrypting the mapping with AES-256-GCM bound to session_id:schema_version:revision_id AAD. The LLM and TurnLedger only ever see the opaque token. When a whitelisted backend tool requires the plaintext identifier, the developer annotates that parameter with Detokenise[str]. ToolGatekeeper unwraps the value inside volatile RAM solely for that function call and automatically re-sanitises the tool's return value.
StorageBackend Service Provider Interface (src/blockstate/ports/storage.py), all verified against the identical StorageBackendContractSuite: (1) InMemoryStorageBackend for hermetic unit testing and CI, (2) SQLiteStorageBackend with Write-Ahead Logging (PRAGMA journal_mode=WAL via aiosqlite) for local development and single-node edge deployments, and (3) PostgresStorageBackend (via SQLAlchemy[asyncio] and asyncpg) for cloud production deployments with fenced leases (BLK-CON-409) and optimistic Compare-And-Swap (BLK-STO-002). Redis, Microsoft SQL Server, and AWS DynamoDB are scheduled for v1.2+ via the pluggable SPI.
LICENSE v1.0) gives individual developers, researchers, open-source CI pipelines, and enterprise teams evaluating in staging for up to 90 days full source inspection and free execution (£0 under Section 1), while requiring a Commercial Production and Patent Licence (Section 2) when deployed in live commercial production or managed services.
direct | Logged Micro-Conversions: 0