autotune-hook 0.1.0__py3-none-any.whl

autotune_hook/__init__.py

@@ -0,0 +1,18 @@
+from .hook import (
+    AutotuneHook,
+    AutotuneHookConfig,
+    autotune_openrouter,
+    current_session,
+    with_session,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AutotuneHook",
+    "AutotuneHookConfig",
+    "autotune_openrouter",
+    "current_session",
+    "with_session",
+    "__version__",
+]

autotune_hook/hook.py

@@ -0,0 +1,423 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import contextvars
+import datetime as _dt
+import functools
+import inspect
+import json
+import logging
+import os
+import threading
+import time
+import uuid
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Callable, Iterator, Mapping, MutableMapping, TypeVar
+
+LOGGER = logging.getLogger("autotune_hook")
+T = TypeVar("T")
+
+JsonMap = dict[str, Any]
+RequestExtractor = Callable[[tuple[Any, ...], dict[str, Any]], Mapping[str, Any] | None]
+ResponseAdapter = Callable[[Any], T]
+
+
+_session: contextvars.ContextVar[JsonMap] = contextvars.ContextVar(
+    "autotune_session",
+    default={},
+)
+
+
+@dataclass(frozen=True)
+class AutotuneHookConfig:
+    endpoint: str | None = None
+    api_key: str | None = None
+    workflow: str | None = None
+    project: str | None = None
+    environment: str | None = None
+    session_id: str | None = None
+    user_id: str | None = None
+    timeout_seconds: float = 2.0
+
+    @classmethod
+    def from_env(cls) -> "AutotuneHookConfig":
+        return cls(
+            endpoint=os.getenv("AUTOTUNE_ENDPOINT"),
+            api_key=os.getenv("AUTOTUNE_API_KEY"),
+            workflow=os.getenv("AUTOTUNE_WORKFLOW"),
+            project=os.getenv("AUTOTUNE_PROJECT"),
+            environment=os.getenv("AUTOTUNE_ENVIRONMENT"),
+            session_id=os.getenv("AUTOTUNE_SESSION_ID"),
+            user_id=os.getenv("AUTOTUNE_USER_ID"),
+            timeout_seconds=float(os.getenv("AUTOTUNE_HOOK_TIMEOUT", "2.0")),
+        )
+
+
+class AutotuneHook:
+    def __init__(
+        self,
+        *,
+        endpoint: str | None = None,
+        api_key: str | None = None,
+        workflow: str | None = None,
+        project: str | None = None,
+        environment: str | None = None,
+        session_id: str | None = None,
+        user_id: str | None = None,
+        timeout_seconds: float | None = None,
+    ) -> None:
+        env = AutotuneHookConfig.from_env()
+        self.config = AutotuneHookConfig(
+            endpoint=endpoint if endpoint is not None else env.endpoint,
+            api_key=api_key if api_key is not None else env.api_key,
+            workflow=workflow if workflow is not None else env.workflow,
+            project=project if project is not None else env.project,
+            environment=environment if environment is not None else env.environment,
+            session_id=session_id if session_id is not None else env.session_id,
+            user_id=user_id if user_id is not None else env.user_id,
+            timeout_seconds=(
+                timeout_seconds
+                if timeout_seconds is not None
+                else env.timeout_seconds
+            ),
+        )
+
+    def openrouter_call(
+        self,
+        request: Mapping[str, Any],
+        call: Callable[[], T],
+        *,
+        metadata: Mapping[str, Any] | None = None,
+        response_adapter: ResponseAdapter[T] | None = None,
+    ) -> T:
+        """Wrap one OpenRouter call.
+
+        AutoTune receives the request first. If cloud policy returns a JSON
+        boolean, this method executes ``call`` and reports its observed output in
+        the background. If AutoTune returns a provider response, that response is
+        returned directly, optionally through ``response_adapter``.
+        """
+        started_at = _now_iso()
+        started = time.perf_counter()
+        run_id = str(uuid.uuid4())
+        request_body = _with_metadata(dict(request), self._metadata(metadata))
+        decision = self._preflight(run_id, request_body, started_at)
+        should_report = decision is _SHADOW
+        if decision is not _SHADOW and decision is not _SHADOW_NO_REPORT:
+            return _adapt_response(decision, response_adapter)
+
+        try:
+            response = call()
+        except Exception as exc:
+            latency_ms = int((time.perf_counter() - started) * 1000)
+            if should_report:
+                self._report_background(
+                    run_id=run_id,
+                    request=request_body,
+                    started_at=started_at,
+                    latency_ms=latency_ms,
+                    error=_serialize_error(exc),
+                )
+            raise
+
+        latency_ms = int((time.perf_counter() - started) * 1000)
+        if should_report:
+            self._report_background(
+                run_id=run_id,
+                request=request_body,
+                started_at=started_at,
+                latency_ms=latency_ms,
+                response=_jsonish(response),
+                status_code=_read_status_code(response),
+            )
+        return response
+
+    async def openrouter_call_async(
+        self,
+        request: Mapping[str, Any],
+        call: Callable[[], Any],
+        *,
+        metadata: Mapping[str, Any] | None = None,
+        response_adapter: ResponseAdapter[T] | None = None,
+    ) -> Any:
+        started_at = _now_iso()
+        started = time.perf_counter()
+        run_id = str(uuid.uuid4())
+        request_body = _with_metadata(dict(request), self._metadata(metadata))
+        decision = await asyncio.to_thread(self._preflight, run_id, request_body, started_at)
+        should_report = decision is _SHADOW
+        if decision is not _SHADOW and decision is not _SHADOW_NO_REPORT:
+            return _adapt_response(decision, response_adapter)
+
+        try:
+            response = call()
+            if inspect.isawaitable(response):
+                response = await response
+        except Exception as exc:
+            latency_ms = int((time.perf_counter() - started) * 1000)
+            if should_report:
+                self._report_task(
+                    run_id=run_id,
+                    request=request_body,
+                    started_at=started_at,
+                    latency_ms=latency_ms,
+                    error=_serialize_error(exc),
+                )
+            raise
+
+        latency_ms = int((time.perf_counter() - started) * 1000)
+        if should_report:
+            self._report_task(
+                run_id=run_id,
+                request=request_body,
+                started_at=started_at,
+                latency_ms=latency_ms,
+                response=_jsonish(response),
+                status_code=_read_status_code(response),
+            )
+        return response
+
+    def openrouter(
+        self,
+        *,
+        request_extractor: RequestExtractor | None = None,
+        metadata: Mapping[str, Any] | None = None,
+        response_adapter: ResponseAdapter[Any] | None = None,
+    ) -> Callable[[Callable[..., T]], Callable[..., T]]:
+        extractor = request_extractor or _default_request_extractor
+
+        def decorator(func: Callable[..., T]) -> Callable[..., T]:
+            if inspect.iscoroutinefunction(func):
+
+                @functools.wraps(func)
+                async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                    request = extractor(args, kwargs)
+                    if request is None:
+                        LOGGER.warning("AutoTune hook could not infer OpenRouter request")
+                        return await func(*args, **kwargs)  # type: ignore[misc]
+                    return await self.openrouter_call_async(
+                        request,
+                        lambda: func(*args, **kwargs),
+                        metadata=metadata,
+                        response_adapter=response_adapter,
+                    )
+
+                return async_wrapper  # type: ignore[return-value]
+
+            @functools.wraps(func)
+            def wrapper(*args: Any, **kwargs: Any) -> T:
+                request = extractor(args, kwargs)
+                if request is None:
+                    LOGGER.warning("AutoTune hook could not infer OpenRouter request")
+                    return func(*args, **kwargs)
+                return self.openrouter_call(
+                    request,
+                    lambda: func(*args, **kwargs),
+                    metadata=metadata,
+                    response_adapter=response_adapter,
+                )
+
+            return wrapper
+
+        return decorator
+
+    def _metadata(self, metadata: Mapping[str, Any] | None = None) -> JsonMap:
+        session = current_session()
+        pairs = {
+            "workflow_name": session.get("workflow") or self.config.workflow,
+            "project_name": session.get("project") or self.config.project,
+            "environment_name": session.get("environment") or self.config.environment,
+            "session_id": session.get("session_id") or self.config.session_id,
+            "user_id": session.get("user_id") or self.config.user_id,
+        }
+        merged = {key: value for key, value in pairs.items() if value}
+        if metadata:
+            merged.update(dict(metadata))
+        return merged
+
+    def _hook_url(self) -> str | None:
+        if not self.config.endpoint:
+            return None
+        return (
+            self.config.endpoint.rstrip("/")
+            + "/v1/hooks/openrouter/chat/completions"
+        )
+
+    def _preflight(self, run_id: str, request: JsonMap, started_at: str) -> Any:
+        url = self._hook_url()
+        if not url:
+            return _SHADOW
+        payload = {
+            "provider": "openrouter",
+            "run_id": run_id,
+            "request": request,
+            "started_at": started_at,
+            "metadata": request.get("metadata", {}),
+        }
+        response = self._post_json(url, payload)
+        if response is _HTTP_ERROR:
+            return _SHADOW_NO_REPORT
+        return _SHADOW if isinstance(response, bool) else response
+
+    def _report_background(self, **run: Any) -> None:
+        thread = threading.Thread(target=self._report, kwargs=run, daemon=True)
+        thread.start()
+
+    def _report_task(self, **run: Any) -> None:
+        async def send() -> None:
+            await asyncio.to_thread(self._report, **run)
+
+        try:
+            asyncio.create_task(send())
+        except RuntimeError:
+            self._report_background(**run)
+
+    def _report(self, **run: Any) -> None:
+        url = self._hook_url()
+        if not url:
+            return
+        payload = {
+            "run": {
+                "run_id": run["run_id"],
+                "provider": "openrouter",
+                "request": run["request"],
+                "started_at": run["started_at"],
+                "latency_ms": run["latency_ms"],
+                "metadata": run["request"].get("metadata", {}),
+            }
+        }
+        if run.get("response") is not None:
+            payload["run"]["response"] = run["response"]
+        if run.get("error") is not None:
+            payload["run"]["error"] = run["error"]
+        if run.get("status_code") is not None:
+            payload["run"]["status_code"] = run["status_code"]
+        self._post_json(url, payload)
+
+    def _post_json(self, url: str, payload: Mapping[str, Any]) -> Any:
+        body = json.dumps(_jsonish(payload), separators=(",", ":")).encode("utf-8")
+        headers = {"content-type": "application/json"}
+        if self.config.api_key:
+            headers["authorization"] = f"Bearer {self.config.api_key}"
+        request = urllib.request.Request(url, data=body, headers=headers, method="POST")
+        try:
+            with urllib.request.urlopen(
+                request,
+                timeout=self.config.timeout_seconds,
+            ) as response:
+                raw = response.read()
+                if not raw:
+                    return None
+                content_type = response.headers.get("content-type", "")
+                if "application/json" in content_type:
+                    return json.loads(raw.decode("utf-8"))
+                return raw.decode("utf-8", "replace")
+        except (OSError, urllib.error.URLError, urllib.error.HTTPError) as exc:
+            LOGGER.warning("AutoTune hook request failed: %s", exc)
+            return _HTTP_ERROR
+
+
+def autotune_openrouter(**options: Any) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """Convenience decorator using environment-backed configuration."""
+    return AutotuneHook().openrouter(**options)
+
+
+@contextlib.contextmanager
+def with_session(**context: Any) -> Iterator[None]:
+    parent = current_session()
+    token = _session.set({**parent, **{k: v for k, v in context.items() if v}})
+    try:
+        yield
+    finally:
+        _session.reset(token)
+
+
+def current_session() -> JsonMap:
+    return dict(_session.get({}))
+
+
+def _default_request_extractor(
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+) -> Mapping[str, Any] | None:
+    if args and isinstance(args[0], Mapping):
+        return args[0]
+    request = kwargs.get("request")
+    if isinstance(request, Mapping):
+        return request
+    if kwargs:
+        return kwargs
+    return None
+
+
+def _with_metadata(request: MutableMapping[str, Any], metadata: Mapping[str, Any]) -> JsonMap:
+    existing = request.get("metadata")
+    request["metadata"] = {
+        **(dict(existing) if isinstance(existing, Mapping) else {}),
+        **dict(metadata),
+    }
+    return dict(request)
+
+
+def _adapt_response(value: Any, adapter: ResponseAdapter[T] | None) -> T:
+    return adapter(value) if adapter else value
+
+
+def _jsonish(value: Any) -> Any:
+    if value is None or isinstance(value, (bool, int, float, str)):
+        return value
+    if isinstance(value, Mapping):
+        return {str(key): _jsonish(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple, set)):
+        return [_jsonish(item) for item in value]
+    model_dump = getattr(value, "model_dump", None)
+    if callable(model_dump):
+        try:
+            return _jsonish(model_dump(mode="json"))
+        except TypeError:
+            return _jsonish(model_dump())
+    to_dict = getattr(value, "dict", None)
+    if callable(to_dict):
+        return _jsonish(to_dict())
+    json_method = getattr(value, "json", None)
+    if callable(json_method):
+        try:
+            parsed = json_method()
+            return _jsonish(parsed)
+        except Exception:
+            pass
+    text = getattr(value, "text", None)
+    if isinstance(text, str):
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError:
+            return text
+    return str(value)
+
+
+def _read_status_code(value: Any) -> int | None:
+    status = getattr(value, "status_code", None)
+    return status if isinstance(status, int) else None
+
+
+def _serialize_error(exc: BaseException) -> JsonMap:
+    return {
+        "type": exc.__class__.__name__,
+        "message": str(exc),
+    }
+
+
+def _now_iso() -> str:
+    return _dt.datetime.now(_dt.timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+class _Sentinel:
+    pass
+
+
+_SHADOW = _Sentinel()
+_SHADOW_NO_REPORT = _Sentinel()
+_HTTP_ERROR = _Sentinel()

autotune_hook/py.typed

@@ -0,0 +1 @@
+

autotune_hook-0.1.0.dist-info/METADATA

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: autotune-hook
+Version: 0.1.0
+Summary: Autotune Hook
+Author: Autotune
+License-Expression: LicenseRef-Proprietary
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Autotune Hook
+
+Python hook for wrapping OpenRouter calls with AutoTune workflow policy.
+
+```python
+from autotune_hook import AutotuneHook
+
+hook = AutotuneHook(workflow="email-triage")
+
+def call_openrouter(payload):
+    return hook.openrouter_call(
+        payload,
+        lambda: openrouter_client.chat.completions.create(**payload),
+    )
+```
+
+Decorator form:
+
+```python
+@hook.openrouter()
+def call_openrouter(**payload):
+    return openrouter_client.chat.completions.create(**payload)
+```
+
+Configuration defaults to environment variables:
+
+- `AUTOTUNE_ENDPOINT`
+- `AUTOTUNE_API_KEY`
+- `AUTOTUNE_WORKFLOW`
+- `AUTOTUNE_PROJECT`
+- `AUTOTUNE_ENVIRONMENT`
+- `AUTOTUNE_SESSION_ID`
+- `AUTOTUNE_USER_ID`
+
+The hook sends the OpenRouter request to AutoTune first. A JSON boolean response
+means shadow mode, so the wrapped provider call executes and its output is
+reported in the background. A non-boolean AutoTune response is returned directly.

autotune_hook-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+autotune_hook/__init__.py,sha256=bDHZCVWjkNwW31pccjfBjY6Rkf8GnkrXg7nWAgv3g9Q,301
+autotune_hook/hook.py,sha256=ASoCgWw_epT07G8MI5Kv_UJ7PYksvyvEySpTGRNwnOo,14759
+autotune_hook/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+autotune_hook-0.1.0.dist-info/METADATA,sha256=xZeJ8jILL8d-BG8q7pRzKQtRJ_iA8u4mxMMT5PvPHTc,1322
+autotune_hook-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+autotune_hook-0.1.0.dist-info/top_level.txt,sha256=DxfTuGA08Jo3AzAXFBl2ckYVSD0jfB33EIUANJ9gGZw,14
+autotune_hook-0.1.0.dist-info/RECORD,,

autotune_hook-0.1.0.dist-info/WHEEL

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

autotune_hook-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+autotune_hook