AbstractRuntime 0.0.0__tar.gz → 0.0.1__tar.gz

abstractruntime-0.0.1/.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.0.0 → abstractruntime-0.0.1}/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.0.1/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: AbstractRuntime
+Version: 0.0.1
+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.0.1/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 |

abstractruntime-0.0.1/ROADMAP.md

@@ -0,0 +1,234 @@
+# AbstractRuntime Roadmap
+
+## Current Status: MVP Complete (v0.1)
+
+AbstractRuntime has a functional MVP kernel with:
+- Durable workflow execution (start/tick/resume)
+- Explicit waiting states (wait_event, wait_until, ask_user)
+- Persistence (in-memory + JSON/JSONL file backends)
+- Snapshots/bookmarks for named checkpoints
+- Tamper-evident provenance (hash-chained ledger)
+- AbstractCore integration (local/remote/hybrid execution modes)
+- **QueryableRunStore** for listing/filtering runs ✅
+- **Built-in Scheduler** with zero-config operation ✅
+- Test coverage for core functionality (81% overall, 57 tests)
+
+---
+
+## Why AbstractRuntime Exists
+
+AbstractRuntime is the **durable execution substrate** that sits below both AbstractAgent and AbstractFlow:
+
+```
+AbstractFlow (UI graphs, multi-agent orchestration, templates)
+     │
+AbstractAgent (ReAct, CodeAct, specialized agents like DeepSearch)
+     │
+AbstractRuntime (interrupt/checkpoint/resume, ledger, snapshots)
+     │
+AbstractCore (LLM calls, tool execution, server API)
+```
+
+**Key insight**: You cannot keep Python stacks alive for days. When an agent needs to:
+- Ask a user a question and wait hours/days for a response
+- Wait until a scheduled time
+- Wait for an external job to complete
+
+...you need **durable state that survives process restarts**. This is what AbstractRuntime provides.
+
+**Why not in AbstractFlow?** Because individual agents need these primitives directly. A ReAct agent that calls `ask_user` needs to pause and resume — that's not orchestration, that's the agent itself needing durability.
+
+---
+
+## Phase 1: Core Completeness ✅ COMPLETE
+
+### 1.1 Built-in Scheduler (Zero-Config) ✅
+**Status: COMPLETE** | **Backlog: 004**
+
+**What shipped**:
+- `WorkflowRegistry` for mapping workflow_id → WorkflowSpec
+- `Scheduler` class with background polling thread
+- `ScheduledRuntime` convenience wrapper
+- `create_scheduled_runtime()` factory function
+- Event ingestion via `scheduler.resume_event()`
+- Stats tracking and callbacks
+
+**Usage**:
+```python
+# Zero-config: defaults to in-memory, auto-starts scheduler
+sr = create_scheduled_runtime()
+
+# run() does start + tick in one call
+run_id, state = sr.run(my_workflow)
+
+# respond() auto-finds wait_key
+if state.status.value == "waiting":
+    state = sr.respond(run_id, {"answer": "yes"})
+
+sr.stop()
+```
+
+---
+
+## Phase 2: Composition and Examples (Next Priority)
+
+### 2.1 Subworkflow Support
+**Priority: High** | **Effort: Medium** | **Backlog: 011**
+
+**Why**: `EffectType.START_SUBWORKFLOW` exists but has no handler. Without this:
+- Multi-agent orchestration is impossible
+- Workflow composition (DeepSearch as a node) doesn't work
+- AbstractFlow cannot compose agents
+
+**Deliverables**:
+- Workflow registry interface
+- `START_SUBWORKFLOW` effect handler
+- Sync and async subworkflow modes
+- Tests for parent/child workflow interaction
+
+**Success criteria**: A workflow can invoke another workflow by ID and receive its output.
+
+---
+
+### 2.2 Examples and Documentation
+**Priority: High** | **Effort: Low** | **Backlog: 010**
+
+**Why**: The MVP is functional but lacks concrete examples. Developers cannot understand how to build workflows without reading source code.
+
+**Deliverables**:
+- `examples/` directory with runnable workflows
+- ask_user interrupt example (pause for days, resume)
+- wait_until timer example
+- LLM call + tool execution example
+- Subworkflow composition example
+
+**Success criteria**: A developer can copy an example and have a working workflow in 5 minutes.
+
+---
+
+## Phase 3: Production Readiness
+
+### 3.1 Artifact Store
+**Priority: Medium** | **Effort: Medium** | **Backlog: 009**
+
+**Why**: Large payloads (documents, images, tool outputs) embedded in `RunState.vars` cause performance issues. The constraint that vars must be JSON-serializable becomes painful without by-reference storage.
+
+**Deliverables**:
+- `ArtifactStore` interface
+- File-based implementation
+- `ArtifactRef` type for referencing stored artifacts
+- Integration with RunState serialization
+
+**Success criteria**: A workflow can store a 10MB document without bloating the checkpoint.
+
+---
+
+### 3.2 Effect Retries and Idempotency
+**Priority: Medium** | **Effort: Medium** | **Backlog: 013**
+
+**Why**: At-least-once execution is a real risk. If a process crashes after an LLM call but before checkpointing, the call may be duplicated on restart.
+
+**Deliverables**:
+- `EffectPolicy` protocol (max_attempts, backoff, idempotency_key)
+- Ledger-based deduplication
+- Retry logic in runtime loop
+
+**Success criteria**: A workflow survives a crash/restart without duplicating side effects.
+
+---
+
+## Phase 4: Advanced Features
+
+### 4.1 Cryptographic Signatures
+**Priority: Low** | **Effort: High** | **Backlog: 008**
+
+**Why**: The hash chain provides tamper-evidence but not non-forgeability. For high-accountability scenarios (AI fingerprinting, regulatory compliance), cryptographic signatures are needed.
+
+**Dependencies**: 007 (Hash Chain - complete)
+
+**Deliverables**:
+- Ed25519 keypair generation
+- `actor_id` bound to public key
+- Signed `StepRecord` entries
+- Signature verification in `verify_ledger_chain`
+- Key storage patterns (file, OS keychain, Vault)
+
+**Success criteria**: A ledger can prove which actor produced each step.
+
+---
+
+### 4.2 Remote Tool Worker
+**Priority: Low** | **Effort: Medium** | **Backlog: 014**
+
+**Why**: Some deployments need centralized tool execution (thin clients, sandboxed environments). The current passthrough mode requires the host to execute tools; a worker service would handle this automatically.
+
+**Deliverables**:
+- Tool worker API contract
+- `RemoteToolExecutor` implementation
+- Job-based waiting semantics
+
+**Success criteria**: A thin client can run workflows with tools by delegating to a worker service.
+
+---
+
+## Relationship to the Abstract Series
+
+AbstractRuntime is the **durable execution substrate** that enables both agents and memory to have long-running, interruptible workflows.
+
+```
+AbstractFlow (UI graphs, multi-agent orchestration, templates)
+     │
+     ├── AbstractSwarm (swarm of agents - future)
+     │
+AbstractAgent (ReAct, CodeAct, DeepSearch, specialized agents)
+     │
+     ├── AbstractMemory (agentic memory - consolidation, reflection, forgetting)
+     │
+AbstractRuntime (interrupt/checkpoint/resume, ledger, snapshots)
+     │
+AbstractCore (LLM calls, tool execution, server API)
+```
+
+**Why this layering?**
+- **AbstractAgent** needs durability primitives directly (an agent might `ask_user` and wait days)
+- **AbstractMemory** needs the same primitives (memory consolidation might run on a schedule)
+- **AbstractFlow** composes agents and workflows, using AbstractRuntime for execution
+- **AbstractRuntime** provides the substrate; it doesn't know about "agents" or "memory" — just workflows
+
+**Snapshots enable time-travel debugging:**
+- Save a named checkpoint at any point
+- Restore a multi-agent system to a previous state
+- Rebuild context from ledger + snapshot
+
+---
+
+## Decision Log
+
+| Decision | Rationale |
+|----------|-----------|
+| Kernel stays dependency-light | Enables portability, stability, and clear integration boundaries |
+| AbstractCore integration is opt-in | Layered coupling prevents kernel from breaking when AbstractCore changes |
+| Hash chain before signatures | Provides value immediately without key management complexity |
+| Built-in scheduler (not external) | UX principle: simplify as much as possible; zero-config for simple cases |
+| Graph representation for all workflows | A loop is a simple graph; graphs enable visualization, checkpointing, composition |
+
+---
+
+## Timeline (Estimated)
+
+| Phase | Items | Status |
+|-------|-------|--------|
+| 1.1 | Scheduler + RunStore Query | ✅ Complete |
+| 2.1 | Subworkflow | 2-3 days |
+| 2.2 | Examples | 1-2 days |
+| 3.1 | Artifact Store | 2-3 days |
+| 3.2 | Retries/Idempotency | 3-4 days |
+| 4.1 | Signatures | 1 week |
+| 4.2 | Remote Worker | 3-4 days |
+
+**Phase 1 (Core Completeness)**: ✅ Complete
+**Phase 2 (Composition)**: ~3-5 days
+**Phase 3 (Production Readiness)**: ~1 week  
+**Phase 4 (Advanced Features)**: ~2 weeks
+
+Remaining: ~3-4 weeks for full roadmap.

