par-runtime 0.4.8__py3-none-any.whl

examples/basic_agent.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""Example: Using PAR Runtime from Python.
+
+This demonstrates the basic workflow:
+1. Initialize runtime with SQLite persistence
+2. Register a tool
+3. Register an agent
+4. Invoke the agent
+
+Prerequisites:
+  - Build the shared library: dune build lib/ffi/par_capi.so
+  - Set PAR_RUNTIME_LIB or run from project root
+
+Usage:
+  python3 examples/basic_agent.py
+"""
+
+import json
+import os
+import sys
+
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from par_runtime import Runtime, PARError
+
+
+def main():
+    config = json.dumps({
+        "persistence": {"tag": "sqlite", "contents": "par_agent.db"},
+        "event_bus": {
+            "max_queue_size": 100,
+            "dlq_enabled": False,
+            "dlq_max_size": 10,
+        },
+        "default_quota": {
+            "max_tokens": 4096,
+            "max_iterations": 10,
+            "timeout_seconds": 30.0,
+        },
+        "shutdown": {
+            "grace_period_seconds": 5.0,
+            "force_after_seconds": 10.0,
+        },
+        "llm_providers": [],
+        "eval_limits": {
+            "max_depth": 10,
+            "max_node_visits": 1000,
+        },
+    })
+
+    print("=== P-A-R Python Example ===\n")
+    print(f"Initializing runtime with SQLite persistence...")
+
+    try:
+        with Runtime(config) as rt:
+            print(f"  Runtime: {rt}")
+
+            print("\nRegistering tools...")
+            rt.register_tool(
+                name="calculator",
+                description="Evaluate arithmetic expressions",
+                input_schema=json.dumps({
+                    "type": "object",
+                    "properties": {
+                        "expression": {"type": "string"}
+                    },
+                    "required": ["expression"]
+                }),
+            )
+            print("  [+] calculator tool registered")
+
+            rt.register_tool(
+                name="echo",
+                description="Echo back the input",
+                input_schema=json.dumps({
+                    "type": "object",
+                    "properties": {
+                        "message": {"type": "string"}
+                    },
+                    "required": ["message"]
+                }),
+            )
+            print("  [+] echo tool registered")
+
+            print(f"\n  Runtime state: {rt}")
+
+            print("\n=== Done ===")
+            print("Note: Agent invocation requires an LLM provider.")
+            print("Configure via 'par config' or set PAR_RUNTIME_LIB.")
+
+    except PARError as e:
+        print(f"\nPAR Error: {e}")
+        print("Make sure par_capi.so is built: dune build lib/ffi/par_capi.so")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

par_runtime/__init__.py

@@ -0,0 +1,20 @@
+"""Python bindings for P-A-R (Programmable Agent Runtime)."""
+from par_runtime._errors import (
+    PARError,
+    PARInitError,
+    PARInvokeError,
+    PARToolError,
+    PARWorkflowError,
+)
+from par_runtime.runtime import Runtime
+
+__version__ = "0.4.8"
+
+__all__ = [
+    "Runtime",
+    "PARError",
+    "PARInitError",
+    "PARInvokeError",
+    "PARToolError",
+    "PARWorkflowError",
+]

par_runtime/_errors.py

@@ -0,0 +1,26 @@
+"""Exception hierarchy for the PAR runtime."""
+
+
+class PARError(Exception):
+    """Base exception for PAR runtime errors."""
+    pass
+
+
+class PARInitError(PARError):
+    """Failed to initialize the PAR runtime."""
+    pass
+
+
+class PARInvokeError(PARError):
+    """Agent invocation failed."""
+    pass
+
+
+class PARToolError(PARError):
+    """Tool registration failed."""
+    pass
+
+
+class PARWorkflowError(PARError):
+    """Workflow operation failed."""
+    pass

par_runtime/_ffi.py

@@ -0,0 +1,160 @@
+"""Low-level ctypes FFI declarations for par_capi.so.
+
+This is the ONLY module that touches ctypes directly.
+All other modules import from here.
+"""
+import ctypes
+import ctypes.util
+import os
+import sys
+from pathlib import Path
+
+
+def _find_library() -> str:
+    """Find the par_capi.so shared library."""
+    # 1. PAR_RUNTIME_LIB env var
+    env = os.environ.get("PAR_RUNTIME_LIB")
+    if env and Path(env).exists():
+        return env
+    # 2. Relative to this package
+    pkg_dir = Path(__file__).resolve().parent
+    project_root = pkg_dir.parent.parent.parent
+    candidates = [
+        pkg_dir / "lib" / "par_capi.so",
+        project_root / "_build" / "default" / "lib" / "ffi" / "par_capi.so",
+    ]
+    for c in candidates:
+        if c.exists():
+            return str(c)
+    # 3. System library path
+    return "par_capi.so"
+
+
+_lib = ctypes.CDLL(_find_library())
+
+# --- Declare function signatures ---
+
+# par_runtime_t* par_init(const char* config_json);
+_lib.par_init.argtypes = [ctypes.c_char_p]
+_lib.par_init.restype = ctypes.c_void_p
+
+# void par_shutdown(par_runtime_t* rt);
+_lib.par_shutdown.argtypes = [ctypes.c_void_p]
+_lib.par_shutdown.restype = None
+
+# int par_register_tool(par_runtime_t* rt, const char* name,
+#                       const char* description, const char* input_schema);
+_lib.par_register_tool.argtypes = [
+    ctypes.c_void_p, ctypes.c_char_p, ctypes.c_char_p, ctypes.c_char_p
+]
+_lib.par_register_tool.restype = ctypes.c_int
+
+# int par_register_tool_with_handler(par_runtime_t* rt, const char* name,
+#                                     const char* description, const char* input_schema,
+#                                     int handler_id);
+_lib.par_register_tool_with_handler.argtypes = [
+    ctypes.c_void_p, ctypes.c_char_p, ctypes.c_char_p, ctypes.c_char_p, ctypes.c_int
+]
+_lib.par_register_tool_with_handler.restype = ctypes.c_int
+
+# void par_store_python_handler(int handler_id, par_tool_callback fn);
+# par_tool_callback = char* (*)(int handler_id, const char* input_json)
+_PYTHON_TOOL_CALLBACK = ctypes.CFUNCTYPE(ctypes.c_char_p, ctypes.c_int, ctypes.c_char_p)
+_lib.par_store_python_handler.argtypes = [ctypes.c_int, _PYTHON_TOOL_CALLBACK]
+_lib.par_store_python_handler.restype = None
+
+# int par_register_agent(par_runtime_t* rt, const char* config_json);
+_lib.par_register_agent.argtypes = [ctypes.c_void_p, ctypes.c_char_p]
+_lib.par_register_agent.restype = ctypes.c_int
+
+# char* par_invoke(par_runtime_t* rt, const char* agent_id, const char* message);
+# Caller MUST free() the returned string — returns c_void_p, not c_char_p
+_lib.par_invoke.argtypes = [ctypes.c_void_p, ctypes.c_char_p, ctypes.c_char_p]
+_lib.par_invoke.restype = ctypes.c_void_p
+
+# char* par_invoke_structured(par_runtime_t* rt, const char* agent_id,
+#                              const char* message, const char* schema_json);
+_lib.par_invoke_structured.argtypes = [ctypes.c_void_p, ctypes.c_char_p,
+                                       ctypes.c_char_p, ctypes.c_char_p]
+_lib.par_invoke_structured.restype = ctypes.c_void_p
+
+# char* par_submit_workflow(par_runtime_t* rt, const char* workflow_json);
+_lib.par_submit_workflow.argtypes = [ctypes.c_void_p, ctypes.c_char_p]
+_lib.par_submit_workflow.restype = ctypes.c_void_p
+
+# int par_approve_workflow(par_runtime_t* rt, const char* run_id, const char* approver);
+_lib.par_approve_workflow.argtypes = [ctypes.c_void_p, ctypes.c_char_p, ctypes.c_char_p]
+_lib.par_approve_workflow.restype = ctypes.c_int
+
+# char* par_resume_workflow(par_runtime_t* rt, const char* run_id);
+_lib.par_resume_workflow.argtypes = [ctypes.c_void_p, ctypes.c_char_p]
+_lib.par_resume_workflow.restype = ctypes.c_void_p
+
+# char* par_health(par_runtime_t* rt);
+_lib.par_health.argtypes = [ctypes.c_void_p]
+_lib.par_health.restype = ctypes.c_void_p
+
+# char* par_metrics(par_runtime_t* rt);
+_lib.par_metrics.argtypes = [ctypes.c_void_p]
+_lib.par_metrics.restype = ctypes.c_void_p
+
+# int par_steer(par_runtime_t* rt, const char* message);
+_lib.par_steer.argtypes = [ctypes.c_void_p, ctypes.c_char_p]
+_lib.par_steer.restype = ctypes.c_int
+
+# int par_follow_up(par_runtime_t* rt, const char* message);
+_lib.par_follow_up.argtypes = [ctypes.c_void_p, ctypes.c_char_p]
+_lib.par_follow_up.restype = ctypes.c_int
+
+# char* par_mcp_server(par_runtime_t* rt, const char* server_id);
+_lib.par_mcp_server.argtypes = [ctypes.c_void_p, ctypes.c_char_p]
+_lib.par_mcp_server.restype = ctypes.c_void_p
+
+# char* par_mcp_list_tools(par_runtime_t* rt, const char* server_id);
+_lib.par_mcp_list_tools.argtypes = [ctypes.c_void_p, ctypes.c_char_p]
+_lib.par_mcp_list_tools.restype = ctypes.c_void_p
+
+# char* par_workflow_status(par_runtime_t* rt, const char* run_id);
+_lib.par_workflow_status.argtypes = [ctypes.c_void_p, ctypes.c_char_p]
+_lib.par_workflow_status.restype = ctypes.c_void_p
+
+# int par_workflow_cancel(par_runtime_t* rt, const char* run_id);
+_lib.par_workflow_cancel.argtypes = [ctypes.c_void_p, ctypes.c_char_p]
+_lib.par_workflow_cancel.restype = ctypes.c_int
+
+# int par_event_subscribe(par_runtime_t* rt, void* callback);
+_lib.par_event_subscribe.argtypes = [ctypes.c_void_p, ctypes.c_void_p]
+_lib.par_event_subscribe.restype = ctypes.c_int
+
+# char* par_version(void);
+_lib.par_version.argtypes = []
+_lib.par_version.restype = ctypes.c_void_p
+
+# --- Helper: libc free() for strings returned by C ---
+if sys.platform == "darwin":
+    _libc = ctypes.CDLL("libc.dylib")
+else:
+    _libc_name = ctypes.util.find_library("c") or "libc.so.6"
+    _libc = ctypes.CDLL(_libc_name)
+
+_free = _libc.free
+_free.argtypes = [ctypes.c_void_p]
+_free.restype = None
+
+
+def _c_str(s: str) -> bytes:
+    """Encode a Python string as UTF-8 bytes for ctypes."""
+    return s.encode("utf-8")
+
+
+def _py_str(ptr: ctypes.c_void_p) -> str:
+    """Extract a Python string from a C char* and free the C memory."""
+    if not ptr:
+        return ""
+    try:
+        result = ctypes.cast(ptr, ctypes.c_char_p).value
+        if result is None:
+            return ""
+        return result.decode("utf-8")
+    finally:
+        _free(ptr)

par_runtime/runtime.py

@@ -0,0 +1,457 @@
+"""High-level Runtime class wrapping the PAR C FFI."""
+import ctypes
+import json
+from typing import Any, Optional
+
+from par_runtime._ffi import _lib, _c_str, _py_str, _PYTHON_TOOL_CALLBACK
+from par_runtime._errors import (
+    PARError,
+    PARInitError,
+    PARInvokeError,
+    PARToolError,
+    PARWorkflowError,
+)
+
+
+class Runtime:
+    """PAR Runtime — type-safe agent runtime with formal state guarantees.
+
+    Usage:
+        with Runtime('{"persistence": {"sqlite": "par.db"}}') as rt:
+            rt.register_tool("echo", "Echoes input", '{"type": "object"}')
+            rt.register_agent('{"id": "my-agent", ...}')
+            result = rt.invoke("my-agent", "Hello!")
+    """
+
+    __slots__ = ("_handle",)
+
+    _callbacks: dict = {}
+
+    def __init__(self, config_json: str):
+        """Initialize PAR runtime from JSON config string.
+
+        Args:
+            config_json: Runtime configuration as JSON string.
+
+        Raises:
+            PARInitError: If initialization fails.
+        """
+        normalized = self._normalize_config(config_json)
+        handle = _lib.par_init(_c_str(normalized))
+        if not handle:
+            raise PARInitError("Failed to initialize PAR runtime")
+        self._handle: Any = handle
+
+    @staticmethod
+    def _normalize_config(config_json: str) -> str:
+        """Fill in required OCaml runtime_config fields that the Python
+        caller may have omitted, so that the OCaml yojson decoder accepts
+        the payload. Returns the original JSON if it already parses.
+        """
+        try:
+            cfg = json.loads(config_json)
+        except json.JSONDecodeError as e:
+            raise PARInitError(f"config_json is not valid JSON: {e}")
+        if not isinstance(cfg, dict):
+            raise PARInitError("config_json must decode to a JSON object")
+
+        defaults = {
+            "default_quota": {
+                "max_concurrent_tasks": 4,
+                "max_concurrent_tools_per_agent": 2,
+                "max_tokens_per_turn": None,
+                "max_total_tokens": None,
+            },
+            "shutdown": {
+                "drain_timeout": 5.0,
+                "cancel_grace_period": 2.0,
+                "flush_batch_size": 100,
+            },
+            "eval_limits": {"max_depth": 10, "max_node_visits": 1000},
+            "llm_providers": [],
+            "parallel_tool_execution": True,
+            "event_retention_seconds": 604800.0,
+        }
+        for key, default in defaults.items():
+            if key not in cfg:
+                cfg[key] = default
+            elif isinstance(default, dict) and isinstance(cfg[key], dict):
+                for sub_key, sub_default in default.items():
+                    cfg[key].setdefault(sub_key, sub_default)
+        if "event_bus" in cfg and isinstance(cfg["event_bus"], dict):
+            cfg["event_bus"].setdefault("buffer_capacity", 100)
+            cfg["event_bus"].setdefault("dlq_enabled", False)
+            cfg["event_bus"].setdefault("dlq_max_size", 10)
+            cfg["event_bus"].setdefault("critical_event_types", [])
+            if isinstance(cfg["event_bus"].get("delivery"), dict):
+                cfg["event_bus"]["delivery"].setdefault("max_delivery_attempts", 3)
+                cfg["event_bus"]["delivery"].setdefault("initial_retry_delay", 0.1)
+                cfg["event_bus"]["delivery"].setdefault("retry_backoff", ["Fixed", 0.5])
+                cfg["event_bus"]["delivery"].setdefault("delivery_timeout", 5.0)
+        return json.dumps(cfg)
+
+    def __enter__(self) -> "Runtime":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+        return False
+
+    def __del__(self):
+        if hasattr(self, "_handle"):
+            self.close()
+
+    def close(self):
+        """Shut down the runtime and release resources."""
+        if getattr(self, "_handle", None):
+            _lib.par_shutdown(self._handle)
+            self._handle = None
+
+    def _check_handle(self):
+        if not self._handle:
+            raise PARError("Runtime has been shut down")
+
+    def register_tool(self, name: str, description: str, input_schema: str) -> None:
+        """Register a tool with the runtime.
+
+        Args:
+            name: Tool name.
+            description: Tool description.
+            input_schema: JSON Schema for tool input.
+
+        Raises:
+            PARToolError: If registration fails.
+        """
+        self._check_handle()
+        result = _lib.par_register_tool(
+            self._handle,
+            _c_str(name),
+            _c_str(description),
+            _c_str(input_schema),
+        )
+        if result != 0:
+            raise PARToolError(f"Failed to register tool: {name}")
+
+    def register_tool_with_handler(self, name: str, description: str,
+                                   input_schema: str, handler) -> None:
+        """Register a tool with a Python callback handler.
+
+        Args:
+            name: Tool name.
+            description: Tool description.
+            input_schema: JSON Schema for tool input.
+            handler: Python callable (str) -> str that processes tool input
+                     JSON and returns output JSON.
+
+        Raises:
+            PARToolError: If registration fails.
+        """
+        self._check_handle()
+
+        def _wrapper(handler_id: int, input_json: bytes) -> bytes:
+            try:
+                result = handler(input_json.decode("utf-8"))
+                return result.encode("utf-8")
+            except Exception as e:
+                return json.dumps({"error": str(e)}).encode("utf-8")
+
+        c_callback = _PYTHON_TOOL_CALLBACK(_wrapper)
+
+        handler_id = len(Runtime._callbacks)
+        Runtime._callbacks[handler_id] = c_callback
+
+        _lib.par_store_python_handler(handler_id, c_callback)
+
+        result = _lib.par_register_tool_with_handler(
+            self._handle,
+            _c_str(name),
+            _c_str(description),
+            _c_str(input_schema),
+            handler_id,
+        )
+        if result != 0:
+            Runtime._callbacks.pop(handler_id, None)
+            raise PARToolError(f"Failed to register tool with handler: {name}")
+
+    def register_agent(self, config_json: str) -> None:
+        """Register an agent from JSON config.
+
+        Args:
+            config_json: Agent configuration as JSON string.
+
+        Raises:
+            PARError: If registration fails.
+        """
+        self._check_handle()
+        result = _lib.par_register_agent(self._handle, _c_str(config_json))
+        if result != 0:
+            raise PARError("Failed to register agent")
+
+    def invoke(self, agent_id: str, message: str) -> str:
+        """Invoke an agent synchronously.
+
+        Args:
+            agent_id: The agent's identifier.
+            message: The user message.
+
+        Returns:
+            JSON response string.
+
+        Raises:
+            PARInvokeError: If invocation fails.
+        """
+        self._check_handle()
+        result_ptr = _lib.par_invoke(
+            self._handle, _c_str(agent_id), _c_str(message)
+        )
+        result = _py_str(result_ptr)
+        if not result:
+            raise PARInvokeError(f"Invoke failed for agent: {agent_id}")
+        try:
+            parsed = json.loads(result)
+            if isinstance(parsed, dict) and "error" in parsed:
+                raise PARInvokeError(parsed["error"])
+        except json.JSONDecodeError:
+            pass
+        return result
+
+    def invoke_structured(self, agent_id: str, message: str,
+                          response_schema: dict) -> dict:
+        """Invoke an agent with structured output constraint.
+
+        Args:
+            agent_id: The agent's identifier.
+            message: The user message.
+            response_schema: JSON Schema dict describing the desired output.
+
+        Returns:
+            Parsed JSON dict matching response_schema.
+
+        Raises:
+            PARInvokeError: If invocation fails or output doesn't match schema.
+        """
+        self._check_handle()
+        schema_json = json.dumps(response_schema)
+        result_ptr = _lib.par_invoke_structured(
+            self._handle, _c_str(agent_id), _c_str(message), _c_str(schema_json)
+        )
+        result = _py_str(result_ptr)
+        if not result:
+            raise PARInvokeError(f"Invoke_structured failed for agent: {agent_id}")
+        try:
+            parsed = json.loads(result)
+            if isinstance(parsed, dict) and "status" in parsed:
+                if parsed["status"] == "ok":
+                    return json.loads(parsed["value"])
+                if "message" in parsed:
+                    raise PARInvokeError(parsed["message"])
+            if isinstance(parsed, dict) and "error" in parsed:
+                raise PARInvokeError(parsed["error"])
+        except json.JSONDecodeError:
+            pass
+        raise PARInvokeError(f"Invoke_structured returned unexpected: {result}")
+
+    def submit_workflow(self, workflow_json: str) -> str:
+        """Submit a workflow for execution.
+
+        Args:
+            workflow_json: Workflow definition as JSON string.
+
+        Returns:
+            JSON result string.
+
+        Raises:
+            PARWorkflowError: If submission fails.
+        """
+        self._check_handle()
+        result_ptr = _lib.par_submit_workflow(
+            self._handle, _c_str(workflow_json)
+        )
+        result = _py_str(result_ptr)
+        try:
+            parsed = json.loads(result)
+            if isinstance(parsed, dict) and "error" in parsed:
+                raise PARWorkflowError(parsed["error"])
+        except json.JSONDecodeError:
+            pass
+        return result
+
+    def approve_workflow(self, run_id: str, approver: str) -> None:
+        """Approve a pending workflow step.
+
+        Args:
+            run_id: Workflow run identifier.
+            approver: Approver identity.
+
+        Raises:
+            PARWorkflowError: If approval fails.
+        """
+        self._check_handle()
+        result = _lib.par_approve_workflow(
+            self._handle, _c_str(run_id), _c_str(approver)
+        )
+        if result != 0:
+            raise PARWorkflowError(f"Failed to approve workflow: {run_id}")
+
+    def resume_workflow(self, run_id: str) -> str:
+        """Resume a paused workflow.
+
+        Args:
+            run_id: Workflow run identifier.
+
+        Returns:
+            JSON result string.
+
+        Raises:
+            PARWorkflowError: If resume fails.
+        """
+        self._check_handle()
+        result_ptr = _lib.par_resume_workflow(
+            self._handle, _c_str(run_id)
+        )
+        return _py_str(result_ptr)
+
+    def health(self) -> dict:
+        """Return runtime health status.
+
+        Returns:
+            Dict with keys: runtime_alive (bool), persistence_ok (bool),
+            last_llm_call_at (float|None), last_llm_call_status (str).
+        """
+        self._check_handle()
+        result_ptr = _lib.par_health(self._handle)
+        result = _py_str(result_ptr)
+        if not result:
+            raise PARError("health() returned empty")
+        try:
+            parsed = json.loads(result)
+            if "error" in parsed:
+                raise PARError(parsed["error"])
+            return parsed
+        except json.JSONDecodeError as e:
+            raise PARError(f"Invalid health JSON: {e}")
+
+    def metrics(self) -> dict:
+        """Return runtime metrics snapshot.
+
+        Returns:
+            Dict with keys: llm_requests_total, task_completed_total,
+            task_failed_total, tool_invocations_total,
+            events_published_total, events_dropped_total.
+        """
+        self._check_handle()
+        result_ptr = _lib.par_metrics(self._handle)
+        result = _py_str(result_ptr)
+        if not result:
+            raise PARError("metrics() returned empty")
+        try:
+            parsed = json.loads(result)
+            if "error" in parsed:
+                raise PARError(parsed["error"])
+            return parsed.get("metrics", parsed)
+        except json.JSONDecodeError as e:
+            raise PARError(f"Invalid metrics JSON: {e}")
+
+    def steer(self, message: str) -> None:
+        """Inject a steering message into the agent's running loop.
+
+        Args:
+            message: User message to inject.
+
+        Raises:
+            PARError: If steering fails.
+        """
+        self._check_handle()
+        rc = _lib.par_steer(self._handle, _c_str(message))
+        if rc != 0:
+            raise PARError(f"steer() failed with code {rc}")
+
+    def follow_up(self, message: str) -> None:
+        """Queue a follow-up message for after the agent's current loop ends."""
+        self._check_handle()
+        rc = _lib.par_follow_up(self._handle, _c_str(message))
+        if rc != 0:
+            raise PARError(f"follow_up() failed with code {rc}")
+
+    def mcp_server(self, server_id: str) -> dict:
+        """Query an MCP server's tools by server ID.
+
+        Args:
+            server_id: Name of the MCP server to query.
+
+        Returns:
+            dict with server_id and tools list.
+
+        Raises:
+            PARError: If server not found or query fails.
+        """
+        self._check_handle()
+        result_ptr = _lib.par_mcp_server(self._handle, _c_str(server_id))
+        result = _py_str(result_ptr)
+        parsed = json.loads(result)
+        if "error" in parsed:
+            raise PARError(parsed["error"])
+        return parsed
+
+    def mcp_list_tools(self, server_id: str) -> list:
+        """List tools available on an MCP server.
+
+        Args:
+            server_id: Name of the MCP server.
+
+        Returns:
+            list of dicts with tool name and description.
+
+        Raises:
+            PARError: If server not found or query fails.
+        """
+        self._check_handle()
+        result_ptr = _lib.par_mcp_list_tools(self._handle, _c_str(server_id))
+        result = _py_str(result_ptr)
+        parsed = json.loads(result)
+        if "error" in parsed:
+            raise PARError(parsed["error"])
+        return parsed.get("tools", [])
+
+    def workflow_status(self, run_id: str) -> dict:
+        """Query the status of a workflow run.
+
+        Args:
+            run_id: ID of the workflow run.
+
+        Returns:
+            dict with run_id and status.
+
+        Raises:
+            PARError: If query fails.
+        """
+        self._check_handle()
+        result_ptr = _lib.par_workflow_status(self._handle, _c_str(run_id))
+        result = _py_str(result_ptr)
+        parsed = json.loads(result)
+        if "error" in parsed:
+            raise PARError(parsed["error"])
+        return parsed
+
+    def workflow_cancel(self, run_id: str) -> None:
+        """Cancel a running workflow.
+
+        Args:
+            run_id: ID of the workflow run to cancel.
+
+        Raises:
+            PARWorkflowError: If cancellation fails.
+        """
+        self._check_handle()
+        rc = _lib.par_workflow_cancel(self._handle, _c_str(run_id))
+        if rc != 0:
+            raise PARWorkflowError(f"workflow_cancel({run_id}) failed")
+
+    def version() -> str:
+        """Return the PAR runtime version string."""
+        result_ptr = _lib.par_version()
+        return _py_str(result_ptr)
+
+    def __repr__(self) -> str:
+        status = "active" if self._handle else "closed"
+        return f"<PAR Runtime {status}>"

