AbstractRuntime 0.0.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

abstractruntime/__init__.py

@@ -1,8 +1,110 @@
 """
 AbstractRuntime
 
-Placeholder package for a durable graph runner (interrupt → checkpoint → resume).
-Implementation intentionally not included yet.
+Durable graph runner (interrupt → checkpoint → resume).
+
+This package provides a minimal execution substrate:
+- workflow graphs (state machines)
+- durable RunState with WAITING / RESUME semantics
+- append-only execution journal (ledger)
+
+Higher-level orchestration and UI graph authoring is expected to live in AbstractFlow.
 """
 
+from .core.models import (
+    Effect,
+    EffectType,
+    RunState,
+    RunStatus,
+    StepPlan,
+    WaitReason,
+    WaitState,
+)
+from .core.runtime import Runtime
+from .core.spec import WorkflowSpec
+from .core.policy import (
+    EffectPolicy,
+    DefaultEffectPolicy,
+    RetryPolicy,
+    NoRetryPolicy,
+    compute_idempotency_key,
+)
+from .storage.base import QueryableRunStore
+from .storage.in_memory import InMemoryLedgerStore, InMemoryRunStore
+from .storage.json_files import JsonFileRunStore, JsonlLedgerStore
+from .storage.ledger_chain import HashChainedLedgerStore, verify_ledger_chain
+from .storage.snapshots import Snapshot, SnapshotStore, InMemorySnapshotStore, JsonSnapshotStore
+from .storage.artifacts import (
+    Artifact,
+    ArtifactMetadata,
+    ArtifactStore,
+    InMemoryArtifactStore,
+    FileArtifactStore,
+    artifact_ref,
+    is_artifact_ref,
+    get_artifact_id,
+    resolve_artifact,
+    compute_artifact_id,
+)
+from .identity.fingerprint import ActorFingerprint
+from .scheduler import (
+    WorkflowRegistry,
+    Scheduler,
+    SchedulerStats,
+    ScheduledRuntime,
+    create_scheduled_runtime,
+)
+
+__all__ = [
+    # Core models
+    "Effect",
+    "EffectType",
+    "RunState",
+    "RunStatus",
+    "StepPlan",
+    "WaitReason",
+    "WaitState",
+    # Spec + runtime
+    "WorkflowSpec",
+    "Runtime",
+    # Scheduler
+    "WorkflowRegistry",
+    "Scheduler",
+    "SchedulerStats",
+    "ScheduledRuntime",
+    "create_scheduled_runtime",
+    # Storage backends
+    "QueryableRunStore",
+    "InMemoryRunStore",
+    "InMemoryLedgerStore",
+    "JsonFileRunStore",
+    "JsonlLedgerStore",
+    "HashChainedLedgerStore",
+    "verify_ledger_chain",
+    "Snapshot",
+    "SnapshotStore",
+    "InMemorySnapshotStore",
+    "JsonSnapshotStore",
+    # Artifacts
+    "Artifact",
+    "ArtifactMetadata",
+    "ArtifactStore",
+    "InMemoryArtifactStore",
+    "FileArtifactStore",
+    "artifact_ref",
+    "is_artifact_ref",
+    "get_artifact_id",
+    "resolve_artifact",
+    "compute_artifact_id",
+    # Identity
+    "ActorFingerprint",
+    # Effect policies
+    "EffectPolicy",
+    "DefaultEffectPolicy",
+    "RetryPolicy",
+    "NoRetryPolicy",
+    "compute_idempotency_key",
+]
+
+
 

abstractruntime/core/__init__.py

@@ -0,0 +1,26 @@
+"""Core runtime primitives."""
+
+from .config import RuntimeConfig
+from .models import Effect, EffectType, LimitWarning, RunState, RunStatus, StepPlan, WaitReason, WaitState
+from .runtime import Runtime
+from .spec import WorkflowSpec
+from .vars import LIMITS, ensure_limits, get_limits
+
+__all__ = [
+    "Effect",
+    "EffectType",
+    "LimitWarning",
+    "LIMITS",
+    "RunState",
+    "RunStatus",
+    "Runtime",
+    "RuntimeConfig",
+    "StepPlan",
+    "WaitReason",
+    "WaitState",
+    "WorkflowSpec",
+    "ensure_limits",
+    "get_limits",
+]
+
+

