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

abstractruntime/core/spec.py

@@ -0,0 +1,53 @@
+"""abstractruntime.core.spec
+
+Workflow specification and node contract.
+
+In v0.1 we keep the spec simple:
+- The workflow is a graph: nodes identified by string IDs.
+- Nodes are implemented as Python callables (handlers).
+- This kernel does not define a UI DSL; AbstractFlow can produce specs.
+
+Durability note:
+- We persist *RunState* and a *ledger*.
+- We assume the workflow spec + node handlers are available at resume time.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Dict, Optional, Protocol
+
+from .models import RunState, StepPlan
+
+
+class RunContext(Protocol):
+    """Dependency injection surface for node handlers.
+
+    This is intentionally small and can be extended later.
+    """
+
+    def now_iso(self) -> str: ...
+
+
+NodeHandler = Callable[[RunState, RunContext], StepPlan]
+
+
+@dataclass(frozen=True)
+class WorkflowSpec:
+    workflow_id: str
+    entry_node: str
+    nodes: Dict[str, NodeHandler]
+
+    def get_node(self, node_id: str) -> NodeHandler:
+        if node_id not in self.nodes:
+            raise KeyError(f"Unknown node_id '{node_id}' in workflow '{self.workflow_id}'")
+        return self.nodes[node_id]
+
+    def is_terminal(self, node_id: str) -> bool:
+        """A workflow is terminal when the node returns StepPlan.complete_output.
+
+        The runtime decides termination based on StepPlan, not a dedicated node type.
+        """
+
+        return False  # evaluated at runtime
+

abstractruntime/core/vars.py

@@ -0,0 +1,94 @@
+"""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
+
+
+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 _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,
+    }
+

abstractruntime/identity/__init__.py

@@ -0,0 +1,7 @@
+"""Identity and provenance primitives."""
+
+from .fingerprint import ActorFingerprint
+
+__all__ = ["ActorFingerprint"]
+
+

abstractruntime/identity/fingerprint.py

@@ -0,0 +1,57 @@
+"""abstractruntime.identity.fingerprint
+
+AI fingerprint / provenance (v0.1 - data model + hashing only).
+
+Important:
+- This does NOT implement cryptographic signatures yet (no non-forgeability).
+- It provides a stable, deterministic *identifier* given stable inputs.
+
+Backlog item will define:
+- keypair-based identity (public key) and signing of ledger chains.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, asdict
+from typing import Any, Dict, Optional
+
+
+def _canonical_json(data: Dict[str, Any]) -> str:
+    return json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def sha256_hex(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+@dataclass(frozen=True)
+class ActorFingerprint:
+    """A stable identifier for an actor (agent/service/human).
+
+    This is intentionally minimal. For accountability you typically want:
+    - stable actor id
+    - metadata about the owner/org
+    - (future) signature key to make logs tamper-evident
+    """
+
+    actor_id: str
+    kind: str  # "agent" | "human" | "service"
+    display_name: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+    @classmethod
+    def from_metadata(cls, *, kind: str, display_name: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None) -> "ActorFingerprint":
+        payload = {
+            "kind": kind,
+            "display_name": display_name,
+            "metadata": metadata or {},
+        }
+        actor_id = f"ar_{sha256_hex(_canonical_json(payload))[:24]}"
+        return cls(actor_id=actor_id, kind=kind, display_name=display_name, metadata=metadata or {})
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+

abstractruntime/integrations/__init__.py

@@ -0,0 +1,11 @@
+"""abstractruntime.integrations
+
+Integration modules live here.
+
+Design rule (layered coupling):
+- The **kernel** (`abstractruntime.core`, `abstractruntime.storage`, `abstractruntime.identity`) stays dependency-light.
+- Optional integration packages may import heavier dependencies (e.g. AbstractCore) and provide effect handlers.
+
+This package intentionally does not import any integration by default.
+"""
+

abstractruntime/integrations/abstractcore/__init__.py

@@ -0,0 +1,47 @@
+"""abstractruntime.integrations.abstractcore
+
+AbstractCore integration package.
+
+Provides:
+- LLM clients (local + remote)
+- 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, MappingToolExecutor, PassthroughToolExecutor, ToolExecutor
+from .effect_handlers import build_effect_handlers
+from .factory import (
+    create_hybrid_runtime,
+    create_local_file_runtime,
+    create_local_runtime,
+    create_remote_file_runtime,
+    create_remote_runtime,
+)
+
+__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",
+]