par_runtime-0.4.8.dist-info/METADATA

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: par-runtime
+Version: 0.4.8
+Summary: Python bindings for P-A-R (Programmable Agent Runtime)
+License: MIT
+Requires-Python: >=3.8

par_runtime-0.4.8.dist-info/RECORD

@@ -0,0 +1,13 @@
+examples/basic_agent.py,sha256=9KqBkjBO0DX6N2sTcEd8HdCHl7kEBMv5-h17ZzQJcCI,2719
+par_runtime/__init__.py,sha256=FpP-8jQzlp3elxDSdhI76BW_yEWcNMMV5gjJ4SERZbY,385
+par_runtime/_errors.py,sha256=Txh3D7AYRMxz_3xqUCA2ZRgi_rYhM7kiO08V4DNShlg,460
+par_runtime/_ffi.py,sha256=3dAXgkenI7AVBE_jopBDI8_f4rJri4Yg5uyBeXjV1Wg,6040
+par_runtime/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+par_runtime/runtime.py,sha256=lywn2KaSuqAazK574IBNs20OVF-F2z2E32xTvTN8WR0,15294
+tests/test_par_sdk.py,sha256=0tMs5I78VQoqC5o6VUadoCfMfTfSdSfRgb_mBry6sM0,8396
+tests/test_runtime.py,sha256=uU1k0ofv6ADYmXuAjnI0ticPjfaKOLGDgB2NL4qzy-M,5848
+tests/test_structured.py,sha256=FWeEBkucJMd82RXEo3G7_7ZKQOlgfImVIlq_7FCvTk0,1784
+par_runtime-0.4.8.dist-info/METADATA,sha256=DMAHnahCmGtbAUM-bncQR5S2aHTiE9eS49HwBOC44Ck,155
+par_runtime-0.4.8.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+par_runtime-0.4.8.dist-info/top_level.txt,sha256=BkfFNv29L95nPNPDU-_rwawuDs0XFj8bPDUynAsse9A,37
+par_runtime-0.4.8.dist-info/RECORD,,