abstractruntime-0.0.1/docs/adr/0001_layered_coupling_with_abstractcore.md

@@ -0,0 +1,27 @@
+## ADR 0001: Layered coupling with AbstractCore
+
+### Status
+Accepted (2025-12-11)
+
+### Context
+AbstractRuntime needs to reuse AbstractCore capabilities (LLM calls, tool execution, structured logging), but we must keep the **durable kernel** stable and dependency-light.
+
+Mixing AbstractCore imports into the kernel creates:
+- brittle coupling to AbstractCore internals
+- larger runtime footprint for processes that only need bookkeeping (stores/ledger)
+- harder evolution of the durable state machine
+
+### Decision
+- The kernel (`abstractruntime.core`, `abstractruntime.storage`, `abstractruntime.identity`) must **not** import AbstractCore.
+- AbstractCore integration is an explicit opt-in module:
+  - `abstractruntime.integrations.abstractcore`
+
+### Consequences
+- Kernel remains stable and reusable across topologies.
+- AbstractCore can evolve; only the integration module needs updates.
+- We still support heavy reuse of AbstractCore in real deployments (local/remote/hybrid execution modes).
+
+### See Also
+- Implementation: [`backlog/completed/005_abstractcore_integration.md`](../backlog/completed/005_abstractcore_integration.md)
+- Code: `src/abstractruntime/integrations/abstractcore/`
+

