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

abstractruntime/__init__.py

@@ -32,8 +32,27 @@ from .core.policy import (
 from .storage.base import QueryableRunStore
 from .storage.in_memory import InMemoryLedgerStore, InMemoryRunStore
 from .storage.json_files import JsonFileRunStore, JsonlLedgerStore
+from .storage.sqlite import (
+    SqliteCommandCursorStore,
+    SqliteCommandStore,
+    SqliteDatabase,
+    SqliteLedgerStore,
+    SqliteRunStore,
+)
+from .storage.commands import (
+    CommandAppendResult,
+    CommandCursorStore,
+    CommandRecord,
+    CommandStore,
+    InMemoryCommandCursorStore,
+    InMemoryCommandStore,
+    JsonFileCommandCursorStore,
+    JsonlCommandStore,
+)
 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.offloading import OffloadingLedgerStore, OffloadingRunStore, offload_large_values
 from .storage.artifacts import (
     Artifact,
     ArtifactMetadata,
@@ -54,6 +73,29 @@ from .scheduler import (
     ScheduledRuntime,
     create_scheduled_runtime,
 )
+from .memory import ActiveContextPolicy, TimeRange
+from .workflow_bundle import (
+    WORKFLOW_BUNDLE_FORMAT_VERSION_V1,
+    InstalledWorkflowBundle,
+    WorkflowBundle,
+    WorkflowBundleEntrypoint,
+    WorkflowBundleError,
+    WorkflowBundleManifest,
+    WorkflowBundleRegistry,
+    WorkflowBundleRegistryError,
+    WorkflowEntrypointRef,
+    default_workflow_bundles_dir,
+    open_workflow_bundle,
+    sanitize_bundle_id,
+    sanitize_bundle_version,
+    workflow_bundle_manifest_from_dict,
+    workflow_bundle_manifest_to_dict,
+)
+from .history_bundle import (
+    RUN_HISTORY_BUNDLE_VERSION_V1,
+    export_run_history_bundle,
+    persist_workflow_snapshot,
+)
 
 __all__ = [
     # Core models
@@ -79,8 +121,26 @@ __all__ = [
     "InMemoryLedgerStore",
     "JsonFileRunStore",
     "JsonlLedgerStore",
+    "SqliteDatabase",
+    "SqliteRunStore",
+    "SqliteLedgerStore",
+    "CommandRecord",
+    "CommandAppendResult",
+    "CommandStore",
+    "CommandCursorStore",
+    "InMemoryCommandStore",
+    "JsonlCommandStore",
+    "InMemoryCommandCursorStore",
+    "JsonFileCommandCursorStore",
+    "SqliteCommandStore",
+    "SqliteCommandCursorStore",
     "HashChainedLedgerStore",
     "verify_ledger_chain",
+    "ObservableLedgerStore",
+    "ObservableLedgerStoreProtocol",
+    "OffloadingRunStore",
+    "OffloadingLedgerStore",
+    "offload_large_values",
     "Snapshot",
     "SnapshotStore",
     "InMemorySnapshotStore",
@@ -104,7 +164,27 @@ __all__ = [
     "RetryPolicy",
     "NoRetryPolicy",
     "compute_idempotency_key",
+    # Memory
+    "ActiveContextPolicy",
+    "TimeRange",
+    # WorkflowBundles (portable distribution unit)
+    "WORKFLOW_BUNDLE_FORMAT_VERSION_V1",
+    "WorkflowBundleError",
+    "WorkflowBundleEntrypoint",
+    "WorkflowBundleManifest",
+    "WorkflowBundle",
+    "InstalledWorkflowBundle",
+    "WorkflowBundleRegistry",
+    "WorkflowBundleRegistryError",
+    "WorkflowEntrypointRef",
+    "default_workflow_bundles_dir",
+    "sanitize_bundle_id",
+    "sanitize_bundle_version",
+    "workflow_bundle_manifest_from_dict",
+    "workflow_bundle_manifest_to_dict",
+    "open_workflow_bundle",
+    # Run history bundle (portable replay)
+    "RUN_HISTORY_BUNDLE_VERSION_V1",
+    "export_run_history_bundle",
+    "persist_workflow_snapshot",
 ]
-
-
-

abstractruntime/core/config.py

@@ -12,6 +12,13 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from typing import Any, Dict, Optional
 
+from .vars import DEFAULT_MAX_TOKENS
+
+# Truncation policy: keep mechanisms, but default to disabled.
+# A positive value enables a conservative auto-cap for `max_input_tokens` when callers do not
+# explicitly set an input budget. `-1` disables this cap (no automatic truncation).
+DEFAULT_RECOMMENDED_MAX_INPUT_TOKENS = -1
+
 
 @dataclass(frozen=True)
 class RuntimeConfig:
@@ -29,6 +36,8 @@ class RuntimeConfig:
         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:
@@ -45,11 +54,16 @@ class RuntimeConfig:
     # Token/context window management
     max_tokens: Optional[int] = None  # None = query from model capabilities
     max_output_tokens: Optional[int] = None  # None = use provider default
+    max_input_tokens: Optional[int] = None  # None = auto-calculate from max_tokens/max_output_tokens
     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)
 
@@ -60,14 +74,77 @@ class RuntimeConfig:
             Dict with canonical limit values for storage in RunState.vars["_limits"].
             Uses model_capabilities as fallback for max_tokens if not explicitly set.
         """
+        max_tokens = self.max_tokens
+        if max_tokens is None:
+            max_tokens = self.model_capabilities.get("max_tokens")
+        if max_tokens is None:
+            max_tokens = DEFAULT_MAX_TOKENS
+
+        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")
+        # If capabilities are unavailable and max_output_tokens is unset, keep it as None
+        # (meaning: provider default). Do not force a conservative output cap here.
+
+        # ADR-0008 alignment:
+        # - max_tokens: total context window size
+        # - max_output_tokens: output budget
+        # - max_input_tokens: explicit or derived input budget (may be smaller than max_tokens-max_output_tokens)
+        #
+        # Constraint: max_input_tokens + max_output_tokens + delta <= max_tokens
+        delta = 256
+        effective_max_input_tokens = self.max_input_tokens
+
+        try:
+            max_tokens_int = int(max_tokens) if max_tokens is not None else None
+        except Exception:
+            max_tokens_int = None
+        try:
+            max_output_int = int(max_output_tokens) if max_output_tokens is not None else None
+        except Exception:
+            max_output_int = None
+
+        if (
+            max_tokens_int is not None
+            and max_tokens_int > 0
+            and max_output_int is not None
+            and max_output_int >= 0
+            and effective_max_input_tokens is not None
+        ):
+            # If callers explicitly set max_input_tokens, clamp it to the context-window constraint.
+            max_allowed_in = max(0, int(max_tokens_int) - int(max_output_int) - int(delta))
+            try:
+                effective_max_input_tokens = int(effective_max_input_tokens)
+            except Exception:
+                effective_max_input_tokens = max_allowed_in
+            if effective_max_input_tokens < 0:
+                effective_max_input_tokens = 0
+            if effective_max_input_tokens > max_allowed_in:
+                effective_max_input_tokens = max_allowed_in
+
+        # Optional conservative auto-cap (disabled by default with -1).
+        if (
+            self.max_input_tokens is None
+            and effective_max_input_tokens is not None
+            and isinstance(DEFAULT_RECOMMENDED_MAX_INPUT_TOKENS, int)
+            and DEFAULT_RECOMMENDED_MAX_INPUT_TOKENS > 0
+        ):
+            try:
+                effective_max_input_tokens = min(int(effective_max_input_tokens), int(DEFAULT_RECOMMENDED_MAX_INPUT_TOKENS))
+            except Exception:
+                pass
+
         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,
+            "max_tokens": max_tokens,
+            "max_output_tokens": max_output_tokens,
+            "max_input_tokens": effective_max_input_tokens,
             "estimated_tokens_used": 0,
 
             # History management
@@ -95,7 +172,10 @@ class RuntimeConfig:
             warn_iterations_pct=self.warn_iterations_pct,
             max_tokens=self.max_tokens,
             max_output_tokens=self.max_output_tokens,
+            max_input_tokens=self.max_input_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,27 @@ 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"
+
+    # Semantic / KG memory (host-provided handlers)
+    MEMORY_KG_ASSERT = "memory_kg_assert"
+    MEMORY_KG_QUERY = "memory_kg_query"
+    MEMORY_KG_RESOLVE = "memory_kg_resolve"
+
+    # Debug / inspection (schema-only tools -> runtime effects)
+    VARS_QUERY = "vars_query"
 
     # Composition
     START_SUBWORKFLOW = "start_subworkflow"
@@ -279,4 +296,3 @@ class LimitWarning:
     def __post_init__(self) -> None:
         if self.maximum > 0:
             self.pct = round(self.current / self.maximum * 100, 1)
-

abstractruntime/core/policy.py

@@ -15,7 +15,76 @@ import json
 from dataclasses import dataclass
 from typing import Any, Dict, Optional, Protocol
 
-from .models import Effect, RunState
+from .models import Effect, EffectType, RunState
+
+
+def _loads_dict_like(value: Any) -> Optional[Dict[str, Any]]:
+    if value is None:
+        return None
+    if isinstance(value, dict):
+        return dict(value)
+    if not isinstance(value, str):
+        return None
+    text = value.strip()
+    if not text:
+        return None
+    try:
+        parsed = json.loads(text)
+    except Exception:
+        return None
+    return parsed if isinstance(parsed, dict) else None
+
+
+def _normalize_tool_call_for_idempotency(value: Any) -> Any:
+    if not isinstance(value, dict):
+        return value
+
+    out = dict(value)
+    # Provider/model-emitted IDs are not semantic; remove them from the idempotency hash.
+    for k in ("call_id", "id", "runtime_call_id", "model_call_id", "idempotency_key"):
+        out.pop(k, None)
+
+    name = out.get("name")
+    if isinstance(name, str):
+        out["name"] = name.strip()
+
+    args = out.get("arguments")
+    if isinstance(args, str):
+        parsed = _loads_dict_like(args)
+        out["arguments"] = parsed if isinstance(parsed, dict) else {}
+    elif not isinstance(args, dict):
+        out["arguments"] = {}
+
+    func = out.get("function")
+    if isinstance(func, dict):
+        # Some callers pass OpenAI-style shapes; preserve semantics, but strip IDs.
+        out["function"] = _normalize_tool_call_for_idempotency(func)
+
+    return out
+
+
+def _normalize_effect_payload_for_idempotency(effect: Effect) -> Dict[str, Any]:
+    if not isinstance(effect.payload, dict):
+        return {}
+    payload = dict(effect.payload)
+
+    if effect.type != EffectType.TOOL_CALLS:
+        return payload
+
+    tool_calls = payload.get("tool_calls")
+    if isinstance(tool_calls, list):
+        payload["tool_calls"] = [_normalize_tool_call_for_idempotency(tc) for tc in tool_calls]
+
+    allowed_tools = payload.get("allowed_tools")
+    if isinstance(allowed_tools, list):
+        uniq = {
+            str(t).strip()
+            for t in allowed_tools
+            if isinstance(t, str) and t.strip()
+        }
+        payload["allowed_tools"] = sorted(uniq)
+
+    return payload
 
 
 class EffectPolicy(Protocol):
@@ -110,11 +179,12 @@ class DefaultEffectPolicy:
         This ensures the same effect at the same point in the same run
         gets the same key, enabling deduplication on restart.
         """
+        normalized_payload = _normalize_effect_payload_for_idempotency(effect)
         key_data = {
             "run_id": run.run_id,
             "node_id": node_id,
             "effect_type": effect.type.value,
-            "effect_payload": effect.payload,
+            "effect_payload": normalized_payload,
         }
         key_json = json.dumps(key_data, sort_keys=True, separators=(",", ":"))
         return hashlib.sha256(key_json.encode()).hexdigest()[:32]
@@ -156,11 +226,12 @@ def compute_idempotency_key(
     
     Useful when you need to compute a key without a full policy.
     """
+    normalized_payload = _normalize_effect_payload_for_idempotency(effect)
     key_data = {
         "run_id": run_id,
         "node_id": node_id,
         "effect_type": effect.type.value,
-        "effect_payload": effect.payload,
+        "effect_payload": normalized_payload,
     }
     key_json = json.dumps(key_data, sort_keys=True, separators=(",", ":"))
     return hashlib.sha256(key_json.encode()).hexdigest()[:32]