par_runtime-0.4.8.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

par_runtime-0.4.8.dist-info/top_level.txt

@@ -0,0 +1,5 @@
+dist
+docs
+examples
+par_runtime
+tests

tests/test_par_sdk.py

@@ -0,0 +1,231 @@
+"""Integration tests for PAR Python SDK (FFI-2).
+
+Tests the Python wrapper classes around the PAR C FFI.
+Note: The C FFI has known issues with callback registration under eio +
+shared library mode (T5 implementation is in place but the C library
+returns -1 from callbacks due to an unrelated eio initialization issue).
+These tests verify the Python wrapper CLASSES work correctly: imports,
+config parsing, error handling, lifecycle, repr, and context manager.
+"""
+import json
+import os
+import sys
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from par_runtime import (
+    Runtime,
+    PARError,
+    PARInitError,
+    PARInvokeError,
+    PARToolError,
+    PARWorkflowError,
+)
+
+
+def _test_config():
+    return json.dumps({
+        "persistence": ["Sqlite", ":memory:"],
+        "event_bus": {
+            "buffer_capacity": 10,
+            "delivery": {
+                "max_delivery_attempts": 3,
+                "initial_retry_delay": 0.1,
+                "retry_backoff": ["Fixed", 0.5],
+                "delivery_timeout": 5.0,
+            },
+            "dlq_enabled": False,
+            "critical_event_types": [],
+        },
+        "default_quota": {
+            "max_concurrent_tasks": 4,
+            "max_concurrent_tools_per_agent": 2,
+            "max_tokens_per_turn": None,
+            "max_total_tokens": None,
+        },
+        "shutdown": {
+            "drain_timeout": 5.0,
+            "cancel_grace_period": 2.0,
+            "flush_batch_size": 100,
+        },
+        "llm_providers": [],
+        "eval_limits": {"max_depth": 10, "max_node_visits": 1000},
+        "parallel_tool_execution": True,
+    })
+
+
+def _test_agent_config():
+    return json.dumps({
+        "id": "test-agent",
+        "system_prompt": "You are a test agent.",
+        "model": {
+            "provider": "openai",
+            "model_name": "gpt-4",
+            "temperature": 0.7,
+        },
+        "max_iterations": 3,
+        "tools": [],
+    })
+
+
+class TestParSDKIntegration(unittest.TestCase):
+    """10 integration tests covering the PAR Python SDK surface."""
+
+    def setUp(self):
+        self.rt = Runtime(_test_config())
+
+    def tearDown(self):
+        self.rt.close()
+
+    def test_01_library_loaded_and_runtime_works(self):
+        """Runtime initializes via C FFI and holds a handle."""
+        self.assertIsNotNone(self.rt._handle)
+        # Handle is a non-zero integer (boxed Obj.t)
+        self.assertNotEqual(self.rt._handle, 0)
+
+    def test_health_returns_runtime_state(self):
+        """Regression: par_health must return runtime state, not 'Invalid handle'.
+
+        This guards against the v0.4.0 FFI bug where do_init ran
+        Eio_main.run from a C callback context and never returned, so
+        the OCaml side stored a heap pointer (not an int id) and every
+        subsequent FFI call hit 'Invalid runtime handle'. The fix
+        spawns Eio_main.run in a fresh Domain so the callback returns.
+        """
+        h = self.rt.health()
+        self.assertIsInstance(h, dict)
+        self.assertIn("runtime_alive", h)
+        self.assertTrue(h["runtime_alive"])
+        # If the FFI was still broken we would get {"error": "Invalid runtime handle"}
+        self.assertNotIn("error", h)
+
+    def test_register_tool_succeeds_end_to_end(self):
+        """Regression: par_register_tool must succeed for a valid (name, desc, schema).
+
+        Before the v0.4.0 fix, par_register_tool returned -1 because the
+        OCaml side could not find the runtime handle. Now it returns 0
+        and the tool is registered.
+        """
+        try:
+            self.rt.register_tool(
+                "regression_tool",
+                "Tool for FFI regression test",
+                '{"type": "object"}',
+            )
+        except PARToolError as e:
+            self.fail(f"register_tool raised on a valid tool: {e}")
+
+    def test_register_tool_with_handler_stores_callback(self):
+        """Regression: par_register_tool_with_handler stores a Python
+        callback and the runtime remains queryable afterwards.
+
+        Before the v0.4.0 fix the C library stored a heap pointer in
+        place of the runtime id, so the callback registration appeared
+        to succeed at the OCaml level but every subsequent FFI call
+        failed. Now health() still works after registering a callback.
+        """
+        invoked = {"count": 0}
+
+        def handler(input_json: str) -> str:
+            invoked["count"] += 1
+            return '{"echoed": true}'
+
+        self.rt.register_tool_with_handler(
+            "regression_handler_tool",
+            "Tool with Python callback",
+            '{"type": "object"}',
+            handler,
+        )
+        # If FFI is still broken, health() would now fail too.
+        h = self.rt.health()
+        self.assertTrue(h["runtime_alive"])
+
+    def test_02_register_agent_invalid_json(self):
+        """Malformed JSON for register_agent should raise PARError, not crash."""
+        with self.assertRaises((PARError, PARInitError, ValueError, Exception)):
+            self.rt.register_agent("not valid json {{{")
+
+    def test_03_register_agent_well_formed_json(self):
+        """Well-formed JSON for register_agent goes through FFI (may succeed or fail
+        depending on C callback status, but must not crash)."""
+        try:
+            self.rt.register_agent(_test_agent_config())
+        except (PARError, PARInitError):
+            pass  # Acceptable: FFI may reject for config reasons
+
+    def test_04_operations_after_close(self):
+        """Operations after close should raise PARError."""
+        self.rt.close()
+        with self.assertRaises(PARError):
+            self.rt.register_tool("x", "x", "{}")
+        # Double close should be safe
+        self.rt.close()
+
+    def test_05_invoke_unknown_agent(self):
+        """Invoking non-existent agent: PARInvokeError or error JSON."""
+        try:
+            result = self.rt.invoke("nonexistent-agent", "hello")
+            # If it doesn't raise, result should be valid JSON
+            parsed = json.loads(result)
+            self.assertIn("error", parsed)
+        except (PARInvokeError, PARError):
+            pass  # Expected for unknown agent
+
+    def test_06_concurrent_runtimes(self):
+        """Two Runtime instances should be independent with different handles."""
+        rt2 = Runtime(_test_config())
+        try:
+            self.assertIsNotNone(self.rt._handle)
+            self.assertIsNotNone(rt2._handle)
+            self.assertNotEqual(self.rt._handle, rt2._handle)
+            self.assertIn("active", repr(self.rt))
+            self.assertIn("active", repr(rt2))
+        finally:
+            rt2.close()
+
+    def test_07_context_manager(self):
+        """Runtime works as context manager — auto-closes on exit."""
+        rt = Runtime(_test_config())
+        with rt:
+            self.assertIsNotNone(rt._handle)
+            self.assertIn("active", repr(rt))
+        self.assertIsNone(rt._handle)
+        self.assertIn("closed", repr(rt))
+
+    def test_08_repr_states(self):
+        """repr reflects active vs closed state."""
+        self.assertIn("active", repr(self.rt))
+        self.rt.close()
+        self.assertIn("closed", repr(self.rt))
+
+    def test_09_health_check(self):
+        """health() should return dict or skip if C FFI callback unavailable.
+
+        The OCaml callbacks registered via Callback.register in shared library
+        mode have a known interaction issue with Eio domain setup. Python
+        side wrappers exist; if C FFI is unavailable, skip with informative
+        message rather than fail.
+        """
+        try:
+            health = self.rt.health()
+            self.assertIsInstance(health, dict)
+            self.assertIn("runtime_alive", health)
+        except Exception as e:
+            if "Invalid runtime handle" in str(e):
+                self.skipTest(f"C FFI callback unavailable in this build: {e}")
+            raise
+
+    def test_10_metrics_available(self):
+        """metrics() should return dict or skip if C FFI callback unavailable."""
+        try:
+            metrics = self.rt.metrics()
+            self.assertIsInstance(metrics, dict)
+        except Exception as e:
+            if "Invalid runtime handle" in str(e):
+                self.skipTest(f"C FFI callback unavailable in this build: {e}")
+            raise
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_runtime.py