abstractruntime/integrations/abstractcore/effect_handlers.py

@@ -0,0 +1,119 @@
+"""abstractruntime.integrations.abstractcore.effect_handlers
+
+Effect handlers wiring for AbstractRuntime.
+
+These handlers implement:
+- `EffectType.LLM_CALL`
+- `EffectType.TOOL_CALLS`
+
+They are designed to keep `RunState.vars` JSON-safe.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from ...core.models import Effect, EffectType, RunState, WaitReason, WaitState
+from ...core.runtime import EffectOutcome, EffectHandler
+from .llm_client import AbstractCoreLLMClient
+from .tool_executor import ToolExecutor
+from .logging import get_logger
+
+logger = get_logger(__name__)
+
+
+def _trace_context(run: RunState) -> Dict[str, str]:
+    ctx: Dict[str, str] = {"run_id": run.run_id}
+    if run.actor_id:
+        ctx["actor_id"] = str(run.actor_id)
+    session_id = getattr(run, "session_id", None)
+    if session_id:
+        ctx["session_id"] = str(session_id)
+    if run.parent_run_id:
+        ctx["parent_run_id"] = str(run.parent_run_id)
+    return ctx
+
+
+def make_llm_call_handler(*, llm: AbstractCoreLLMClient) -> EffectHandler:
+    def _handler(run: RunState, effect: Effect, default_next_node: Optional[str]) -> EffectOutcome:
+        payload = dict(effect.payload or {})
+        prompt = payload.get("prompt")
+        messages = payload.get("messages")
+        system_prompt = payload.get("system_prompt")
+        tools = payload.get("tools")
+        raw_params = payload.get("params")
+        params = dict(raw_params) if isinstance(raw_params, dict) else {}
+
+        # Propagate durable trace context into AbstractCore calls.
+        trace_metadata = params.get("trace_metadata")
+        if not isinstance(trace_metadata, dict):
+            trace_metadata = {}
+        trace_metadata.update(_trace_context(run))
+        params["trace_metadata"] = trace_metadata
+
+        if not prompt and not messages:
+            return EffectOutcome.failed("llm_call requires payload.prompt or payload.messages")
+
+        try:
+            result = llm.generate(
+                prompt=str(prompt or ""),
+                messages=messages,
+                system_prompt=system_prompt,
+                tools=tools,
+                params=params,
+            )
+            return EffectOutcome.completed(result=result)
+        except Exception as e:
+            logger.error("LLM_CALL failed", error=str(e))
+            return EffectOutcome.failed(str(e))
+
+    return _handler
+
+
+def make_tool_calls_handler(*, tools: Optional[ToolExecutor] = None) -> EffectHandler:
+    """Create a TOOL_CALLS effect handler.
+
+    Tool execution is performed exclusively via the host-configured ToolExecutor.
+    This keeps `RunState.vars` and ledger payloads JSON-safe (durable execution).
+    """
+    def _handler(run: RunState, effect: Effect, default_next_node: Optional[str]) -> EffectOutcome:
+        payload = dict(effect.payload or {})
+        tool_calls = payload.get("tool_calls")
+        if not isinstance(tool_calls, list):
+            return EffectOutcome.failed("tool_calls requires payload.tool_calls (list)")
+
+        if tools is None:
+            return EffectOutcome.failed(
+                "TOOL_CALLS requires a ToolExecutor; configure Runtime with "
+                "MappingToolExecutor/AbstractCoreToolExecutor/PassthroughToolExecutor."
+            )
+
+        try:
+            result = tools.execute(tool_calls=tool_calls)
+        except Exception as e:
+            logger.error("TOOL_CALLS execution failed", error=str(e))
+            return EffectOutcome.failed(str(e))
+
+        mode = result.get("mode")
+        if mode and mode != "executed":
+            # Passthrough/untrusted mode: pause until an external host resumes with tool results.
+            wait_key = payload.get("wait_key") or f"tool_calls:{run.run_id}:{run.current_node}"
+            wait = WaitState(
+                reason=WaitReason.EVENT,
+                wait_key=str(wait_key),
+                resume_to_node=payload.get("resume_to_node") or default_next_node,
+                result_key=effect.result_key,
+                details={"mode": mode, "tool_calls": tool_calls},
+            )
+            return EffectOutcome.waiting(wait)
+
+        return EffectOutcome.completed(result=result)
+
+    return _handler
+
+
+def build_effect_handlers(*, llm: AbstractCoreLLMClient, tools: ToolExecutor = None) -> Dict[EffectType, Any]:
+    return {
+        EffectType.LLM_CALL: make_llm_call_handler(llm=llm),
+        EffectType.TOOL_CALLS: make_tool_calls_handler(tools=tools),
+    }

abstractruntime/integrations/abstractcore/factory.py

@@ -0,0 +1,187 @@
+"""abstractruntime.integrations.abstractcore.factory
+
+Convenience constructors for a Runtime wired to AbstractCore.
+
+These helpers implement the three supported execution modes:
+- local: in-process LLM + local tool execution
+- remote: HTTP to AbstractCore server + tool passthrough
+- hybrid: HTTP to AbstractCore server + local tool execution
+
+The caller supplies storage backends (in-memory or file-based).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from ...core.config import RuntimeConfig
+from ...core.runtime import Runtime
+from ...storage.in_memory import InMemoryLedgerStore, InMemoryRunStore
+from ...storage.json_files import JsonFileRunStore, JsonlLedgerStore
+from ...storage.base import LedgerStore, RunStore
+
+from .effect_handlers import build_effect_handlers
+from .llm_client import LocalAbstractCoreLLMClient, RemoteAbstractCoreLLMClient
+from .tool_executor import AbstractCoreToolExecutor, PassthroughToolExecutor, ToolExecutor
+
+
+def _default_in_memory_stores() -> tuple[RunStore, LedgerStore]:
+    return InMemoryRunStore(), InMemoryLedgerStore()
+
+
+def _default_file_stores(*, base_dir: str | Path) -> tuple[RunStore, LedgerStore]:
+    base = Path(base_dir)
+    base.mkdir(parents=True, exist_ok=True)
+    return JsonFileRunStore(base), JsonlLedgerStore(base)
+
+
+def create_local_runtime(
+    *,
+    provider: str,
+    model: str,
+    llm_kwargs: Optional[Dict[str, Any]] = None,
+    run_store: Optional[RunStore] = None,
+    ledger_store: Optional[LedgerStore] = None,
+    tool_executor: Optional[ToolExecutor] = None,
+    context: Optional[Any] = None,
+    effect_policy: Optional[Any] = None,
+    config: Optional[RuntimeConfig] = None,
+) -> Runtime:
+    """Create a runtime with local LLM execution via AbstractCore.
+
+    Args:
+        provider: LLM provider (e.g., "ollama", "openai")
+        model: Model name
+        llm_kwargs: Additional kwargs for LLM client
+        run_store: Storage for run state (default: in-memory)
+        ledger_store: Storage for ledger (default: in-memory)
+        tool_executor: Optional custom tool executor. If not provided, defaults
+            to `AbstractCoreToolExecutor()` (AbstractCore global tool registry).
+        context: Optional context object
+        effect_policy: Optional effect policy (retry, etc.)
+        config: Optional RuntimeConfig for limits and model capabilities.
+            If not provided, model capabilities are queried from the LLM client.
+
+    Note:
+        For durable execution, tool callables should never be stored in `RunState.vars`
+        or passed in effect payloads. Prefer `MappingToolExecutor.from_tools([...])`.
+    """
+    if run_store is None or ledger_store is None:
+        run_store, ledger_store = _default_in_memory_stores()
+
+    llm_client = LocalAbstractCoreLLMClient(provider=provider, model=model, llm_kwargs=llm_kwargs)
+    tools = tool_executor or AbstractCoreToolExecutor()
+    handlers = build_effect_handlers(llm=llm_client, tools=tools)
+
+    # Query model capabilities and merge into config
+    capabilities = llm_client.get_model_capabilities()
+    if config is None:
+        config = RuntimeConfig(model_capabilities=capabilities)
+    else:
+        # Merge capabilities into provided config
+        config = config.with_capabilities(capabilities)
+
+    return Runtime(
+        run_store=run_store,
+        ledger_store=ledger_store,
+        effect_handlers=handlers,
+        context=context,
+        effect_policy=effect_policy,
+        config=config,
+    )
+
+
+def create_remote_runtime(
+    *,
+    server_base_url: str,
+    model: str,
+    headers: Optional[Dict[str, str]] = None,
+    timeout_s: float = 60.0,
+    run_store: Optional[RunStore] = None,
+    ledger_store: Optional[LedgerStore] = None,
+    tool_executor: Optional[ToolExecutor] = None,
+    context: Optional[Any] = None,
+) -> Runtime:
+    if run_store is None or ledger_store is None:
+        run_store, ledger_store = _default_in_memory_stores()
+
+    llm_client = RemoteAbstractCoreLLMClient(
+        server_base_url=server_base_url,
+        model=model,
+        headers=headers,
+        timeout_s=timeout_s,
+    )
+    tools = tool_executor or PassthroughToolExecutor()
+    handlers = build_effect_handlers(llm=llm_client, tools=tools)
+
+    return Runtime(run_store=run_store, ledger_store=ledger_store, effect_handlers=handlers, context=context)
+
+
+def create_hybrid_runtime(
+    *,
+    server_base_url: str,
+    model: str,
+    headers: Optional[Dict[str, str]] = None,
+    timeout_s: float = 60.0,
+    run_store: Optional[RunStore] = None,
+    ledger_store: Optional[LedgerStore] = None,
+    context: Optional[Any] = None,
+) -> Runtime:
+    """Remote LLM via AbstractCore server, local tool execution."""
+
+    if run_store is None or ledger_store is None:
+        run_store, ledger_store = _default_in_memory_stores()
+
+    llm_client = RemoteAbstractCoreLLMClient(
+        server_base_url=server_base_url,
+        model=model,
+        headers=headers,
+        timeout_s=timeout_s,
+    )
+    tools = AbstractCoreToolExecutor()
+    handlers = build_effect_handlers(llm=llm_client, tools=tools)
+
+    return Runtime(run_store=run_store, ledger_store=ledger_store, effect_handlers=handlers, context=context)
+
+
+def create_local_file_runtime(
+    *,
+    base_dir: str | Path,
+    provider: str,
+    model: str,
+    llm_kwargs: Optional[Dict[str, Any]] = None,
+    context: Optional[Any] = None,
+    config: Optional[RuntimeConfig] = None,
+) -> Runtime:
+    run_store, ledger_store = _default_file_stores(base_dir=base_dir)
+    return create_local_runtime(
+        provider=provider,
+        model=model,
+        llm_kwargs=llm_kwargs,
+        run_store=run_store,
+        ledger_store=ledger_store,
+        context=context,
+        config=config,
+    )
+
+
+def create_remote_file_runtime(
+    *,
+    base_dir: str | Path,
+    server_base_url: str,
+    model: str,
+    headers: Optional[Dict[str, str]] = None,
+    timeout_s: float = 60.0,
+    context: Optional[Any] = None,
+) -> Runtime:
+    run_store, ledger_store = _default_file_stores(base_dir=base_dir)
+    return create_remote_runtime(
+        server_base_url=server_base_url,
+        model=model,
+        headers=headers,
+        timeout_s=timeout_s,
+        run_store=run_store,
+        ledger_store=ledger_store,
+        context=context,
+    )