tikuu-agent-runner 0.1.0__tar.gz

tikuu_agent_runner-0.1.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.3
+Name: tikuu-agent-runner
+Version: 0.1.0
+Summary: SDK that wraps a Tikuu agent invoke handler in a FastAPI /ping + /invoke server
+Author: Utkarsh Tiwari
+Author-email: Utkarsh Tiwari <tiwariutkarsh66@gmail.com>
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn[standard]>=0.32.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# tikuu-agent-runner
+
+Python SDK that wraps a Tikuu agent invoke handler in the HTTP surface expected
+by tikuu-api-server (`GET /ping`, `POST /invoke`).
+
+For usage, see [docs/USAGE.md](docs/USAGE.md).  
+For the HTTP contract, see [docs/API_REFERENCE.md](docs/API_REFERENCE.md).  
+For package layout, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+## Requirements
+
+- Python 3.13+
+- [uv](https://docs.astral.sh/uv/)
+
+## Setup
+
+Install dependencies into a local virtual environment:
+
+```bash
+uv sync
+```

tikuu_agent_runner-0.1.0/README.md

@@ -0,0 +1,21 @@
+# tikuu-agent-runner
+
+Python SDK that wraps a Tikuu agent invoke handler in the HTTP surface expected
+by tikuu-api-server (`GET /ping`, `POST /invoke`).
+
+For usage, see [docs/USAGE.md](docs/USAGE.md).  
+For the HTTP contract, see [docs/API_REFERENCE.md](docs/API_REFERENCE.md).  
+For package layout, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+## Requirements
+
+- Python 3.13+
+- [uv](https://docs.astral.sh/uv/)
+
+## Setup
+
+Install dependencies into a local virtual environment:
+
+```bash
+uv sync
+```

tikuu_agent_runner-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "tikuu-agent-runner"
+version = "0.1.0"
+description = "SDK that wraps a Tikuu agent invoke handler in a FastAPI /ping + /invoke server"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.32.0",
+]
+
+[[project.authors]]
+name = "Utkarsh Tiwari"
+email = "tiwariutkarsh66@gmail.com"
+
+[build-system]
+requires = ["uv_build>=0.12.1,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["httpx>=0.28.1"]

tikuu_agent_runner-0.1.0/pyproject.toml.orig

@@ -0,0 +1,22 @@
+[project]
+name = "tikuu-agent-runner"
+version = "0.1.0"
+description = "SDK that wraps a Tikuu agent invoke handler in a FastAPI /ping + /invoke server"
+readme = "README.md"
+authors = [
+    { name = "Utkarsh Tiwari", email = "tiwariutkarsh66@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.32.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.1,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "httpx>=0.28.1",
+]

tikuu_agent_runner-0.1.0/src/tikuu_agent_runner/__init__.py

@@ -0,0 +1,13 @@
+"""Tikuu Agent Runner: decorate an invoke handler and serve `/ping` + `/invoke`.
+
+The public surface is intentionally small — import ``TikuuAgentRunner`` and
+register one async ``(payload, context)`` handler before calling ``run()``.
+"""
+
+from tikuu_agent_runner.errors import RunnerConfigurationError
+from tikuu_agent_runner.runner import TikuuAgentRunner
+
+__all__ = [
+    "RunnerConfigurationError",
+    "TikuuAgentRunner",
+]

tikuu_agent_runner-0.1.0/src/tikuu_agent_runner/app.py

@@ -0,0 +1,126 @@
+"""FastAPI application factory for agent containers.
+
+Owns only HTTP concerns: readiness (``GET /ping``) and invoke
+(``POST /invoke``). Business logic stays in the user-supplied handler.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from fastapi import FastAPI, Request, Response, status
+from fastapi.encoders import jsonable_encoder
+from fastapi.responses import JSONResponse
+
+from tikuu_agent_runner.constants import INVOKE_PATH, PING_PATH
+from tikuu_agent_runner.context import build_invoke_context
+from tikuu_agent_runner.handler import InvokeHandler
+
+logger = logging.getLogger(__name__)
+
+
+def create_app(invoke_handler: InvokeHandler) -> FastAPI:
+    """Build a FastAPI app wired to a single invoke handler.
+
+    Args:
+        invoke_handler: Async ``(payload, context)`` callable registered via
+            ``TikuuAgentRunner.invoke``.
+
+    Returns:
+        A configured FastAPI application ready for uvicorn.
+    """
+    app = FastAPI(
+        title="Tikuu Agent Runner",
+        description=(
+            "In-container HTTP surface for Tikuu agents: "
+            f"`GET {PING_PATH}` for readiness and "
+            f"`POST {INVOKE_PATH}` for invoke."
+        ),
+        version="0.1.0",
+    )
+
+    @app.get(
+        PING_PATH,
+        status_code=status.HTTP_200_OK,
+        summary="Readiness probe",
+        response_description="Empty 200 when the process is ready to invoke",
+    )
+    async def ping() -> Response:
+        """Return HTTP 200 so the API server can treat the container as ready.
+
+        Body is intentionally empty: the probe only checks status code.
+        """
+        return Response(status_code=status.HTTP_200_OK)
+
+    @app.post(
+        INVOKE_PATH,
+        summary="Invoke agent handler",
+        response_description="JSON body produced by the user handler",
+    )
+    async def invoke(request: Request) -> JSONResponse:
+        """Parse JSON body, build context, call the user handler, return JSON.
+
+        Fail-cheap order: decode body → require JSON object → call handler →
+        encode result. Handler exceptions become 500 without crashing the
+        process so the container stays ready for later invokes.
+        """
+        try:
+            payload = await _parse_payload(request)
+        except json.JSONDecodeError:
+            return JSONResponse(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                content={"detail": "Request body must be valid JSON"},
+            )
+        except _PayloadNotObjectError:
+            return JSONResponse(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                content={"detail": "Request body must be a JSON object"},
+            )
+
+        context = build_invoke_context(request.headers)
+
+        try:
+            result = await invoke_handler(payload, context)
+        except Exception:
+            # Log full traceback for operators; keep the HTTP body generic so
+            # agent internals are not leaked to API clients.
+            logger.exception("Invoke handler raised an unexpected error")
+            return JSONResponse(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                content={"detail": "Invoke handler failed"},
+            )
+
+        try:
+            content = jsonable_encoder(result)
+        except Exception:
+            logger.exception("Invoke handler return value is not JSON-serializable")
+            return JSONResponse(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                content={"detail": "Invoke handler returned non-JSON value"},
+            )
+
+        return JSONResponse(status_code=status.HTTP_200_OK, content=content)
+
+    return app
+
+
+class _PayloadNotObjectError(Exception):
+    """Internal: body decoded as JSON but was not a JSON object (dict)."""
+
+
+async def _parse_payload(request: Request) -> dict[str, Any]:
+    """Decode the request body as a JSON object.
+
+    The API server validates JSON before proxying; this re-check keeps local
+    ``runner.run()`` usage safe when callers hit the agent directly.
+    """
+    body = await request.body()
+    # Empty body is not a valid JSON object under our contract; reject early.
+    if len(body) == 0:
+        raise _PayloadNotObjectError
+    data = json.loads(body)
+    if not isinstance(data, dict):
+        raise _PayloadNotObjectError
+    return data

tikuu_agent_runner-0.1.0/src/tikuu_agent_runner/constants.py

@@ -0,0 +1,22 @@
+"""Shared constants for the agent HTTP contract.
+
+Kept in one module so paths and header names stay aligned with
+``tikuu-api-server`` invoke proxy defaults (``/ping``, ``/invoke``,
+``X-Session-Id``).
+"""
+
+# Paths the API server readiness probe and invoke proxy call on the container.
+PING_PATH = "/ping"
+INVOKE_PATH = "/invoke"
+
+# Canonical session header forwarded by the API server to the agent container.
+SESSION_HEADER = "X-Session-Id"
+
+# Bind defaults: container port published by the API is 8000/tcp, so the
+# process must listen on all interfaces inside the container.
+DEFAULT_HOST = "0.0.0.0"
+DEFAULT_PORT = 8000
+
+# Exact parameter names required on an ``@runner.invoke`` handler.
+PAYLOAD_PARAM = "payload"
+CONTEXT_PARAM = "context"

tikuu_agent_runner-0.1.0/src/tikuu_agent_runner/context.py

@@ -0,0 +1,49 @@
+"""Build the invoke ``context`` dict from inbound HTTP metadata.
+
+Separated from the FastAPI route so context construction stays easy to
+unit-test and can grow (more headers / env) without touching routing.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from tikuu_agent_runner.constants import SESSION_HEADER
+
+
+def build_invoke_context(headers: Mapping[str, str]) -> dict[str, str]:
+    """Return metadata for the invoke handler's ``context`` argument.
+
+    ``session_id`` is included only when ``X-Session-Id`` is present and
+    non-empty after stripping whitespace. Missing or blank headers omit the
+    key entirely so handlers can use ``context.get("session_id")``.
+
+    Args:
+        headers: Inbound request headers (case-insensitive lookup supported
+            via Starlette's ``Headers`` or a plain mapping).
+
+    Returns:
+        A new dict of context fields for the user handler.
+    """
+    context: dict[str, str] = {}
+    # Starlette Headers support case-insensitive get; plain dicts may not,
+    # so normalize by trying the canonical name then a lower-case scan.
+    session_id = _get_header(headers, SESSION_HEADER)
+    if session_id is not None:
+        stripped = session_id.strip()
+        if stripped:
+            context["session_id"] = stripped
+    return context
+
+
+def _get_header(headers: Mapping[str, str], name: str) -> str | None:
+    """Read a header by name, tolerant of case differences in plain dicts."""
+    # Prefer Mapping.get when the mapping already does case-insensitive lookup.
+    direct = headers.get(name)
+    if direct is not None:
+        return direct
+    target = name.lower()
+    for key, value in headers.items():
+        if key.lower() == target:
+            return value
+    return None

tikuu_agent_runner-0.1.0/src/tikuu_agent_runner/errors.py

@@ -0,0 +1,15 @@
+"""Domain errors raised by the runner before the ASGI server starts.
+
+These are fail-fast configuration mistakes (wrong decorator usage), not
+HTTP-layer errors. Request-time failures are mapped to status codes inside
+the FastAPI routes instead.
+"""
+
+
+class RunnerConfigurationError(Exception):
+    """Raised when the runner is misconfigured before serving requests.
+
+    Examples: decorating a second invoke handler, calling ``run()`` with no
+    handler, or registering a handler whose signature is not
+    ``(payload, context)``.
+    """

tikuu_agent_runner-0.1.0/src/tikuu_agent_runner/handler.py

@@ -0,0 +1,73 @@
+"""Invoke handler typing and signature validation.
+
+The public contract is a single async callable named parameters
+``payload`` then ``context``. Validation runs at decoration time so
+miswired workflows fail before the process listens for traffic.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from tikuu_agent_runner.constants import CONTEXT_PARAM, PAYLOAD_PARAM
+from tikuu_agent_runner.errors import RunnerConfigurationError
+
+# User handler: payload and context are dicts; return value becomes JSON.
+InvokeHandler = Callable[[dict[str, Any], dict[str, Any]], Awaitable[Any]]
+
+
+def validate_invoke_handler(func: Callable[..., Any]) -> InvokeHandler:
+    """Ensure ``func`` is an async ``(payload, context)`` handler.
+
+    Args:
+        func: Candidate decorated by ``@runner.invoke``.
+
+    Returns:
+        The same function, typed as ``InvokeHandler``.
+
+    Raises:
+        RunnerConfigurationError: Sync function, wrong arity, or parameter
+            names/order that are not exactly ``payload``, ``context``.
+    """
+    if not inspect.iscoroutinefunction(func):
+        raise RunnerConfigurationError(
+            "@runner.invoke requires an async def handler"
+        )
+
+    signature = inspect.signature(func)
+    params = list(signature.parameters.values())
+    # Reject *args/**kwargs and defaults so the contract stays explicit.
+    if len(params) != 2:
+        raise RunnerConfigurationError(
+            "@runner.invoke handler must accept exactly two parameters: "
+            f"{PAYLOAD_PARAM}, {CONTEXT_PARAM}"
+        )
+
+    expected = (PAYLOAD_PARAM, CONTEXT_PARAM)
+    actual = tuple(param.name for param in params)
+    if actual != expected:
+        raise RunnerConfigurationError(
+            "@runner.invoke handler parameters must be named "
+            f"{PAYLOAD_PARAM}, {CONTEXT_PARAM} in that order "
+            f"(got {', '.join(actual)})"
+        )
+
+    for param in params:
+        if param.kind not in (
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            inspect.Parameter.POSITIONAL_ONLY,
+            inspect.Parameter.KEYWORD_ONLY,
+        ):
+            raise RunnerConfigurationError(
+                "@runner.invoke handler must not use *args or **kwargs"
+            )
+        if param.default is not inspect.Parameter.empty:
+            # Defaults would hide missing payload/context; keep the call site
+            # always supplying both from the HTTP layer.
+            raise RunnerConfigurationError(
+                "@runner.invoke handler parameters must not have defaults"
+            )
+
+    return func  # type: ignore[return-value]

tikuu_agent_runner-0.1.0/src/tikuu_agent_runner/runner.py

@@ -0,0 +1,106 @@
+"""``TikuuAgentRunner``: decorate one invoke handler and serve HTTP.
+
+Typical usage lives in a workflow module::
+
+    from tikuu_agent_runner import TikuuAgentRunner
+
+    runner = TikuuAgentRunner()
+
+    @runner.invoke
+    async def invoke_handler(payload: dict, context: dict) -> dict:
+        return {"message": "Hello, world!"}
+
+    if __name__ == "__main__":
+        runner.run()
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from fastapi import FastAPI
+
+from tikuu_agent_runner.app import create_app
+from tikuu_agent_runner.constants import DEFAULT_HOST, DEFAULT_PORT
+from tikuu_agent_runner.errors import RunnerConfigurationError
+from tikuu_agent_runner.handler import InvokeHandler, validate_invoke_handler
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class TikuuAgentRunner:
+    """Host a single agent invoke handler behind FastAPI ``/ping`` and ``/invoke``.
+
+    Attributes:
+        host: Bind address used by ``run()`` (default ``0.0.0.0`` for Docker).
+        port: Bind port used by ``run()`` (default ``8000`` to match the API
+            server's ``AGENT_CONTAINER_PORT``).
+    """
+
+    def __init__(
+        self,
+        *,
+        host: str = DEFAULT_HOST,
+        port: int = DEFAULT_PORT,
+    ) -> None:
+        """Create a runner with optional bind overrides for local development.
+
+        Args:
+            host: Interface uvicorn should bind.
+            port: TCP port uvicorn should bind.
+        """
+        self.host = host
+        self.port = port
+        # None until @invoke runs; run() refuses to start without a handler so
+        # /ping never advertises readiness for a container that cannot invoke.
+        self._invoke_handler: InvokeHandler | None = None
+
+    def invoke(self, func: F) -> F:
+        """Register ``func`` as the sole ``POST /invoke`` handler.
+
+        The decorated function must be ``async def`` with parameters named
+        ``payload`` and ``context`` (in that order). A second decoration on
+        the same runner instance raises ``RunnerConfigurationError``.
+
+        Args:
+            func: Async handler receiving ``(payload, context)`` dicts.
+
+        Returns:
+            The original function (unwrapped) so tests can call it directly.
+
+        Raises:
+            RunnerConfigurationError: Handler already set or signature invalid.
+        """
+        if self._invoke_handler is not None:
+            raise RunnerConfigurationError(
+                "Only one @runner.invoke handler may be registered"
+            )
+        self._invoke_handler = validate_invoke_handler(func)
+        return func
+
+    def build_app(self) -> FastAPI:
+        """Return the FastAPI app for this runner (useful in tests).
+
+        Raises:
+            RunnerConfigurationError: No handler registered yet.
+        """
+        if self._invoke_handler is None:
+            raise RunnerConfigurationError(
+                "No @runner.invoke handler registered; call run() only after "
+                "decorating an invoke handler"
+            )
+        return create_app(self._invoke_handler)
+
+    def run(self) -> None:
+        """Start uvicorn and block until the server exits.
+
+        Raises:
+            RunnerConfigurationError: No handler registered yet.
+        """
+        # Import uvicorn lazily so importing the SDK does not require the
+        # server stack until the process actually listens.
+        import uvicorn
+
+        app = self.build_app()
+        uvicorn.run(app, host=self.host, port=self.port)