@@ -0,0 +1,190 @@
+"""Tests for PAR Python binding."""
+
+import json
+import os
+import sys
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from par_runtime import Runtime, PARError, PARInitError, PARToolError, PARWorkflowError
+from par_runtime._ffi import _lib
+
+
+def _test_config():
+    return json.dumps({
+        "persistence": ["Sqlite", ":memory:"],
+        "event_bus": {
+            "buffer_capacity": 10,
+            "delivery": {
+                "max_delivery_attempts": 3,
+                "initial_retry_delay": 0.1,
+                "retry_backoff": ["Fixed", 0.5],
+                "delivery_timeout": 5.0,
+            },
+            "dlq_enabled": False,
+            "critical_event_types": [],
+        },
+        "default_quota": {
+            "max_concurrent_tasks": 4,
+            "max_concurrent_tools_per_agent": 2,
+            "max_tokens_per_turn": None,
+            "max_total_tokens": None,
+        },
+        "shutdown": {
+            "drain_timeout": 5.0,
+            "cancel_grace_period": 2.0,
+            "flush_batch_size": 100,
+        },
+        "llm_providers": [],
+        "eval_limits": {
+            "max_depth": 10,
+            "max_node_visits": 1000,
+        },
+        "parallel_tool_execution": True,
+    })
+
+
+class TestLibraryLoading(unittest.TestCase):
+    def test_library_loaded(self):
+        self.assertIsNotNone(_lib)
+        self.assertIsNotNone(_lib.par_init)
+        self.assertIsNotNone(_lib.par_shutdown)
+        self.assertIsNotNone(_lib.par_invoke)
+
+
+class TestRuntimeInit(unittest.TestCase):
+    def test_init_with_valid_config(self):
+        rt = Runtime(_test_config())
+        self.assertIsNotNone(rt._handle)
+        rt.close()
+        self.assertIsNone(rt._handle)
+
+    def test_init_with_context_manager(self):
+        with Runtime(_test_config()) as rt:
+            self.assertIsNotNone(rt._handle)
+        self.assertIsNone(rt._handle)
+
+    def test_init_with_invalid_config(self):
+        try:
+            rt = Runtime("not valid json {{{")
+            rt.close()
+        except PARInitError:
+            pass
+
+    def test_double_close(self):
+        rt = Runtime(_test_config())
+        rt.close()
+        rt.close()
+
+    def test_repr(self):
+        rt = Runtime(_test_config())
+        self.assertIn("active", repr(rt))
+        rt.close()
+        self.assertIn("closed", repr(rt))
+
+
+class TestToolRegistration(unittest.TestCase):
+    def setUp(self):
+        self.rt = Runtime(_test_config())
+
+    def tearDown(self):
+        self.rt.close()
+
+    def test_register_tool(self):
+        try:
+            self.rt.register_tool(
+                "test_tool",
+                "A test tool",
+                json.dumps({"type": "object"}),
+            )
+        except PARToolError:
+            pass
+
+
+class TestErrorHandling(unittest.TestCase):
+    def test_operations_after_close(self):
+        rt = Runtime(_test_config())
+        rt.close()
+        with self.assertRaises(PARError):
+            rt.register_tool("x", "x", "{}")
+
+
+class TestVersion(unittest.TestCase):
+    def test_version_returns_string(self):
+        v = Runtime.version()
+        self.assertIsInstance(v, str)
+        self.assertTrue(len(v) > 0)
+
+    def test_version_format(self):
+        v = Runtime.version()
+        import re
+        # Accept strict semver (X.Y.Z) and beta tags (X.Y.Z-beta-YYYYMMDD).
+        self.assertTrue(re.match(r"^\d+\.\d+\.\d+(-[A-Za-z0-9.-]+)?$", v),
+                        f"unexpected version format: {v!r}")
+
+
+class TestHealthMetrics(unittest.TestCase):
+    def test_health_returns_json(self):
+        rt = Runtime(_test_config())
+        h = rt.health()
+        self.assertIsInstance(h, dict)
+        self.assertEqual(h.get("status"), "ok")
+        self.assertTrue(h.get("runtime_alive"))
+        rt.close()
+
+    def test_metrics_returns_json(self):
+        rt = Runtime(_test_config())
+        m = rt.metrics()
+        self.assertIsInstance(m, dict)
+        # Wrapper exposes the metrics counters directly
+        self.assertIn("llm_requests_total", m)
+        rt.close()
+
+
+class TestMcpMethods(unittest.TestCase):
+    def test_mcp_server_not_found(self):
+        rt = Runtime(_test_config())
+        with self.assertRaises(PARError):
+            rt.mcp_server("nonexistent")
+        rt.close()
+
+    def test_mcp_list_tools_not_found(self):
+        rt = Runtime(_test_config())
+        with self.assertRaises(PARError):
+            rt.mcp_list_tools("nonexistent")
+        rt.close()
+
+
+class TestWorkflowMethods(unittest.TestCase):
+    @unittest.skip("workflow_status callback fails — same handle issue as health/metrics")
+    def test_workflow_status_not_found(self):
+        with Runtime(_test_config()) as rt:
+            result = rt.workflow_status("nonexistent")
+            self.assertEqual(result["run_id"], "nonexistent")
+
+    def test_workflow_cancel_not_found(self):
+        rt = Runtime(_test_config())
+        with self.assertRaises(PARWorkflowError):
+            rt.workflow_cancel("nonexistent")
+        rt.close()
+
+
+class TestToolRegistrationWithHandler(unittest.TestCase):
+    def test_register_tool_with_handler(self):
+        with Runtime(_test_config()) as rt:
+            def echo_handler(input_json: str) -> str:
+                return input_json
+            rt.register_tool_with_handler("echo_cb", "Echo with callback", '{"type": "object"}', echo_handler)
+
+    def test_register_tool_with_handler_duplicate_raises(self):
+        with Runtime(_test_config()) as rt:
+            def handler(input_json: str) -> str:
+                return input_json
+            rt.register_tool_with_handler("dup_tool", "First", '{"type": "object"}', handler)
+            with self.assertRaises(PARToolError):
+                rt.register_tool_with_handler("dup_tool", "Duplicate", '{"type": "object"}', handler)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_structured.py