abstractruntime/core/config.py

@@ -0,0 +1,101 @@
+"""abstractruntime.core.config
+
+Runtime configuration for resource limits and model capabilities.
+
+This module provides a RuntimeConfig dataclass that centralizes configuration
+for runtime resource limits (iterations, tokens, history) and model capabilities.
+The config is used to initialize the `_limits` namespace in RunState.vars.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+
+@dataclass(frozen=True)
+class RuntimeConfig:
+    """Configuration for runtime resource limits and model capabilities.
+
+    This configuration is used by the Runtime to:
+    1. Initialize the `_limits` namespace in RunState.vars when starting a run
+    2. Provide model capability information for resource tracking
+    3. Configure warning thresholds for proactive notifications
+
+    Attributes:
+        max_iterations: Maximum number of reasoning iterations (default: 25)
+        warn_iterations_pct: Percentage threshold for iteration warnings (default: 80)
+        max_tokens: Maximum context window tokens (None = use model capabilities)
+        max_output_tokens: Maximum tokens for LLM response (None = provider default)
+        warn_tokens_pct: Percentage threshold for token warnings (default: 80)
+        max_history_messages: Maximum conversation history messages (-1 = unlimited)
+        model_capabilities: Dict of model capabilities from LLM provider
+
+    Example:
+        >>> config = RuntimeConfig(max_iterations=50, max_tokens=65536)
+        >>> limits = config.to_limits_dict()
+        >>> limits["max_iterations"]
+        50
+    """
+
+    # Iteration control
+    max_iterations: int = 25
+    warn_iterations_pct: int = 80
+
+    # Token/context window management
+    max_tokens: Optional[int] = None  # None = query from model capabilities
+    max_output_tokens: Optional[int] = None  # None = use provider default
+    warn_tokens_pct: int = 80
+
+    # History management
+    max_history_messages: int = -1  # -1 = unlimited (send all messages)
+
+    # Model capabilities (populated from LLM client)
+    model_capabilities: Dict[str, Any] = field(default_factory=dict)
+
+    def to_limits_dict(self) -> Dict[str, Any]:
+        """Convert to _limits namespace dict for RunState.vars.
+
+        Returns:
+            Dict with canonical limit values for storage in RunState.vars["_limits"].
+            Uses model_capabilities as fallback for max_tokens if not explicitly set.
+        """
+        return {
+            # Iteration control
+            "max_iterations": self.max_iterations,
+            "current_iteration": 0,
+
+            # Token management
+            "max_tokens": self.max_tokens or self.model_capabilities.get("max_tokens", 32768),
+            "max_output_tokens": self.max_output_tokens,
+            "estimated_tokens_used": 0,
+
+            # History management
+            "max_history_messages": self.max_history_messages,
+
+            # Warning thresholds
+            "warn_iterations_pct": self.warn_iterations_pct,
+            "warn_tokens_pct": self.warn_tokens_pct,
+        }
+
+    def with_capabilities(self, capabilities: Dict[str, Any]) -> "RuntimeConfig":
+        """Create a new RuntimeConfig with updated model capabilities.
+
+        This is useful for merging model capabilities from an LLM client
+        into an existing configuration.
+
+        Args:
+            capabilities: Dict of model capabilities (e.g., from get_model_capabilities())
+
+        Returns:
+            New RuntimeConfig with merged capabilities
+        """
+        return RuntimeConfig(
+            max_iterations=self.max_iterations,
+            warn_iterations_pct=self.warn_iterations_pct,
+            max_tokens=self.max_tokens,
+            max_output_tokens=self.max_output_tokens,
+            warn_tokens_pct=self.warn_tokens_pct,
+            max_history_messages=self.max_history_messages,
+            model_capabilities=capabilities,
+        )

abstractruntime/core/models.py

@@ -0,0 +1,282 @@
+"""abstractruntime.core.models
+
+Core data model for AbstractRuntime (v0.1).
+
+Design intent:
+- Keep everything JSON-serializable (durable execution)
+- Separate *what to do* (Effect) from *how to do it* (EffectHandler)
+- Represent long pauses explicitly (WaitState), never by keeping Python stacks alive
+
+We intentionally keep this module dependency-light (stdlib only).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, List, Optional
+import uuid
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class RunStatus(str, Enum):
+    RUNNING = "running"
+    WAITING = "waiting"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class WaitReason(str, Enum):
+    EVENT = "event"         # arbitrary external signal
+    UNTIL = "until"         # time-based
+    USER = "user"           # human-in-the-loop
+    JOB = "job"             # external job completion
+    SUBWORKFLOW = "subworkflow"  # waiting for child workflow
+
+
+class EffectType(str, Enum):
+    """Side-effects a node can request."""
+
+    # Pure waiting primitives
+    WAIT_EVENT = "wait_event"
+    WAIT_UNTIL = "wait_until"
+    ASK_USER = "ask_user"
+
+    # Integrations (implemented via pluggable handlers)
+    LLM_CALL = "llm_call"
+    TOOL_CALLS = "tool_calls"
+
+    # Composition
+    START_SUBWORKFLOW = "start_subworkflow"
+
+
+@dataclass(frozen=True)
+class Effect:
+    """A request for an external side-effect.
+
+    Notes:
+    - Effects must be serializable (payload is JSON-like).
+    - `result_key` specifies where the effect result is stored in run state variables.
+    """
+
+    type: EffectType
+    payload: Dict[str, Any] = field(default_factory=dict)
+    result_key: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class StepPlan:
+    """What the runtime should do next for a node."""
+
+    node_id: str
+    effect: Optional[Effect] = None
+    next_node: Optional[str] = None
+
+    # If set, the runtime completes the run immediately.
+    complete_output: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class WaitState:
+    """Represents a durable pause.
+
+    The run can be resumed by calling `resume(run_id, event)`.
+
+    - For EVENT/USER/JOB: `wait_key` identifies which event unblocks the run.
+    - For UNTIL: `until` specifies when the run can continue.
+
+    `resume_to_node` defines where execution continues after resume.
+    `result_key` tells where to store the resume payload.
+    """
+
+    reason: WaitReason
+    wait_key: Optional[str] = None
+    until: Optional[str] = None  # ISO timestamp
+
+    resume_to_node: Optional[str] = None
+    result_key: Optional[str] = None
+
+    prompt: Optional[str] = None
+    choices: Optional[List[str]] = None
+    allow_free_text: bool = True
+
+    # Optional structured details for non-user waits (e.g. tool passthrough).
+    # Must be JSON-serializable.
+    details: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class RunState:
+    """Durable state for a workflow run."""
+
+    run_id: str
+    workflow_id: str
+    status: RunStatus
+    current_node: str
+
+    vars: Dict[str, Any] = field(default_factory=dict)
+
+    waiting: Optional[WaitState] = None
+    output: Optional[Dict[str, Any]] = None
+    error: Optional[str] = None
+
+    created_at: str = field(default_factory=lambda: utc_now().isoformat())
+    updated_at: str = field(default_factory=lambda: utc_now().isoformat())
+
+    # Optional provenance fields
+    actor_id: Optional[str] = None
+    session_id: Optional[str] = None
+    parent_run_id: Optional[str] = None  # For subworkflow tracking
+
+    @classmethod
+    def new(
+        cls,
+        *,
+        workflow_id: str,
+        entry_node: str,
+        actor_id: Optional[str] = None,
+        session_id: Optional[str] = None,
+        vars: Optional[Dict[str, Any]] = None,
+        parent_run_id: Optional[str] = None,
+    ) -> "RunState":
+        return cls(
+            run_id=str(uuid.uuid4()),
+            workflow_id=workflow_id,
+            status=RunStatus.RUNNING,
+            current_node=entry_node,
+            vars=vars or {},
+            actor_id=actor_id,
+            session_id=session_id,
+            parent_run_id=parent_run_id,
+        )
+
+
+class StepStatus(str, Enum):
+    STARTED = "started"
+    COMPLETED = "completed"
+    WAITING = "waiting"
+    FAILED = "failed"
+
+
+@dataclass
+class StepRecord:
+    """One append-only ledger entry (journal d'exécution)."""
+
+    run_id: str
+    step_id: str
+    node_id: str
+    status: StepStatus
+
+    effect: Optional[Dict[str, Any]] = None
+    result: Optional[Dict[str, Any]] = None
+    error: Optional[str] = None
+
+    started_at: str = field(default_factory=lambda: utc_now().isoformat())
+    ended_at: Optional[str] = None
+
+    # Optional provenance/integrity
+    actor_id: Optional[str] = None
+    session_id: Optional[str] = None
+
+    # Retry and idempotency fields
+    attempt: int = 1  # Current attempt number (1-indexed)
+    idempotency_key: Optional[str] = None  # For deduplication on restart
+
+    # Tamper-evident chain fields (optional in v0.1; filled by a chained LedgerStore).
+    prev_hash: Optional[str] = None
+    record_hash: Optional[str] = None
+    signature: Optional[str] = None
+
+    @classmethod
+    def start(
+        cls,
+        *,
+        run: RunState,
+        node_id: str,
+        effect: Optional[Effect],
+        attempt: int = 1,
+        idempotency_key: Optional[str] = None,
+    ) -> "StepRecord":
+        return cls(
+            run_id=run.run_id,
+            step_id=str(uuid.uuid4()),
+            node_id=node_id,
+            status=StepStatus.STARTED,
+            effect={
+                "type": effect.type.value,
+                "payload": effect.payload,
+                "result_key": effect.result_key,
+            } if effect else None,
+            actor_id=run.actor_id,
+            session_id=getattr(run, "session_id", None),
+            attempt=attempt,
+            idempotency_key=idempotency_key,
+        )
+
+    def finish_success(self, result: Optional[Dict[str, Any]] = None) -> "StepRecord":
+        self.status = StepStatus.COMPLETED
+        self.result = result
+        self.ended_at = utc_now().isoformat()
+        return self
+
+    def finish_waiting(self, wait_state: WaitState) -> "StepRecord":
+        self.status = StepStatus.WAITING
+        self.result = {
+            "wait": {
+                "reason": wait_state.reason.value,
+                "wait_key": wait_state.wait_key,
+                "until": wait_state.until,
+                "resume_to_node": wait_state.resume_to_node,
+                "result_key": wait_state.result_key,
+                # Optional fields for richer audit/debugging
+                "prompt": wait_state.prompt,
+                "choices": wait_state.choices,
+                "allow_free_text": wait_state.allow_free_text,
+                "details": wait_state.details,
+            }
+        }
+        self.ended_at = utc_now().isoformat()
+        return self
+
+    def finish_failure(self, error: str) -> "StepRecord":
+        self.status = StepStatus.FAILED
+        self.error = error
+        self.ended_at = utc_now().isoformat()
+        return self
+
+
+@dataclass
+class LimitWarning:
+    """Warning about approaching or exceeding a runtime limit.
+
+    Generated by Runtime.check_limits() to proactively notify about
+    resource constraints before they cause failures.
+
+    Attributes:
+        limit_type: Type of limit ("iterations", "tokens", "history")
+        status: Warning status ("warning" at threshold, "exceeded" at limit)
+        current: Current value of the resource
+        maximum: Maximum allowed value
+        pct: Percentage of limit used (computed in __post_init__)
+
+    Example:
+        >>> warning = LimitWarning("iterations", "warning", 20, 25)
+        >>> warning.pct
+        80.0
+    """
+
+    limit_type: str  # "iterations", "tokens", "history"
+    status: str  # "warning", "exceeded"
+    current: int
+    maximum: int
+    pct: float = 0.0
+
+    def __post_init__(self) -> None:
+        if self.maximum > 0:
+            self.pct = round(self.current / self.maximum * 100, 1)
+

