flowscript-agents 0.2.8__tar.gz → 0.3.0__tar.gz

flowscript_agents-0.3.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+*.tmp
+.flowscript-*
+*.jsonl
+
+.DS_Store
+
+# Development-only validation scripts (hardcoded local paths)
+e2e_compliance_chain.py
+validate_wrapper.py
+validate_autonomous_agent.py
+e2e_output/
+validation_output/

{flowscript_agents-0.2.8 → flowscript_agents-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowscript-agents
-Version: 0.2.8
+Version: 0.3.0
 Summary: Complete agent memory: reasoning queries + vector search + auto-extraction. Decision intelligence for LangGraph, CrewAI, Google ADK, OpenAI Agents SDK, Pydantic AI, smolagents, LlamaIndex, Haystack, and CAMEL-AI.
 Project-URL: Homepage, https://flowscript.org
 Project-URL: Repository, https://github.com/phillipclapham/flowscript-agents
@@ -70,9 +70,11 @@ Description-Content-Type: text/markdown
 
 <p align="center"><strong>Your AI agents make decisions they can't explain. FlowScript makes those decisions queryable.</strong></p>
 
-<p align="center">Drop-in adapters for 9 agent frameworks. Plain text in, typed reasoning queries out.<br>Hash-chained audit trail. Structural compliance. MIT licensed.</p>
+<p align="center">Drop-in adapters for 9 agent frameworks. Plain text in, typed reasoning queries out.<br>Hash-chained audit trail. Convergence certificates. CloudClient for independent witnessing. MIT licensed.</p>
 
-[![Tests](https://img.shields.io/badge/tests-584%20passing-brightgreen)](https://github.com/phillipclapham/flowscript-agents) [![PyPI](https://img.shields.io/pypi/v/flowscript-agents)](https://pypi.org/project/flowscript-agents/) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/flowscript-agents/)
+<p align="center"><em>EU AI Act enforcement begins August 2026. Audit trails can't be backdated.<br>FlowScript is the compliance engine that makes your agents audit-ready from day one.</em></p>
+
+[![Tests](https://img.shields.io/badge/tests-590%2B%20passing-brightgreen)](https://github.com/phillipclapham/flowscript-agents) [![PyPI](https://img.shields.io/pypi/v/flowscript-agents)](https://pypi.org/project/flowscript-agents/) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/flowscript-agents/)
 
 ---
 
@@ -357,6 +359,55 @@ Events are dispatched in order (single worker thread). Callback failures log to
 
 ---
 
+## @fix — Convergence Certificates
+
+When FlowScript's consolidation engine resolves contradictions — creating tensions, updating beliefs, unblocking decisions — it produces **convergence certificates**: hash-chained attestations that prove how the reasoning graph changed and that the transformation hasn't been tampered with.
+
+```python
+from flowscript_agents import Memory, MemoryOptions, AuditConfig
+
+mem = Memory.load_or_create("agent.json", options=MemoryOptions(
+    audit=AuditConfig(retention_months=84)
+))
+
+# UnifiedMemory consolidation produces certificates automatically:
+# initial_graph_hash → delta_sequence → final_graph_hash → certificate_hash
+```
+
+Each certificate records: the graph state before consolidation (`initial_hash`), what changed (`delta_sequence`), the graph state after (`final_hash`), and a hash proving the record is tamper-evident (`certificate_hash`). This is concrete Article 86 infrastructure — an auditor can verify not just what your agent decided, but how it got there.
+
+**Underlying formal model:** FlowScript's `@fix` operator provides stratified fixpoint computation over typed reasoning graphs — L0 (pure description, always terminates), L1 (bounded fixpoint, Knaster-Tarski guarantees), L2 (general fixpoint, Turing-complete, bounded). Consolidation is a degenerate L1 fixpoint (single iteration). Full spec: [`fixpoint_spec.md`](https://github.com/phillipclapham/flowscript/blob/main/spec/fixpoint_spec.md).
+
+---
+
+## FlowScript Cloud — Independent Cryptographic Witnessing *(Coming Soon)*
+
+Local audit trails are tamper-evident but self-attested. FlowScript Cloud will add independent verification: your SDK streams events to the Cloud service, which verifies chain continuity and stores witness attestations.
+
+The CloudClient is included in the SDK and ready for integration. The Cloud service is under development.
+
+```python
+from flowscript_agents import Memory, MemoryOptions, AuditConfig
+from flowscript_agents.cloud import CloudClient
+
+cloud = CloudClient()  # reads FLOWSCRIPT_API_KEY from env
+
+mem = Memory.load_or_create("agent.json", options=MemoryOptions(
+    audit=AuditConfig(on_event=cloud.queue_event)
+))
+```
+
+**CloudClient features:**
+- **Batch buffering** — events accumulate and flush in batches (configurable `batch_size`, default 50)
+- **Lock-free I/O** — network operations never block your agent's main thread
+- **Buffer overflow protection** — `max_buffer_size` cap prevents memory growth
+- **Witness tracking** — `cloud.last_witness` returns the most recent attestation
+- **Retry with backoff** — transient failures retry automatically
+
+**Planned deployment tiers:** SaaS, self-hosted Cloudflare, or Docker on-premise. BSL 1.1 licensed.
+
+---
+
 ## Session Lifecycle — How Memory Gets Smarter
 
 Just like a mind needs sleep to consolidate memories, your agent's reasoning graph needs regular session wraps to develop intelligence over time. Without consolidation cycles, knowledge accumulates as noise instead of maturing.
@@ -497,14 +548,14 @@ text = explain(result, audience="legal")
 │  ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │
 │  │  Memory   │ │ Queries  │ │ Audit Trail          │ │
 │  │  (graph)  │ │ (5 ops)  │ │ (SHA-256 hash chain) │ │
-│  │         explain()      │ │  on_event_async      │ │
-│  └──────────┘ └──────────┘ └──────────────────────┘ │
+│  │  @fix     │ │explain() │ │  on_event_async ─────────→ FlowScript Cloud
+│  └──────────┘ └──────────┘ └──────────────────────┘ │  (independent witness)
 ├─────────────────────────────────────────────────────┤
 │  Your Storage (files, database, cloud)              │
 └─────────────────────────────────────────────────────┘
 ```
 
-FlowScript doesn't replace your stack. It sits between your agent framework and your storage, adding typed reasoning and audit to whatever you already use.
+FlowScript doesn't replace your stack. It sits between your agent framework and your storage, adding typed reasoning and audit to whatever you already use. Optionally stream audit events to FlowScript Cloud *(coming soon)* for independent cryptographic witnessing.
 
 ---
 
@@ -550,11 +601,12 @@ The applications are what you install FlowScript for. The infrastructure is why
 
 | Package | What | Install |
 |:--------|:-----|:--------|
-| [flowscript-agents](https://pypi.org/project/flowscript-agents/) | Python SDK — 9 adapters, unified memory, consolidation, audit trail | `pip install flowscript-agents openai` |
+| [flowscript-agents](https://pypi.org/project/flowscript-agents/) | Python SDK — 9 adapters, CloudClient, unified memory, consolidation, audit trail | `pip install flowscript-agents openai` |
 | [flowscript-core](https://www.npmjs.com/package/flowscript-core) | TypeScript SDK — Memory class, 15 tools, token budgeting, audit trail | `npm install flowscript-core` |
+| [flowscript-cloud](https://github.com/phillipclapham/flowscript-cloud) | Cloud witnessing service — chain verification, witness attestations, RBAC | *Coming soon* |
 | [flowscript.org](https://flowscript.org) | Web editor, D3 visualization, live query panel | Browser |
 
-**1,315 tests** across Python (584) and TypeScript (731). Same audit trail format and canonical JSON serialization across both languages.
+**~1,400+ tests** across Python (590+), TypeScript (779), and Cloud (68). Same audit trail format and canonical JSON serialization across both languages.
 
 ### Docs
 

{flowscript_agents-0.2.8 → flowscript_agents-0.3.0}/README.md

@@ -6,9 +6,11 @@
 
 <p align="center"><strong>Your AI agents make decisions they can't explain. FlowScript makes those decisions queryable.</strong></p>
 
-<p align="center">Drop-in adapters for 9 agent frameworks. Plain text in, typed reasoning queries out.<br>Hash-chained audit trail. Structural compliance. MIT licensed.</p>
+<p align="center">Drop-in adapters for 9 agent frameworks. Plain text in, typed reasoning queries out.<br>Hash-chained audit trail. Convergence certificates. CloudClient for independent witnessing. MIT licensed.</p>
 
-[![Tests](https://img.shields.io/badge/tests-584%20passing-brightgreen)](https://github.com/phillipclapham/flowscript-agents) [![PyPI](https://img.shields.io/pypi/v/flowscript-agents)](https://pypi.org/project/flowscript-agents/) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/flowscript-agents/)
+<p align="center"><em>EU AI Act enforcement begins August 2026. Audit trails can't be backdated.<br>FlowScript is the compliance engine that makes your agents audit-ready from day one.</em></p>
+
+[![Tests](https://img.shields.io/badge/tests-590%2B%20passing-brightgreen)](https://github.com/phillipclapham/flowscript-agents) [![PyPI](https://img.shields.io/pypi/v/flowscript-agents)](https://pypi.org/project/flowscript-agents/) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/flowscript-agents/)
 
 ---
 
@@ -293,6 +295,55 @@ Events are dispatched in order (single worker thread). Callback failures log to
 
 ---
 
+## @fix — Convergence Certificates
+
+When FlowScript's consolidation engine resolves contradictions — creating tensions, updating beliefs, unblocking decisions — it produces **convergence certificates**: hash-chained attestations that prove how the reasoning graph changed and that the transformation hasn't been tampered with.
+
+```python
+from flowscript_agents import Memory, MemoryOptions, AuditConfig
+
+mem = Memory.load_or_create("agent.json", options=MemoryOptions(
+    audit=AuditConfig(retention_months=84)
+))
+
+# UnifiedMemory consolidation produces certificates automatically:
+# initial_graph_hash → delta_sequence → final_graph_hash → certificate_hash
+```
+
+Each certificate records: the graph state before consolidation (`initial_hash`), what changed (`delta_sequence`), the graph state after (`final_hash`), and a hash proving the record is tamper-evident (`certificate_hash`). This is concrete Article 86 infrastructure — an auditor can verify not just what your agent decided, but how it got there.
+
+**Underlying formal model:** FlowScript's `@fix` operator provides stratified fixpoint computation over typed reasoning graphs — L0 (pure description, always terminates), L1 (bounded fixpoint, Knaster-Tarski guarantees), L2 (general fixpoint, Turing-complete, bounded). Consolidation is a degenerate L1 fixpoint (single iteration). Full spec: [`fixpoint_spec.md`](https://github.com/phillipclapham/flowscript/blob/main/spec/fixpoint_spec.md).
+
+---
+
+## FlowScript Cloud — Independent Cryptographic Witnessing *(Coming Soon)*
+
+Local audit trails are tamper-evident but self-attested. FlowScript Cloud will add independent verification: your SDK streams events to the Cloud service, which verifies chain continuity and stores witness attestations.
+
+The CloudClient is included in the SDK and ready for integration. The Cloud service is under development.
+
+```python
+from flowscript_agents import Memory, MemoryOptions, AuditConfig
+from flowscript_agents.cloud import CloudClient
+
+cloud = CloudClient()  # reads FLOWSCRIPT_API_KEY from env
+
+mem = Memory.load_or_create("agent.json", options=MemoryOptions(
+    audit=AuditConfig(on_event=cloud.queue_event)
+))
+```
+
+**CloudClient features:**
+- **Batch buffering** — events accumulate and flush in batches (configurable `batch_size`, default 50)
+- **Lock-free I/O** — network operations never block your agent's main thread
+- **Buffer overflow protection** — `max_buffer_size` cap prevents memory growth
+- **Witness tracking** — `cloud.last_witness` returns the most recent attestation
+- **Retry with backoff** — transient failures retry automatically
+
+**Planned deployment tiers:** SaaS, self-hosted Cloudflare, or Docker on-premise. BSL 1.1 licensed.
+
+---
+
 ## Session Lifecycle — How Memory Gets Smarter
 
 Just like a mind needs sleep to consolidate memories, your agent's reasoning graph needs regular session wraps to develop intelligence over time. Without consolidation cycles, knowledge accumulates as noise instead of maturing.
@@ -433,14 +484,14 @@ text = explain(result, audience="legal")
 │  ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │
 │  │  Memory   │ │ Queries  │ │ Audit Trail          │ │
 │  │  (graph)  │ │ (5 ops)  │ │ (SHA-256 hash chain) │ │
-│  │         explain()      │ │  on_event_async      │ │
-│  └──────────┘ └──────────┘ └──────────────────────┘ │
+│  │  @fix     │ │explain() │ │  on_event_async ─────────→ FlowScript Cloud
+│  └──────────┘ └──────────┘ └──────────────────────┘ │  (independent witness)
 ├─────────────────────────────────────────────────────┤
 │  Your Storage (files, database, cloud)              │
 └─────────────────────────────────────────────────────┘
 ```
 
-FlowScript doesn't replace your stack. It sits between your agent framework and your storage, adding typed reasoning and audit to whatever you already use.
+FlowScript doesn't replace your stack. It sits between your agent framework and your storage, adding typed reasoning and audit to whatever you already use. Optionally stream audit events to FlowScript Cloud *(coming soon)* for independent cryptographic witnessing.
 
 ---
 
@@ -486,11 +537,12 @@ The applications are what you install FlowScript for. The infrastructure is why
 
 | Package | What | Install |
 |:--------|:-----|:--------|
-| [flowscript-agents](https://pypi.org/project/flowscript-agents/) | Python SDK — 9 adapters, unified memory, consolidation, audit trail | `pip install flowscript-agents openai` |
+| [flowscript-agents](https://pypi.org/project/flowscript-agents/) | Python SDK — 9 adapters, CloudClient, unified memory, consolidation, audit trail | `pip install flowscript-agents openai` |
 | [flowscript-core](https://www.npmjs.com/package/flowscript-core) | TypeScript SDK — Memory class, 15 tools, token budgeting, audit trail | `npm install flowscript-core` |
+| [flowscript-cloud](https://github.com/phillipclapham/flowscript-cloud) | Cloud witnessing service — chain verification, witness attestations, RBAC | *Coming soon* |
 | [flowscript.org](https://flowscript.org) | Web editor, D3 visualization, live query panel | Browser |
 
-**1,315 tests** across Python (584) and TypeScript (731). Same audit trail format and canonical JSON serialization across both languages.
+**~1,400+ tests** across Python (590+), TypeScript (779), and Cloud (68). Same audit trail format and canonical JSON serialization across both languages.
 
 ### Docs
 

{flowscript_agents-0.2.8 → flowscript_agents-0.3.0}/flowscript_agents/__init__.py

@@ -27,6 +27,7 @@ Usage:
 """
 
 from .audit import AuditConfig, AuditQueryResult, AuditVerifyResult
+from .client import FlowScriptAnthropic, FlowScriptOpenAI
 from .cloud import CloudClient, CloudFlushResult, CloudWitness
 from .memory import (
     Memory,
@@ -43,14 +44,17 @@ from .memory import (
     SessionWrapResult,
 )
 from .unified import UnifiedMemory
-from .explain import explain
+from .explain import explain, explain_counterfactual
 
-__version__ = "0.2.8"
+__version__ = "0.3.0"
 __all__ = [
     "explain",
+    "explain_counterfactual",
     "AuditConfig",
     "AuditQueryResult",
     "AuditVerifyResult",
+    "FlowScriptAnthropic",
+    "FlowScriptOpenAI",
     "CloudClient",
     "CloudFlushResult",
     "CloudWitness",

{flowscript_agents-0.2.8 → flowscript_agents-0.3.0}/flowscript_agents/audit.py

@@ -19,6 +19,7 @@ File layout:
 
 from __future__ import annotations
 
+import copy
 import gzip
 import atexit
 import hashlib
@@ -407,7 +408,10 @@ class AuditWriter:
         # Fire on_event callback (failure must never block audit, but log to stderr)
         if self._config.on_event:
             if self._config.on_event_async:
-                self._get_executor().submit(self._fire_on_event, entry)
+                # Deep copy to prevent caller mutation between write() return and
+                # async callback execution from producing different canonical JSON
+                # (which would break hash chain verification in CloudClient).
+                self._get_executor().submit(self._fire_on_event, copy.deepcopy(entry))
             else:
                 self._fire_on_event(entry)