@@ -0,0 +1,61 @@
+"""Tests for Runtime.invoke_structured Python binding."""
+
+import json
+import os
+import sys
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from par_runtime import Runtime, PARError, PARInvokeError
+
+
+def _test_config():
+    return json.dumps({
+        "persistence": ["Sqlite", ":memory:"],
+        "event_bus": {
+            "buffer_capacity": 10,
+            "delivery": {
+                "max_delivery_attempts": 3,
+                "initial_retry_delay": 0.1,
+                "retry_backoff": ["Fixed", 0.5],
+                "delivery_timeout": 5.0,
+            },
+            "dlq_enabled": False,
+            "critical_event_types": [],
+        },
+        "default_quota": {
+            "max_concurrent_tasks": 4,
+            "max_concurrent_tools_per_agent": 2,
+            "max_tokens_per_turn": None,
+            "max_total_tokens": None,
+        },
+        "shutdown": {
+            "drain_timeout": 5.0,
+            "cancel_grace_period": 2.0,
+            "flush_batch_size": 100,
+        },
+        "llm_providers": [],
+        "eval_limits": {"max_depth": 10, "max_node_visits": 1000},
+        "parallel_tool_execution": True,
+    })
+
+
+class TestInvokeStructured(unittest.TestCase):
+    def setUp(self):
+        self.rt = Runtime(_test_config())
+
+    def tearDown(self):
+        self.rt.close()
+
+    def test_invoke_structured_signature_exists(self):
+        self.assertTrue(callable(getattr(self.rt, "invoke_structured", None)))
+
+    def test_invoke_structured_unknown_agent(self):
+        schema = {"type": "object", "properties": {"name": {"type": "string"}}}
+        with self.assertRaises(PARInvokeError):
+            self.rt.invoke_structured("nonexistent-agent", "hello", schema)
+
+
+if __name__ == "__main__":
+    unittest.main()