AbstractRuntime 0.0.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

abstractruntime/__init__.py

@@ -33,6 +33,7 @@ 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.observable import ObservableLedgerStore, ObservableLedgerStoreProtocol
 from .storage.snapshots import Snapshot, SnapshotStore, InMemorySnapshotStore, JsonSnapshotStore
 from .storage.artifacts import (
     Artifact,
@@ -54,6 +55,7 @@ from .scheduler import (
     ScheduledRuntime,
     create_scheduled_runtime,
 )
+from .memory import ActiveContextPolicy, TimeRange
 
 __all__ = [
     # Core models
@@ -81,6 +83,8 @@ __all__ = [
     "JsonlLedgerStore",
     "HashChainedLedgerStore",
     "verify_ledger_chain",
+    "ObservableLedgerStore",
+    "ObservableLedgerStoreProtocol",
     "Snapshot",
     "SnapshotStore",
     "InMemorySnapshotStore",
@@ -104,7 +108,8 @@ __all__ = [
     "RetryPolicy",
     "NoRetryPolicy",
     "compute_idempotency_key",
+    # Memory
+    "ActiveContextPolicy",
+    "TimeRange",
 ]
 
-
-

abstractruntime/core/__init__.py

@@ -1,19 +1,26 @@
 """Core runtime primitives."""
 
-from .models import Effect, EffectType, RunState, RunStatus, StepPlan, WaitReason, WaitState
+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",
-    "Runtime",
+    "ensure_limits",
+    "get_limits",
 ]
 
 

abstractruntime/core/config.py

@@ -0,0 +1,114 @@
+"""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)
+        provider: Default provider id for this Runtime (best-effort; used for run metadata)
+        model: Default model id for this Runtime (best-effort; used for run metadata)
+        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)
+
+    # Default routing metadata (optional; depends on how the Runtime was constructed)
+    provider: Optional[str] = None
+    model: Optional[str] = None
+
+    # 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.
+        """
+        max_output_tokens = self.max_output_tokens
+        if max_output_tokens is None:
+            # Best-effort: persist the provider/model default so agent logic can reason about
+            # output-size constraints (e.g., chunk large tool arguments like file contents).
+            max_output_tokens = self.model_capabilities.get("max_output_tokens")
+        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": 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,
+            provider=self.provider,
+            model=self.model,
+            model_capabilities=capabilities,
+        )

abstractruntime/core/event_keys.py

@@ -0,0 +1,62 @@
+"""abstractruntime.core.event_keys
+
+Durable event key conventions.
+
+Why this exists:
+- `WAIT_EVENT` needs a stable `wait_key` that external hosts can compute.
+- Visual editors and other hosts (AbstractCode, servers) must agree on the same
+  key format without importing UI-specific code.
+
+We keep this module dependency-light (stdlib only).
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+def build_event_wait_key(
+    *,
+    scope: str,
+    name: str,
+    session_id: Optional[str] = None,
+    workflow_id: Optional[str] = None,
+    run_id: Optional[str] = None,
+) -> str:
+    """Build a durable wait_key for event-driven workflows.
+
+    Format:
+        evt:{scope}:{scope_id}:{name}
+
+    Scopes:
+    - session: `scope_id` is the workflow instance/session identifier (recommended default)
+    - workflow: `scope_id` is the workflow_id
+    - run: `scope_id` is the run_id
+    - global: `scope_id` is the literal string "global"
+    """
+    scope_norm = str(scope or "session").strip().lower()
+    name_norm = str(name or "").strip()
+    if not name_norm:
+        raise ValueError("event name is required")
+
+    scope_id: Optional[str]
+    if scope_norm == "session":
+        scope_id = str(session_id or "").strip() if session_id is not None else ""
+    elif scope_norm == "workflow":
+        scope_id = str(workflow_id or "").strip() if workflow_id is not None else ""
+    elif scope_norm == "run":
+        scope_id = str(run_id or "").strip() if run_id is not None else ""
+    elif scope_norm == "global":
+        scope_id = "global"
+    else:
+        raise ValueError(f"unknown event scope: {scope!r}")
+
+    if not scope_id:
+        raise ValueError(f"missing scope id for scope={scope_norm!r}")
+
+    return f"evt:{scope_norm}:{scope_id}:{name_norm}"
+
+
+
+
+

abstractruntime/core/models.py

@@ -46,10 +46,22 @@ class EffectType(str, Enum):
     WAIT_EVENT = "wait_event"
     WAIT_UNTIL = "wait_until"
     ASK_USER = "ask_user"
+    ANSWER_USER = "answer_user"
+
+    # Eventing
+    EMIT_EVENT = "emit_event"
 
     # Integrations (implemented via pluggable handlers)
     LLM_CALL = "llm_call"
     TOOL_CALLS = "tool_calls"
+    MEMORY_QUERY = "memory_query"
+    MEMORY_TAG = "memory_tag"
+    MEMORY_COMPACT = "memory_compact"
+    MEMORY_NOTE = "memory_note"
+    MEMORY_REHYDRATE = "memory_rehydrate"
+
+    # Debug / inspection (schema-only tools -> runtime effects)
+    VARS_QUERY = "vars_query"
 
     # Composition
     START_SUBWORKFLOW = "start_subworkflow"
@@ -130,10 +142,20 @@ class RunState:
 
     # 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, vars: Optional[Dict[str, Any]] = None, parent_run_id: Optional[str] = None) -> "RunState":
+    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,
@@ -141,6 +163,7 @@ class RunState:
             current_node=entry_node,
             vars=vars or {},
             actor_id=actor_id,
+            session_id=session_id,
             parent_run_id=parent_run_id,
         )
 
@@ -170,6 +193,7 @@ class StepRecord:
 
     # 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)
@@ -201,6 +225,7 @@ class StepRecord:
                 "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,
         )
@@ -237,3 +262,32 @@ class StepRecord:
         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)