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

abstractruntime/core/vars.py

@@ -0,0 +1,189 @@
+"""RunState.vars namespacing helpers.
+
+AbstractRuntime treats `RunState.vars` as JSON-serializable user/workflow state.
+To avoid key collisions and to clarify ownership, we use a simple convention:
+
+- `context`: user-facing context (task, conversation, inputs)
+- `scratchpad`: agent/workflow working memory (iteration counters, plans)
+- `_runtime`: runtime/host-managed metadata (tool specs, inbox, etc.)
+- `_temp`: ephemeral step-to-step values (llm_response, tool_results, etc.)
+- `_limits`: runtime resource limits (max_iterations, max_tokens, etc.)
+
+This is a convention, not a strict schema; helpers here are intentionally small.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+CONTEXT = "context"
+SCRATCHPAD = "scratchpad"
+RUNTIME = "_runtime"
+TEMP = "_temp"
+LIMITS = "_limits"  # Canonical storage for runtime resource limits
+NODE_TRACES = "node_traces"  # _runtime namespace key for per-node execution traces
+
+
+def ensure_namespaces(vars: Dict[str, Any]) -> Dict[str, Any]:
+    """Ensure the four canonical namespaces exist and are dicts."""
+    for key in (CONTEXT, SCRATCHPAD, RUNTIME, TEMP):
+        current = vars.get(key)
+        if not isinstance(current, dict):
+            vars[key] = {}
+    return vars
+
+
+def get_namespace(vars: Dict[str, Any], key: str) -> Dict[str, Any]:
+    ensure_namespaces(vars)
+    return vars[key]  # type: ignore[return-value]
+
+
+def get_context(vars: Dict[str, Any]) -> Dict[str, Any]:
+    return get_namespace(vars, CONTEXT)
+
+
+def get_scratchpad(vars: Dict[str, Any]) -> Dict[str, Any]:
+    return get_namespace(vars, SCRATCHPAD)
+
+
+def get_runtime(vars: Dict[str, Any]) -> Dict[str, Any]:
+    return get_namespace(vars, RUNTIME)
+
+
+def get_temp(vars: Dict[str, Any]) -> Dict[str, Any]:
+    return get_namespace(vars, TEMP)
+
+
+def clear_temp(vars: Dict[str, Any]) -> None:
+    get_temp(vars).clear()
+
+
+def get_limits(vars: Dict[str, Any]) -> Dict[str, Any]:
+    """Get the _limits namespace, creating with defaults if missing."""
+    if LIMITS not in vars or not isinstance(vars.get(LIMITS), dict):
+        vars[LIMITS] = _default_limits()
+    return vars[LIMITS]  # type: ignore[return-value]
+
+
+def ensure_limits(vars: Dict[str, Any]) -> Dict[str, Any]:
+    """Ensure _limits namespace exists with defaults.
+
+    This is the canonical location for runtime resource limits:
+    - max_iterations / current_iteration: Iteration control
+    - max_tokens / estimated_tokens_used: Token/context window management
+    - max_history_messages: Conversation history limit (-1 = unlimited)
+    - warn_*_pct: Warning thresholds for proactive notifications
+
+    Returns:
+        The _limits dict (mutable reference into vars)
+    """
+    return get_limits(vars)
+
+
+def get_node_traces(vars: Dict[str, Any]) -> Dict[str, Any]:
+    """Return the runtime-owned per-node trace mapping.
+
+    Stored under `run.vars["_runtime"]["node_traces"]`.
+    This is intended for host UX/debugging and for exposing traces to higher layers.
+    """
+    runtime_ns = get_runtime(vars)
+    traces = runtime_ns.get(NODE_TRACES)
+    if not isinstance(traces, dict):
+        traces = {}
+        runtime_ns[NODE_TRACES] = traces
+    return traces
+
+
+def get_node_trace(vars: Dict[str, Any], node_id: str) -> Dict[str, Any]:
+    """Return a single node trace object (always a dict)."""
+    traces = get_node_traces(vars)
+    trace = traces.get(node_id)
+    if isinstance(trace, dict):
+        return trace
+    return {"node_id": node_id, "steps": []}
+
+
+def _default_limits() -> Dict[str, Any]:
+    """Return default limits dict."""
+    return {
+        "max_iterations": 25,
+        "current_iteration": 0,
+        "max_tokens": 32768,
+        "max_output_tokens": None,
+        "max_history_messages": -1,
+        "estimated_tokens_used": 0,
+        "warn_iterations_pct": 80,
+        "warn_tokens_pct": 80,
+    }
+
+
+def parse_vars_path(path: str) -> list[Any]:
+    """Parse a path for inspecting `RunState.vars`.
+
+    Supports:
+      - dot paths: "scratchpad.research.sources[0].title"
+      - JSON pointer-ish paths: "/scratchpad/research/sources/0/title"
+    """
+    import re
+
+    raw = str(path or "").strip()
+    if not raw:
+        return []
+
+    tokens: list[Any] = []
+
+    if raw.startswith("/"):
+        for part in [p for p in raw.split("/") if p]:
+            part = part.replace("~1", "/").replace("~0", "~")
+            if part.isdigit():
+                tokens.append(int(part))
+            else:
+                tokens.append(part)
+        return tokens
+
+    for part in [p for p in raw.split(".") if p]:
+        # Allow list indexing as a bare segment: `foo.0.bar`
+        if "[" not in part and part.isdigit():
+            tokens.append(int(part))
+            continue
+
+        # Split `foo[0][1]` into ["foo", 0, 1]
+        for m in re.finditer(r"([^\[\]]+)|\[(\d+)\]", part):
+            key = m.group(1)
+            idx = m.group(2)
+            if key is not None:
+                tokens.append(key)
+            elif idx is not None:
+                tokens.append(int(idx))
+
+    return tokens
+
+
+def resolve_vars_path(root: Any, tokens: list[Any]) -> Any:
+    """Resolve tokens against nested dict/list structures."""
+    cur: Any = root
+    at: list[str] = []
+
+    for tok in tokens:
+        if isinstance(tok, int):
+            if not isinstance(cur, list):
+                where = ".".join([p for p in at if p]) or "(root)"
+                raise ValueError(f"Expected list at {where} but found {type(cur).__name__}")
+            if tok < 0 or tok >= len(cur):
+                where = ".".join([p for p in at if p]) or "(root)"
+                raise ValueError(f"Index {tok} out of range at {where} (len={len(cur)})")
+            cur = cur[tok]
+            at.append(str(tok))
+            continue
+
+        key = str(tok)
+        if not isinstance(cur, dict):
+            where = ".".join([p for p in at if p]) or "(root)"
+            raise ValueError(f"Expected object at {where} but found {type(cur).__name__}")
+        if key not in cur:
+            where = ".".join([p for p in at if p]) or "(root)"
+            raise ValueError(f"Missing key '{key}' at {where}")
+        cur = cur[key]
+        at.append(key)
+
+    return cur

abstractruntime/evidence/__init__.py

@@ -0,0 +1,10 @@
+"""abstractruntime.evidence
+
+Runtime-owned evidence capture and indexing.
+"""
+
+from .recorder import EvidenceRecorder, DEFAULT_EVIDENCE_TOOL_NAMES
+
+__all__ = ["EvidenceRecorder", "DEFAULT_EVIDENCE_TOOL_NAMES"]
+
+

abstractruntime/evidence/recorder.py

@@ -0,0 +1,325 @@
+"""abstractruntime.evidence.recorder
+
+Evidence is "provenance-first": a durable record of what the system actually observed at
+external boundaries (web + process execution), stored as artifacts with a small JSON index
+in run state.
+
+Design goals:
+- Always-on capture for a small default set of tools (web_search/fetch_url/execute_command).
+- Keep RunState.vars JSON-safe and bounded: store large payloads in ArtifactStore and keep refs.
+- Make later indexing/storage upgrades possible (Elastic/vector/etc) without changing semantics.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Sequence
+
+from ..core.models import RunState
+from ..storage.artifacts import ArtifactStore, artifact_ref, is_artifact_ref
+
+
+DEFAULT_EVIDENCE_TOOL_NAMES: tuple[str, ...] = ("web_search", "fetch_url", "execute_command")
+
+
+def utc_now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _ensure_memory_spans(run: RunState) -> list[dict[str, Any]]:
+    runtime_ns = run.vars.get("_runtime")
+    if not isinstance(runtime_ns, dict):
+        runtime_ns = {}
+        run.vars["_runtime"] = runtime_ns
+    spans = runtime_ns.get("memory_spans")
+    if not isinstance(spans, list):
+        spans = []
+        runtime_ns["memory_spans"] = spans
+    return spans
+
+
+def _preview(text: str, *, limit: int = 160) -> str:
+    s = str(text or "").strip()
+    if len(s) <= limit:
+        return s
+    return s[: max(0, limit - 1)] + "…"
+
+
+def _json_loads_maybe(text: str) -> Optional[Any]:
+    if not isinstance(text, str):
+        return None
+    t = text.strip()
+    if not t:
+        return None
+    if not (t.startswith("{") or t.startswith("[")):
+        return None
+    try:
+        return json.loads(t)
+    except Exception:
+        return None
+
+
+def _store_text(
+    store: ArtifactStore,
+    *,
+    text: str,
+    run_id: str,
+    tags: Dict[str, str],
+    content_type: str = "text/plain",
+) -> Optional[Dict[str, str]]:
+    s = str(text or "")
+    if not s:
+        return None
+    meta = store.store_text(s, content_type=content_type, run_id=run_id, tags=tags)
+    return artifact_ref(meta.artifact_id)
+
+
+def _store_json(
+    store: ArtifactStore,
+    *,
+    data: Any,
+    run_id: str,
+    tags: Dict[str, str],
+) -> Optional[Dict[str, str]]:
+    if data is None:
+        return None
+    meta = store.store_json(data, run_id=run_id, tags=tags)
+    return artifact_ref(meta.artifact_id)
+
+
+@dataclass(frozen=True)
+class EvidenceCaptureStats:
+    recorded: int = 0
+
+
+class EvidenceRecorder:
+    """Runtime-side recorder for always-on evidence."""
+
+    def __init__(
+        self,
+        *,
+        artifact_store: ArtifactStore,
+        tool_names: Sequence[str] = DEFAULT_EVIDENCE_TOOL_NAMES,
+    ):
+        self._store = artifact_store
+        self._tool_names = {str(n).strip() for n in tool_names if isinstance(n, str) and n.strip()}
+
+    def record_tool_calls(
+        self,
+        *,
+        run: RunState,
+        node_id: str,
+        tool_calls: list[Any],
+        tool_results: Dict[str, Any],
+    ) -> EvidenceCaptureStats:
+        if not isinstance(tool_results, dict):
+            return EvidenceCaptureStats(recorded=0)
+        results = tool_results.get("results", [])
+        if not isinstance(results, list) or not results:
+            return EvidenceCaptureStats(recorded=0)
+        if not isinstance(tool_calls, list):
+            tool_calls = []
+
+        spans = _ensure_memory_spans(run)
+        recorded = 0
+
+        for idx, r in enumerate(results):
+            if not isinstance(r, dict):
+                continue
+            call = tool_calls[idx] if idx < len(tool_calls) and isinstance(tool_calls[idx], dict) else {}
+            tool_name = str(r.get("name") or call.get("name") or "").strip()
+            if not tool_name or tool_name not in self._tool_names:
+                continue
+
+            ok = bool(r.get("success") is True)
+            call_id = str(r.get("call_id") or call.get("call_id") or "")
+            error = r.get("error")
+            error_text = str(error).strip() if isinstance(error, str) and error.strip() else None
+            args = call.get("arguments") if isinstance(call, dict) else None
+            args_dict = dict(args) if isinstance(args, dict) else {}
+
+            output = r.get("output")
+            # Tool executors vary: output may be str/dict/None.
+            output_dict = dict(output) if isinstance(output, dict) else None
+            output_text = str(output or "") if isinstance(output, str) else None
+
+            created_at = utc_now_iso()
+            tags: Dict[str, str] = {"kind": "evidence", "tool": tool_name}
+
+            evidence_payload: Dict[str, Any] = {
+                "tool_name": tool_name,
+                "call_id": call_id,
+                "success": ok,
+                "error": error_text,
+                "created_at": created_at,
+                "run_id": run.run_id,
+                "workflow_id": run.workflow_id,
+                "node_id": node_id,
+                "arguments": args_dict,
+            }
+            if run.actor_id:
+                evidence_payload["actor_id"] = str(run.actor_id)
+            if getattr(run, "session_id", None):
+                evidence_payload["session_id"] = str(run.session_id)
+
+            artifacts: Dict[str, Any] = {}
+
+            if tool_name == "fetch_url":
+                url = str(args_dict.get("url") or "")
+                if url:
+                    tags["url"] = url[:200]
+
+                if isinstance(output_dict, dict):
+                    # Store and strip large text fields from the tool output dict.
+                    raw_text = output_dict.pop("raw_text", None)
+                    norm_text = output_dict.pop("normalized_text", None)
+                    content_type = output_dict.get("content_type")
+                    content_type_str = str(content_type) if isinstance(content_type, str) else ""
+
+                    raw_ref = None
+                    if isinstance(raw_text, str) and raw_text:
+                        raw_ref = _store_text(
+                            self._store,
+                            text=raw_text,
+                            run_id=run.run_id,
+                            tags={**tags, "part": "raw"},
+                            content_type=content_type_str or "text/plain",
+                        )
+                        output_dict["raw_artifact"] = raw_ref
+                        artifacts["raw"] = raw_ref
+
+                    norm_ref = None
+                    if isinstance(norm_text, str) and norm_text:
+                        norm_ref = _store_text(
+                            self._store,
+                            text=norm_text,
+                            run_id=run.run_id,
+                            tags={**tags, "part": "normalized"},
+                            content_type="text/plain",
+                        )
+                        output_dict["normalized_artifact"] = norm_ref
+                        artifacts["normalized_text"] = norm_ref
+
+                    evidence_payload["url"] = str(output_dict.get("url") or url)
+                    evidence_payload["final_url"] = str(output_dict.get("final_url") or "")
+                    evidence_payload["content_type"] = content_type_str
+                    evidence_payload["size_bytes"] = output_dict.get("size_bytes")
+                    if artifacts:
+                        evidence_payload["artifacts"] = artifacts
+
+                    # Write back the stripped/augmented dict into the tool result so run state stays small.
+                    r["output"] = output_dict
+
+            elif tool_name == "execute_command":
+                cmd = str(args_dict.get("command") or "")
+                if cmd:
+                    tags["command"] = _preview(cmd, limit=200)
+
+                if isinstance(output_dict, dict):
+                    stdout = output_dict.pop("stdout", None)
+                    stderr = output_dict.pop("stderr", None)
+
+                    stdout_ref = None
+                    if isinstance(stdout, str) and stdout:
+                        stdout_ref = _store_text(
+                            self._store,
+                            text=stdout,
+                            run_id=run.run_id,
+                            tags={**tags, "part": "stdout"},
+                        )
+                        output_dict["stdout_artifact"] = stdout_ref
+                        artifacts["stdout"] = stdout_ref
+
+                    stderr_ref = None
+                    if isinstance(stderr, str) and stderr:
+                        stderr_ref = _store_text(
+                            self._store,
+                            text=stderr,
+                            run_id=run.run_id,
+                            tags={**tags, "part": "stderr"},
+                        )
+                        output_dict["stderr_artifact"] = stderr_ref
+                        artifacts["stderr"] = stderr_ref
+
+                    evidence_payload["command"] = str(output_dict.get("command") or cmd)
+                    evidence_payload["return_code"] = output_dict.get("return_code")
+                    evidence_payload["duration_s"] = output_dict.get("duration_s")
+                    evidence_payload["working_directory"] = output_dict.get("working_directory")
+                    evidence_payload["platform"] = output_dict.get("platform")
+                    if artifacts:
+                        evidence_payload["artifacts"] = artifacts
+
+                    r["output"] = output_dict
+
+                elif isinstance(output_text, str) and output_text:
+                    out_ref = _store_text(
+                        self._store,
+                        text=output_text,
+                        run_id=run.run_id,
+                        tags={**tags, "part": "output"},
+                    )
+                    if out_ref is not None:
+                        artifacts["output"] = out_ref
+                        evidence_payload["artifacts"] = artifacts
+
+            elif tool_name == "web_search":
+                query = str(args_dict.get("query") or "")
+                if query:
+                    tags["query"] = _preview(query, limit=200)
+                    evidence_payload["query"] = query
+
+                if isinstance(output_text, str) and output_text:
+                    parsed = _json_loads_maybe(output_text)
+                    if parsed is not None:
+                        out_ref = _store_json(self._store, data=parsed, run_id=run.run_id, tags={**tags, "part": "results"})
+                    else:
+                        out_ref = _store_text(self._store, text=output_text, run_id=run.run_id, tags={**tags, "part": "results"})
+                    if out_ref is not None:
+                        artifacts["results"] = out_ref
+                        evidence_payload["artifacts"] = artifacts
+                elif isinstance(output_dict, dict):
+                    out_ref = _store_json(self._store, data=output_dict, run_id=run.run_id, tags={**tags, "part": "results"})
+                    if out_ref is not None:
+                        artifacts["results"] = out_ref
+                        evidence_payload["artifacts"] = artifacts
+
+            # Store the evidence record itself (small JSON with artifact refs).
+            record_ref = _store_json(self._store, data=evidence_payload, run_id=run.run_id, tags=tags)
+            if not (isinstance(record_ref, dict) and is_artifact_ref(record_ref)):
+                continue
+            evidence_id = record_ref["$artifact"]
+
+            # Append to span-like index for fast listing.
+            span_record: Dict[str, Any] = {
+                "kind": "evidence",
+                "artifact_id": evidence_id,
+                "created_at": created_at,
+                "from_timestamp": created_at,
+                "to_timestamp": created_at,
+                "message_count": 0,
+                "tool_name": tool_name,
+                "call_id": call_id,
+                "success": ok,
+            }
+            if tool_name == "fetch_url":
+                span_record["url"] = evidence_payload.get("url") or str(args_dict.get("url") or "")
+            elif tool_name == "web_search":
+                span_record["query"] = str(args_dict.get("query") or "")
+            elif tool_name == "execute_command":
+                span_record["command_preview"] = _preview(str(args_dict.get("command") or ""))
+
+            # Attach span id back to the tool result entry for easy linking in traces/UIs.
+            meta = r.get("meta")
+            if not isinstance(meta, dict):
+                meta = {}
+                r["meta"] = meta
+            meta["evidence_id"] = evidence_id
+
+            spans.append(span_record)
+            recorded += 1
+
+        return EvidenceCaptureStats(recorded=recorded)
+
+

