AbstractRuntime 0.0.0__tar.gz → 0.2.0__tar.gz

abstractruntime-0.2.0/.gitignore

@@ -0,0 +1,88 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs and editors
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# Pyre type checker
+.pyre/
+
+# profiling
+.prof
+
+# Local config
+*.env
+.env.*
+# End Generation Here
+```
+
+.DS_Store

abstractruntime-0.2.0/CHANGELOG.md

@@ -0,0 +1,132 @@
+# Changelog
+
+All notable changes to AbstractRuntime will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2025-12-17
+
+### Added
+
+#### Core Runtime Features
+- **Durable Workflow Execution**: Start/tick/resume semantics for long-running workflows that survive process restarts
+- **WorkflowSpec**: Graph-based workflow definitions with node handlers keyed by ID
+- **RunState**: Durable state management (`current_node`, `vars`, `waiting`, `status`)
+- **Effect System**: Side-effect requests including `LLM_CALL`, `TOOL_CALLS`, `ASK_USER`, `WAIT_EVENT`, `WAIT_UNTIL`, `START_SUBWORKFLOW`
+- **StepPlan**: Node execution plans that define effects and state transitions
+- **Explicit Waiting States**: First-class support for pausing execution (`WaitReason`, `WaitState`)
+
+#### Scheduler & Automation
+- **Built-in Scheduler**: Zero-config background scheduler with polling thread for automatic run resumption
+- **WorkflowRegistry**: Mapping from workflow_id to WorkflowSpec for dynamic workflow resolution
+- **ScheduledRuntime**: High-level wrapper combining Runtime + Scheduler with simplified API
+- **create_scheduled_runtime()**: Factory function for zero-config scheduler creation
+- **Event Ingestion**: Support for external event delivery via `scheduler.resume_event()`
+- **Scheduler Stats**: Built-in statistics tracking and callback support
+
+#### Storage & Persistence
+- **Append-only Ledger**: Execution journal with `StepRecord` entries for audit/debug/provenance
+- **InMemoryRunStore**: In-memory run state storage for development and testing
+- **InMemoryLedgerStore**: In-memory ledger storage for development and testing
+- **JsonFileRunStore**: File-based persistent run state storage (one file per run)
+- **JsonlLedgerStore**: JSONL-based persistent ledger storage
+- **QueryableRunStore**: Interface for listing and filtering runs by status, workflow_id, actor_id, and time range
+- **Artifacts System**: Storage for large payloads (documents, images, tool outputs) to avoid bloating checkpoints
+  - `ArtifactStore` interface with in-memory and file-based implementations
+  - `ArtifactRef` type for referencing stored artifacts
+  - Helper functions: `artifact_ref()`, `is_artifact_ref()`, `get_artifact_id()`, `resolve_artifact()`, `compute_artifact_id()`
+
+#### Snapshots & Bookmarks
+- **Snapshot System**: Named, searchable checkpoints of run state for debugging and experimentation
+- **SnapshotStore**: Storage interface for snapshots with metadata (name, description, tags, timestamps)
+- **InMemorySnapshotStore**: In-memory snapshot storage for development
+- **JsonSnapshotStore**: File-based snapshot storage (one file per snapshot)
+- **Snapshot Search**: Filter by run_id, tag, or substring match in name/description
+
+#### Provenance & Accountability
+- **Hash-Chained Ledger**: Tamper-evident ledger with `prev_hash` and `record_hash` for each step
+- **HashChainedLedgerStore**: Decorator for adding hash chain verification to any ledger store
+- **verify_ledger_chain()**: Verification function that detects modifications or reordering of ledger records
+- **Actor Identity**: `ActorFingerprint` for attribution of workflow execution to specific actors
+- **actor_id tracking**: Support for actor_id in both RunState and StepRecord for accountability
+
+#### AbstractCore Integration
+- **LLM_CALL Effect Handler**: Execute LLM calls via AbstractCore providers
+- **TOOL_CALLS Effect Handler**: Execute tool calls with support for multiple execution modes
+- **Three Execution Modes**:
+  - **Local**: In-process AbstractCore providers with local tool execution
+  - **Remote**: HTTP to AbstractCore server (`/v1/chat/completions`) with tool passthrough
+  - **Hybrid**: Remote LLM calls with local tool execution
+- **Convenience Factories**: `create_local_runtime()`, `create_remote_runtime()`, `create_hybrid_runtime()`
+- **Tool Execution Modes**:
+  - Executed mode (trusted local) with results
+  - Passthrough mode (untrusted/server) with waiting semantics
+- **Layered Coupling**: AbstractCore integration as opt-in module to keep kernel dependency-light
+
+#### Effect Policies & Reliability
+- **EffectPolicy Protocol**: Configurable retry and idempotency policies for effects
+- **DefaultEffectPolicy**: Default implementation with no retries
+- **RetryPolicy**: Configurable retry behavior with max_attempts and backoff
+- **NoRetryPolicy**: Explicit no-retry policy
+- **compute_idempotency_key()**: Ledger-based deduplication to prevent duplicate side effects after crashes
+
+#### Examples & Documentation
+- **7 Runnable Examples**:
+  - `01_hello_world.py`: Minimal workflow demonstration
+  - `02_ask_user.py`: Pause/resume with user input
+  - `03_wait_until.py`: Scheduled resumption with time-based waiting
+  - `04_multi_step.py`: Branching workflow with conditional logic
+  - `05_persistence.py`: File-based storage demonstration
+  - `06_llm_integration.py`: AbstractCore LLM call integration
+  - `07_react_agent.py`: Full ReAct agent implementation with tools
+- **Comprehensive Documentation**:
+  - Architecture Decision Records (ADRs) for key design choices
+  - Integration guides for AbstractCore
+  - Detailed documentation for snapshots and provenance
+  - Limits and constraints documentation
+  - ROADMAP with prioritized next steps
+
+### Technical Details
+
+#### Architecture
+- **Layered Design**: Clear separation between kernel, storage, integrations, and identity
+- **Dependency-Light Kernel**: Core runtime remains stable with minimal dependencies
+- **Graph-Based Execution**: All workflows represented as state machines/graphs for visualization and composition
+- **JSON-Serializable State**: All run state and vars must be JSON-serializable for persistence
+
+#### Test Coverage
+- **81% Overall Coverage**: Comprehensive test suite with 57+ tests
+- **Integration Tests**: Tests for AbstractCore integration, subworkflows, trace propagation
+- **Core Tests**: Scheduler, snapshots, artifacts, pause/resume, retry/idempotency, ledger chain
+- **Storage Tests**: Queryable run store, durable toolsets
+
+#### Compatibility
+- **Python 3.10+**: Supports Python 3.10, 3.11, 3.12, and 3.13
+- **Development Status**: Planning/Alpha (moving toward Beta with 0.2.0)
+
+### Known Limitations
+
+- Snapshot restore does not guarantee safety if workflow spec or node code has changed
+- Subworkflow support (`START_SUBWORKFLOW`) is implemented but undergoing refinement
+- Cryptographic signatures (non-forgeability) not yet implemented - current hash chain provides tamper-evidence only
+- Remote tool worker service not yet implemented
+
+### Design Decisions
+
+- **Kernel stays dependency-light**: Enables portability, stability, and clear integration boundaries
+- **AbstractCore integration is opt-in**: Layered coupling prevents kernel breakage when AbstractCore changes
+- **Hash chain before signatures**: Provides immediate value without key management complexity
+- **Built-in scheduler (not external)**: Zero-config UX for simple cases
+- **Graph representation for all workflows**: Enables visualization, checkpointing, and composition
+
+### Notes
+
+AbstractRuntime is the durable execution substrate designed to pair with AbstractCore, AbstractAgent, and AbstractFlow. It enables workflows to interrupt, checkpoint, and resume across process restarts, making it suitable for long-running agent workflows that need to wait for user input, scheduled events, or external job completion.
+
+## [0.0.1] - Initial Development
+
+Initial development version with basic proof-of-concept features.
+
+[0.2.0]: https://github.com/lpalbou/abstractruntime/releases/tag/v0.2.0
+[0.0.1]: https://github.com/lpalbou/abstractruntime/releases/tag/v0.0.1

{abstractruntime-0.0.0 → abstractruntime-0.2.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 AbstractRuntime Contributors
+Copyright (c) 2025 Laurent-Philippe Albou
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -21,3 +21,5 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 
+
+

abstractruntime-0.2.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: AbstractRuntime
+Version: 0.2.0
+Summary: AbstractRuntime: a durable graph runner designed to pair with AbstractCore.
+Project-URL: AbstractCore (website), https://www.abstractcore.ai/
+Project-URL: AbstractCore (GitHub), https://github.com/lpalbou/abstractruntime
+Author: Laurent-Philippe Albou
+License: MIT
+License-File: LICENSE
+Keywords: agents,checkpoint,durable,graph,llm,resume,workflow
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+## AbstractRuntime
+
+**AbstractRuntime** is a low-level **durable workflow runtime**:
+- Execute workflow graphs (state machines)
+- **Interrupt → checkpoint → resume** (hours/days) without keeping Python stacks alive
+- Append-only **ledger** ("journal d’exécution") for audit/debug/provenance
+
+**Status**: MVP kernel + file persistence + AbstractCore integration adapters are implemented.
+
+---
+
+### Key concepts
+- **WorkflowSpec**: graph definition (node handlers keyed by id)
+- **RunState**: durable state (`current_node`, `vars`, `waiting`, etc.)
+- **Effect**: a side-effect request (`llm_call`, `tool_calls`, `ask_user`, `wait_event`, ...)
+- **Ledger**: append-only step records (`StepRecord`) describing what happened
+
+---
+
+### Quick start (pause + resume)
+
+```python
+from abstractruntime import Effect, EffectType, Runtime, StepPlan, WorkflowSpec
+from abstractruntime.storage import InMemoryLedgerStore, InMemoryRunStore
+
+
+def ask(run, ctx):
+    return StepPlan(
+        node_id="ask",
+        effect=Effect(
+            type=EffectType.ASK_USER,
+            payload={"prompt": "Continue?"},
+            result_key="user_answer",
+        ),
+        next_node="done",
+    )
+
+
+def done(run, ctx):
+    return StepPlan(node_id="done", complete_output={"answer": run.vars.get("user_answer")})
+
+
+wf = WorkflowSpec(workflow_id="demo", entry_node="ask", nodes={"ask": ask, "done": done})
+rt = Runtime(run_store=InMemoryRunStore(), ledger_store=InMemoryLedgerStore())
+
+run_id = rt.start(workflow=wf)
+state = rt.tick(workflow=wf, run_id=run_id)
+assert state.status.value == "waiting"
+
+state = rt.resume(
+    workflow=wf,
+    run_id=run_id,
+    wait_key=state.waiting.wait_key,
+    payload={"text": "yes"},
+)
+assert state.status.value == "completed"
+```
+
+---
+
+### Built-in Scheduler
+
+AbstractRuntime includes a zero-config scheduler for automatic run resumption:
+
+```python
+from abstractruntime import create_scheduled_runtime
+
+# Zero-config: defaults to in-memory storage, auto-starts scheduler
+sr = create_scheduled_runtime()
+
+# run() does start + tick in one call
+run_id, state = sr.run(my_workflow)
+
+# If waiting for user input, respond (auto-finds wait_key)
+if state.status.value == "waiting":
+    state = sr.respond(run_id, {"answer": "yes"})
+
+# Stop scheduler when done
+sr.stop()
+```
+
+For production with persistent storage:
+
+```python
+from abstractruntime import create_scheduled_runtime, JsonFileRunStore, JsonlLedgerStore
+
+sr = create_scheduled_runtime(
+    run_store=JsonFileRunStore("./data"),
+    ledger_store=JsonlLedgerStore("./data"),
+)
+```
+
+---
+
+### AbstractCore integration (LLM + tools)
+
+AbstractRuntime’s kernel stays dependency-light; AbstractCore integration lives in:
+- `src/abstractruntime/integrations/abstractcore/`
+
+Execution modes:
+- **Local**: in-process AbstractCore providers + local tool execution
+- **Remote**: HTTP to AbstractCore server (`/v1/chat/completions`) + tool passthrough (default)
+- **Hybrid**: remote LLM + local tool execution
+
+See: `docs/integrations/abstractcore.md`.
+
+---
+
+### Snapshots / bookmarks
+
+Snapshots are named, searchable checkpoints of a run state:
+- `Snapshot(snapshot_id, run_id, name, description, tags, run_state)`
+
+See: `docs/snapshots.md`.
+
+---
+
+### Provenance (tamper-evident ledger)
+
+You can wrap any `LedgerStore` with a hash chain:
+
+- `HashChainedLedgerStore(inner_store)`
+- `verify_ledger_chain(records)`
+
+This is **tamper-evident**, not non-forgeable (signatures are optional future work).
+
+See: `docs/provenance.md`.
+
+---
+
+### Documentation index
+
+| Document | Description |
+|----------|-------------|
+| [Proposal](docs/proposal.md) | Design goals, core concepts, and scope |
+| [ROADMAP](ROADMAP.md) | Prioritized next steps with rationale |
+| [ADRs](docs/adr/) | Architectural decisions and their rationale |
+| [Backlog](docs/backlog/) | Completed and planned work items |
+| [Integrations](docs/integrations/) | AbstractCore integration guide |
+| [Snapshots](docs/snapshots.md) | Named checkpoints for run state |
+| [Provenance](docs/provenance.md) | Tamper-evident ledger documentation |

abstractruntime-0.2.0/README.md

@@ -0,0 +1,141 @@
+## AbstractRuntime
+
+**AbstractRuntime** is a low-level **durable workflow runtime**:
+- Execute workflow graphs (state machines)
+- **Interrupt → checkpoint → resume** (hours/days) without keeping Python stacks alive
+- Append-only **ledger** ("journal d’exécution") for audit/debug/provenance
+
+**Status**: MVP kernel + file persistence + AbstractCore integration adapters are implemented.
+
+---
+
+### Key concepts
+- **WorkflowSpec**: graph definition (node handlers keyed by id)
+- **RunState**: durable state (`current_node`, `vars`, `waiting`, etc.)
+- **Effect**: a side-effect request (`llm_call`, `tool_calls`, `ask_user`, `wait_event`, ...)
+- **Ledger**: append-only step records (`StepRecord`) describing what happened
+
+---
+
+### Quick start (pause + resume)
+
+```python
+from abstractruntime import Effect, EffectType, Runtime, StepPlan, WorkflowSpec
+from abstractruntime.storage import InMemoryLedgerStore, InMemoryRunStore
+
+
+def ask(run, ctx):
+    return StepPlan(
+        node_id="ask",
+        effect=Effect(
+            type=EffectType.ASK_USER,
+            payload={"prompt": "Continue?"},
+            result_key="user_answer",
+        ),
+        next_node="done",
+    )
+
+
+def done(run, ctx):
+    return StepPlan(node_id="done", complete_output={"answer": run.vars.get("user_answer")})
+
+
+wf = WorkflowSpec(workflow_id="demo", entry_node="ask", nodes={"ask": ask, "done": done})
+rt = Runtime(run_store=InMemoryRunStore(), ledger_store=InMemoryLedgerStore())
+
+run_id = rt.start(workflow=wf)
+state = rt.tick(workflow=wf, run_id=run_id)
+assert state.status.value == "waiting"
+
+state = rt.resume(
+    workflow=wf,
+    run_id=run_id,
+    wait_key=state.waiting.wait_key,
+    payload={"text": "yes"},
+)
+assert state.status.value == "completed"
+```
+
+---
+
+### Built-in Scheduler
+
+AbstractRuntime includes a zero-config scheduler for automatic run resumption:
+
+```python
+from abstractruntime import create_scheduled_runtime
+
+# Zero-config: defaults to in-memory storage, auto-starts scheduler
+sr = create_scheduled_runtime()
+
+# run() does start + tick in one call
+run_id, state = sr.run(my_workflow)
+
+# If waiting for user input, respond (auto-finds wait_key)
+if state.status.value == "waiting":
+    state = sr.respond(run_id, {"answer": "yes"})
+
+# Stop scheduler when done
+sr.stop()
+```
+
+For production with persistent storage:
+
+```python
+from abstractruntime import create_scheduled_runtime, JsonFileRunStore, JsonlLedgerStore
+
+sr = create_scheduled_runtime(
+    run_store=JsonFileRunStore("./data"),
+    ledger_store=JsonlLedgerStore("./data"),
+)
+```
+
+---
+
+### AbstractCore integration (LLM + tools)
+
+AbstractRuntime’s kernel stays dependency-light; AbstractCore integration lives in:
+- `src/abstractruntime/integrations/abstractcore/`
+
+Execution modes:
+- **Local**: in-process AbstractCore providers + local tool execution
+- **Remote**: HTTP to AbstractCore server (`/v1/chat/completions`) + tool passthrough (default)
+- **Hybrid**: remote LLM + local tool execution
+
+See: `docs/integrations/abstractcore.md`.
+
+---
+
+### Snapshots / bookmarks
+
+Snapshots are named, searchable checkpoints of a run state:
+- `Snapshot(snapshot_id, run_id, name, description, tags, run_state)`
+
+See: `docs/snapshots.md`.
+
+---
+
+### Provenance (tamper-evident ledger)
+
+You can wrap any `LedgerStore` with a hash chain:
+
+- `HashChainedLedgerStore(inner_store)`
+- `verify_ledger_chain(records)`
+
+This is **tamper-evident**, not non-forgeable (signatures are optional future work).
+
+See: `docs/provenance.md`.
+
+---
+
+### Documentation index
+
+| Document | Description |
+|----------|-------------|
+| [Proposal](docs/proposal.md) | Design goals, core concepts, and scope |
+| [ROADMAP](ROADMAP.md) | Prioritized next steps with rationale |
+| [ADRs](docs/adr/) | Architectural decisions and their rationale |
+| [Backlog](docs/backlog/) | Completed and planned work items |
+| [Integrations](docs/integrations/) | AbstractCore integration guide |
+| [Snapshots](docs/snapshots.md) | Named checkpoints for run state |
+| [Provenance](docs/provenance.md) | Tamper-evident ledger documentation |