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

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,43 @@
+"""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
+
+Importing this module is the explicit opt-in to an AbstractCore dependency.
+"""
+
+from .llm_client import (
+    AbstractCoreLLMClient,
+    LocalAbstractCoreLLMClient,
+    RemoteAbstractCoreLLMClient,
+)
+from .tool_executor import AbstractCoreToolExecutor, 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",
+    "ToolExecutor",
+    "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,89 @@
+"""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 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")
+        params = payload.get("params")
+
+        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: ToolExecutor) -> EffectHandler:
+    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)")
+
+        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) -> 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,150 @@
+"""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.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,
+) -> Runtime:
+    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)
+
+    return Runtime(run_store=run_store, ledger_store=ledger_store, effect_handlers=handlers, context=context, effect_policy=effect_policy)
+
+
+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,
+) -> 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,
+    )
+
+
+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,
+    )
+

abstractruntime/integrations/abstractcore/llm_client.py

@@ -0,0 +1,296 @@
+"""abstractruntime.integrations.abstractcore.llm_client
+
+AbstractCore-backed LLM clients for AbstractRuntime.
+
+Design intent:
+- Keep `RunState.vars` JSON-safe: normalize outputs into dicts.
+- Support both execution topologies:
+  - local/in-process: call AbstractCore's `create_llm(...).generate(...)`
+  - remote: call AbstractCore server `/v1/chat/completions`
+
+Remote mode is the preferred way to support per-request dynamic routing (e.g. `base_url`).
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, is_dataclass
+from typing import Any, Dict, List, Optional, Protocol
+
+from .logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class RequestSender(Protocol):
+    def post(
+        self,
+        url: str,
+        *,
+        headers: Dict[str, str],
+        json: Dict[str, Any],
+        timeout: float,
+    ) -> Dict[str, Any]: ...
+
+
+class AbstractCoreLLMClient(Protocol):
+    def generate(
+        self,
+        *,
+        prompt: str,
+        messages: Optional[List[Dict[str, str]]] = None,
+        system_prompt: Optional[str] = None,
+        tools: Optional[List[Dict[str, Any]]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Return a JSON-safe dict with at least: content/tool_calls/usage/model."""
+
+
+def _jsonable(value: Any) -> Any:
+    """Best-effort conversion to JSON-safe objects.
+
+    This is intentionally conservative: if a value isn't naturally JSON-serializable,
+    we fall back to `str(value)`.
+    """
+
+    if value is None:
+        return None
+    if isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, dict):
+        return {str(k): _jsonable(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_jsonable(v) for v in value]
+    if is_dataclass(value):
+        return _jsonable(asdict(value))
+
+    # Pydantic v2
+    model_dump = getattr(value, "model_dump", None)
+    if callable(model_dump):
+        return _jsonable(model_dump())
+
+    # Pydantic v1
+    to_dict = getattr(value, "dict", None)
+    if callable(to_dict):
+        return _jsonable(to_dict())
+
+    return str(value)
+
+
+def _normalize_local_response(resp: Any) -> Dict[str, Any]:
+    """Normalize an AbstractCore local `generate()` result into JSON."""
+
+    # Dict-like already
+    if isinstance(resp, dict):
+        return _jsonable(resp)
+
+    # Pydantic structured output
+    if hasattr(resp, "model_dump") or hasattr(resp, "dict"):
+        return {
+            "content": None,
+            "data": _jsonable(resp),
+            "tool_calls": None,
+            "usage": None,
+            "model": None,
+            "finish_reason": None,
+        }
+
+    # AbstractCore GenerateResponse
+    content = getattr(resp, "content", None)
+    tool_calls = getattr(resp, "tool_calls", None)
+    usage = getattr(resp, "usage", None)
+    model = getattr(resp, "model", None)
+    finish_reason = getattr(resp, "finish_reason", None)
+
+    return {
+        "content": content,
+        "data": None,
+        "tool_calls": _jsonable(tool_calls) if tool_calls is not None else None,
+        "usage": _jsonable(usage) if usage is not None else None,
+        "model": model,
+        "finish_reason": finish_reason,
+    }
+
+
+class LocalAbstractCoreLLMClient:
+    """In-process LLM client using AbstractCore's provider stack."""
+
+    def __init__(
+        self,
+        *,
+        provider: str,
+        model: str,
+        llm_kwargs: Optional[Dict[str, Any]] = None,
+    ):
+        from abstractcore import create_llm
+        from abstractcore.tools.handler import UniversalToolHandler
+
+        self._provider = provider
+        self._model = model
+        self._llm = create_llm(provider, model=model, **(llm_kwargs or {}))
+        self._tool_handler = UniversalToolHandler(model)
+
+    def generate(
+        self,
+        *,
+        prompt: str,
+        messages: Optional[List[Dict[str, str]]] = None,
+        system_prompt: Optional[str] = None,
+        tools: Optional[List[Dict[str, Any]]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        params = dict(params or {})
+
+        # `base_url` is a provider construction concern in local mode. We intentionally
+        # do not create new providers per call unless the host explicitly chooses to.
+        params.pop("base_url", None)
+
+        # If tools provided, use UniversalToolHandler to format them into prompt
+        # This works for models without native tool support
+        effective_prompt = prompt
+        if tools:
+            from abstractcore.tools import ToolDefinition
+            tool_defs = []
+            for t in tools:
+                tool_defs.append(ToolDefinition(
+                    name=t.get("name", ""),
+                    description=t.get("description", ""),
+                    parameters=t.get("parameters", {}),
+                ))
+            tools_prompt = self._tool_handler.format_tools_prompt(tool_defs)
+            effective_prompt = f"{tools_prompt}\n\nUser request: {prompt}"
+
+        resp = self._llm.generate(
+            prompt=effective_prompt,
+            messages=messages,
+            system_prompt=system_prompt,
+            stream=False,
+            **params,
+        )
+        
+        result = _normalize_local_response(resp)
+        
+        # Parse tool calls from response if tools were provided
+        if tools and result.get("content"):
+            parsed = self._tool_handler.parse_response(result["content"], mode="prompted")
+            if parsed.tool_calls:
+                result["tool_calls"] = [
+                    {"name": tc.name, "arguments": tc.arguments, "call_id": tc.call_id}
+                    for tc in parsed.tool_calls
+                ]
+        
+        return result
+
+
+class HttpxRequestSender:
+    """Default request sender based on httpx (sync)."""
+
+    def __init__(self):
+        import httpx
+
+        self._httpx = httpx
+
+    def post(
+        self,
+        url: str,
+        *,
+        headers: Dict[str, str],
+        json: Dict[str, Any],
+        timeout: float,
+    ) -> Dict[str, Any]:
+        resp = self._httpx.post(url, headers=headers, json=json, timeout=timeout)
+        resp.raise_for_status()
+        return resp.json()
+
+
+class RemoteAbstractCoreLLMClient:
+    """Remote LLM client calling an AbstractCore server endpoint."""
+
+    def __init__(
+        self,
+        *,
+        server_base_url: str,
+        model: str,
+        timeout_s: float = 60.0,
+        headers: Optional[Dict[str, str]] = None,
+        request_sender: Optional[RequestSender] = None,
+    ):
+        self._server_base_url = server_base_url.rstrip("/")
+        self._model = model
+        self._timeout_s = timeout_s
+        self._headers = dict(headers or {})
+        self._sender = request_sender or HttpxRequestSender()
+
+    def generate(
+        self,
+        *,
+        prompt: str,
+        messages: Optional[List[Dict[str, str]]] = None,
+        system_prompt: Optional[str] = None,
+        tools: Optional[List[Dict[str, Any]]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        params = dict(params or {})
+
+        # Build OpenAI-like messages for AbstractCore server.
+        out_messages: List[Dict[str, str]] = []
+        if system_prompt:
+            out_messages.append({"role": "system", "content": system_prompt})
+
+        if messages:
+            out_messages.extend(messages)
+        else:
+            out_messages.append({"role": "user", "content": prompt})
+
+        body: Dict[str, Any] = {
+            "model": self._model,
+            "messages": out_messages,
+            "stream": False,
+        }
+
+        # Dynamic routing support (AbstractCore server feature).
+        base_url = params.pop("base_url", None)
+        if base_url:
+            body["base_url"] = base_url
+
+        # Pass through common OpenAI-compatible parameters.
+        for key in (
+            "temperature",
+            "max_tokens",
+            "stop",
+            "seed",
+            "frequency_penalty",
+            "presence_penalty",
+        ):
+            if key in params and params[key] is not None:
+                body[key] = params[key]
+
+        if tools is not None:
+            body["tools"] = tools
+
+        url = f"{self._server_base_url}/v1/chat/completions"
+        resp = self._sender.post(url, headers=self._headers, json=body, timeout=self._timeout_s)
+
+        # Normalize OpenAI-like response.
+        try:
+            choice0 = (resp.get("choices") or [])[0]
+            msg = choice0.get("message") or {}
+            return {
+                "content": msg.get("content"),
+                "data": None,
+                "tool_calls": _jsonable(msg.get("tool_calls")) if msg.get("tool_calls") is not None else None,
+                "usage": _jsonable(resp.get("usage")) if resp.get("usage") is not None else None,
+                "model": resp.get("model"),
+                "finish_reason": choice0.get("finish_reason"),
+            }
+        except Exception:
+            # Fallback: return the raw response in JSON-safe form.
+            logger.warning("Remote LLM response normalization failed; returning raw JSON")
+            return {
+                "content": None,
+                "data": _jsonable(resp),
+                "tool_calls": None,
+                "usage": None,
+                "model": resp.get("model") if isinstance(resp, dict) else None,
+                "finish_reason": None,
+            }
+

abstractruntime/integrations/abstractcore/logging.py

@@ -0,0 +1,27 @@
+"""abstractruntime.integrations.abstractcore.logging
+
+Logging adapter for the AbstractCore-integrated runtime.
+
+We prefer AbstractCore's structured logger for consistency across the stack.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def get_logger(name: str) -> Any:
+    """Return a logger compatible with AbstractCore's structured logger.
+
+    This is intentionally a thin wrapper to keep the integration layer small.
+    """
+
+    try:
+        from abstractcore.utils.structured_logging import get_logger as _get_logger
+
+        return _get_logger(name)
+    except Exception:  # pragma: no cover
+        import logging
+
+        return logging.getLogger(name)
+