abstractruntime/core/policy.py

@@ -0,0 +1,166 @@
+"""abstractruntime.core.policy
+
+Effect execution policies for retry and idempotency.
+
+Policies control:
+- How many times to retry a failed effect
+- Backoff timing between retries
+- Idempotency keys for deduplication on crash recovery
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Protocol
+
+from .models import Effect, RunState
+
+
+class EffectPolicy(Protocol):
+    """Protocol for effect execution policies.
+    
+    Implementations control retry behavior and idempotency.
+    """
+
+    def max_attempts(self, effect: Effect) -> int:
+        """Maximum number of attempts for an effect.
+        
+        Args:
+            effect: The effect being executed.
+            
+        Returns:
+            Maximum attempts (1 = no retries, 2 = one retry, etc.)
+        """
+        ...
+
+    def backoff_seconds(self, *, effect: Effect, attempt: int) -> float:
+        """Seconds to wait before retry.
+        
+        Args:
+            effect: The effect being retried.
+            attempt: Current attempt number (1-indexed).
+            
+        Returns:
+            Seconds to wait before next attempt.
+        """
+        ...
+
+    def idempotency_key(
+        self, *, run: RunState, node_id: str, effect: Effect
+    ) -> str:
+        """Compute idempotency key for an effect.
+        
+        Effects with the same idempotency key are considered duplicates.
+        If a prior completed result exists for this key, it will be reused.
+        
+        Args:
+            run: Current run state.
+            node_id: Current node ID.
+            effect: The effect being executed.
+            
+        Returns:
+            Idempotency key string.
+        """
+        ...
+
+
+@dataclass
+class DefaultEffectPolicy:
+    """Default effect policy with configurable retry and idempotency.
+    
+    Attributes:
+        default_max_attempts: Default max attempts for all effects.
+        default_backoff_base: Base backoff in seconds (exponential).
+        default_backoff_max: Maximum backoff in seconds.
+        effect_max_attempts: Per-effect-type max attempts override.
+    """
+
+    default_max_attempts: int = 1  # No retries by default
+    default_backoff_base: float = 1.0
+    default_backoff_max: float = 60.0
+    effect_max_attempts: Dict[str, int] = None  # type: ignore
+
+    def __post_init__(self):
+        if self.effect_max_attempts is None:
+            self.effect_max_attempts = {}
+
+    def max_attempts(self, effect: Effect) -> int:
+        """Get max attempts for an effect type."""
+        effect_type = effect.type.value
+        return self.effect_max_attempts.get(effect_type, self.default_max_attempts)
+
+    def backoff_seconds(self, *, effect: Effect, attempt: int) -> float:
+        """Exponential backoff capped at max."""
+        # Exponential: base * 2^(attempt-1), capped at max
+        delay = self.default_backoff_base * (2 ** (attempt - 1))
+        return min(delay, self.default_backoff_max)
+
+    def idempotency_key(
+        self, *, run: RunState, node_id: str, effect: Effect
+    ) -> str:
+        """Compute idempotency key from run_id, node_id, and effect.
+        
+        The key is a hash of:
+        - run_id: Unique to this run
+        - node_id: Current node
+        - effect type and payload: What we're doing
+        
+        This ensures the same effect at the same point in the same run
+        gets the same key, enabling deduplication on restart.
+        """
+        key_data = {
+            "run_id": run.run_id,
+            "node_id": node_id,
+            "effect_type": effect.type.value,
+            "effect_payload": effect.payload,
+        }
+        key_json = json.dumps(key_data, sort_keys=True, separators=(",", ":"))
+        return hashlib.sha256(key_json.encode()).hexdigest()[:32]
+
+
+class RetryPolicy(DefaultEffectPolicy):
+    """Policy with retries enabled for LLM and tool calls."""
+
+    def __init__(
+        self,
+        *,
+        llm_max_attempts: int = 3,
+        tool_max_attempts: int = 2,
+        backoff_base: float = 1.0,
+        backoff_max: float = 30.0,
+    ):
+        super().__init__(
+            default_max_attempts=1,
+            default_backoff_base=backoff_base,
+            default_backoff_max=backoff_max,
+            effect_max_attempts={
+                "llm_call": llm_max_attempts,
+                "tool_calls": tool_max_attempts,
+            },
+        )
+
+
+class NoRetryPolicy(DefaultEffectPolicy):
+    """Policy with no retries (fail immediately)."""
+
+    def __init__(self):
+        super().__init__(default_max_attempts=1)
+
+
+def compute_idempotency_key(
+    *, run_id: str, node_id: str, effect: Effect
+) -> str:
+    """Standalone function to compute idempotency key.
+    
+    Useful when you need to compute a key without a full policy.
+    """
+    key_data = {
+        "run_id": run_id,
+        "node_id": node_id,
+        "effect_type": effect.type.value,
+        "effect_payload": effect.payload,
+    }
+    key_json = json.dumps(key_data, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(key_json.encode()).hexdigest()[:32]