abstractruntime-0.0.1/docs/adr/0002_execution_modes_local_remote_hybrid.md

@@ -0,0 +1,32 @@
+## ADR 0002: Execution modes (local, remote, hybrid)
+
+### Status
+Accepted (2025-12-11)
+
+### Context
+Agents/workflows must run in multiple deployment topologies:
+- thin clients (mobile/web) calling a backend LLM gateway
+- backend orchestration calling GPU inference fleets
+- local/dev mode (everything on one machine)
+
+AbstractCore already provides two compatible boundaries:
+- in-process python API (`create_llm(...).generate(...)`)
+- HTTP server boundary (`/v1/chat/completions`)
+
+### Decision
+AbstractRuntime supports three execution modes:
+
+- **Local**: in-process AbstractCore LLM + local tool execution
+- **Remote**: HTTP to AbstractCore server; tools default to passthrough (untrusted)
+- **Hybrid**: remote LLM + local tool execution
+
+### Consequences
+- Thin-mode clients can run the workflow logic while delegating inference to a server.
+- Remote mode supports AbstractCore per-request `base_url` routing (dynamic endpoint selection).
+- Tool execution can be gated by trust/sandbox policy outside the router.
+
+### See Also
+- Implementation: [`backlog/completed/005_abstractcore_integration.md`](../backlog/completed/005_abstractcore_integration.md)
+- Integration guide: [`integrations/abstractcore.md`](../integrations/abstractcore.md)
+- Code: `src/abstractruntime/integrations/abstractcore/factory.py`
+