abstractruntime/integrations/abstractcore/__init__.py

@@ -7,16 +7,18 @@ Provides:
 - Tool executors (executed + passthrough)
 - Effect handlers wiring
 - Convenience runtime factories for local/remote/hybrid modes
+- RuntimeConfig for limits and model capabilities
 
 Importing this module is the explicit opt-in to an AbstractCore dependency.
 """
 
+from ...core.config import RuntimeConfig
 from .llm_client import (
     AbstractCoreLLMClient,
     LocalAbstractCoreLLMClient,
     RemoteAbstractCoreLLMClient,
 )
-from .tool_executor import AbstractCoreToolExecutor, PassthroughToolExecutor, ToolExecutor
+from .tool_executor import AbstractCoreToolExecutor, MappingToolExecutor, PassthroughToolExecutor, ToolExecutor
 from .effect_handlers import build_effect_handlers
 from .factory import (
     create_hybrid_runtime,
@@ -25,19 +27,24 @@ from .factory import (
     create_remote_file_runtime,
     create_remote_runtime,
 )
+from .observability import attach_global_event_bus_bridge, emit_step_record
 
 __all__ = [
     "AbstractCoreLLMClient",
     "LocalAbstractCoreLLMClient",
     "RemoteAbstractCoreLLMClient",
+    "RuntimeConfig",
     "ToolExecutor",
+    "MappingToolExecutor",
     "AbstractCoreToolExecutor",
     "PassthroughToolExecutor",
+
     "build_effect_handlers",
     "create_local_runtime",
     "create_remote_runtime",
     "create_hybrid_runtime",
     "create_local_file_runtime",
     "create_remote_file_runtime",
+    "attach_global_event_bus_bridge",
+    "emit_step_record",
 ]
-

abstractruntime/integrations/abstractcore/constants.py

@@ -0,0 +1,19 @@
+"""abstractruntime.integrations.abstractcore.constants
+
+Single source of truth for AbstractRuntime orchestration defaults when it
+executes AbstractCore-backed effects (LLM calls and tool calls).
+"""
+
+# Default *effect* timeouts (seconds).
+#
+# IMPORTANT: These are NOT a "workflow/run TTL". Workflows can be long-lived
+# (hours/days) or even continuous. These limits only apply to a *single*
+# runtime-managed operation (e.g. one LLM HTTP request, one tool call).
+#
+# Rationale:
+# - Local inference can be slow for large contexts.
+# - In an orchestrator, timeouts are policy and should be explicit + consistent.
+DEFAULT_LLM_TIMEOUT_S: float = 7200.0
+DEFAULT_TOOL_TIMEOUT_S: float = 7200.0
+
+