autotune-hook 0.1.0__tar.gz

autotune_hook-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,37 @@
+# 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/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "autotune-hook"
+version = "0.1.0"
+description = "Autotune Hook"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "LicenseRef-Proprietary"
+authors = [{ name = "Autotune" }]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+autotune_hook = ["py.typed"]

autotune_hook-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

autotune_hook-0.1.0/src/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-0.1.0/src/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-0.1.0/src/autotune_hook/py.typed

@@ -0,0 +1 @@
+

autotune_hook-0.1.0/src/autotune_hook.egg-info/PKG-INFO

@@ -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/src/autotune_hook.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+src/autotune_hook/__init__.py
+src/autotune_hook/hook.py
+src/autotune_hook/py.typed
+src/autotune_hook.egg-info/PKG-INFO
+src/autotune_hook.egg-info/SOURCES.txt
+src/autotune_hook.egg-info/dependency_links.txt
+src/autotune_hook.egg-info/top_level.txt
+tests/test_hook.py

autotune_hook-0.1.0/src/autotune_hook.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

autotune_hook-0.1.0/src/autotune_hook.egg-info/top_level.txt

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

autotune_hook-0.1.0/tests/test_hook.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+import time
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any
+
+from autotune_hook import AutotuneHook, with_session
+
+
+class HookHandler(BaseHTTPRequestHandler):
+    preflight_responses: list[Any] = [True]
+    preflights: list[dict[str, Any]] = []
+    reports: list[dict[str, Any]] = []
+
+    def do_POST(self) -> None:
+        length = int(self.headers.get("content-length", "0"))
+        body = json.loads(self.rfile.read(length).decode("utf-8"))
+        if "run" in body:
+            self.__class__.reports.append(body)
+            self.send_response(202)
+            self.send_header("content-type", "application/json")
+            self.end_headers()
+            self.wfile.write(b'{"status":"recorded"}')
+            return
+
+        self.__class__.preflights.append(body)
+        response = (
+            self.__class__.preflight_responses.pop(0)
+            if self.__class__.preflight_responses
+            else True
+        )
+        self.send_response(200)
+        self.send_header("content-type", "application/json")
+        self.end_headers()
+        self.wfile.write(json.dumps(response).encode("utf-8"))
+
+    def log_message(self, _format: str, *_args: Any) -> None:
+        return
+
+
+class StubServer:
+    def __enter__(self) -> "StubServer":
+        HookHandler.preflight_responses = [True]
+        HookHandler.preflights = []
+        HookHandler.reports = []
+        self.server = ThreadingHTTPServer(("127.0.0.1", 0), HookHandler)
+        self.thread = threading.Thread(target=self.server.serve_forever, daemon=True)
+        self.thread.start()
+        host, port = self.server.server_address
+        self.url = f"http://{host}:{port}"
+        return self
+
+    def __exit__(self, *_exc: Any) -> None:
+        self.server.shutdown()
+        self.server.server_close()
+        self.thread.join(timeout=1)
+
+
+def wait_for_report(count: int = 1) -> list[dict[str, Any]]:
+    deadline = time.time() + 2
+    while time.time() < deadline:
+        if len(HookHandler.reports) >= count:
+            return HookHandler.reports
+        time.sleep(0.02)
+    return HookHandler.reports
+
+
+async def wait_for_report_async(count: int = 1) -> list[dict[str, Any]]:
+    deadline = time.time() + 2
+    while time.time() < deadline:
+        if len(HookHandler.reports) >= count:
+            return HookHandler.reports
+        await asyncio.sleep(0.02)
+    return HookHandler.reports
+
+
+class AutotuneHookTest(unittest.TestCase):
+    def test_shadow_wrapper_reports_response(self) -> None:
+        with StubServer() as server:
+            hook = AutotuneHook(endpoint=server.url, workflow="email-triage", timeout_seconds=1)
+            payload = {
+                "model": "openrouter/stub",
+                "messages": [{"role": "user", "content": "hi"}],
+            }
+            provider_response = {
+                "choices": [
+                    {"message": {"role": "assistant", "content": "hello"}}
+                ],
+                "usage": {"prompt_tokens": 1, "completion_tokens": 1},
+            }
+
+            result = hook.openrouter_call(payload, lambda: provider_response)
+
+            self.assertEqual(result, provider_response)
+            self.assertEqual(len(HookHandler.preflights), 1)
+            self.assertEqual(
+                HookHandler.preflights[0]["request"]["metadata"]["workflow_name"],
+                "email-triage",
+            )
+            reports = wait_for_report()
+            self.assertEqual(len(reports), 1)
+            self.assertEqual(reports[0]["run"]["response"], provider_response)
+            self.assertEqual(
+                reports[0]["run"]["request"]["metadata"]["workflow_name"],
+                "email-triage",
+            )
+
+    def test_proxy_response_short_circuits_provider_call(self) -> None:
+        proxy_response = {
+            "id": "chatcmpl-at",
+            "choices": [{"message": {"role": "assistant", "content": "from autotune"}}],
+        }
+        with StubServer() as server:
+            HookHandler.preflight_responses = [proxy_response]
+            hook = AutotuneHook(endpoint=server.url)
+            called = False
+
+            def provider() -> dict[str, Any]:
+                nonlocal called
+                called = True
+                return {"unexpected": True}
+
+            result = hook.openrouter_call({"messages": []}, provider)
+
+            self.assertEqual(result, proxy_response)
+            self.assertFalse(called)
+            self.assertEqual(HookHandler.reports, [])
+
+    def test_decorator_infers_kwargs_and_session(self) -> None:
+        with StubServer() as server:
+            hook = AutotuneHook(endpoint=server.url, workflow="fallback")
+
+            @hook.openrouter()
+            def call_openrouter(**payload: Any) -> dict[str, Any]:
+                return {
+                    "choices": [
+                        {"message": {"role": "assistant", "content": payload["messages"][0]["content"]}}
+                    ]
+                }
+
+            with with_session(session_id="session-1", user_id="user-1", workflow="session-wf"):
+                result = call_openrouter(
+                    model="stub",
+                    messages=[{"role": "user", "content": "decorated"}],
+                )
+
+            self.assertEqual(result["choices"][0]["message"]["content"], "decorated")
+            reports = wait_for_report()
+            metadata = reports[0]["run"]["request"]["metadata"]
+            self.assertEqual(metadata["session_id"], "session-1")
+            self.assertEqual(metadata["user_id"], "user-1")
+            self.assertEqual(metadata["workflow_name"], "session-wf")
+
+    def test_autotune_unavailable_falls_back_to_provider(self) -> None:
+        hook = AutotuneHook(endpoint="http://127.0.0.1:1", timeout_seconds=0.05)
+        result = hook.openrouter_call({"messages": []}, lambda: {"ok": True})
+        self.assertEqual(result, {"ok": True})
+
+
+class AutotuneHookAsyncTest(unittest.IsolatedAsyncioTestCase):
+    async def test_async_shadow_wrapper(self) -> None:
+        with StubServer() as server:
+            hook = AutotuneHook(endpoint=server.url, workflow="async-wf")
+
+            async def provider() -> dict[str, Any]:
+                await asyncio.sleep(0)
+                return {"choices": [{"message": {"content": "async"}}]}
+
+            result = await hook.openrouter_call_async({"messages": []}, provider)
+
+            self.assertEqual(result["choices"][0]["message"]["content"], "async")
+            reports = await wait_for_report_async()
+            self.assertEqual(reports[0]["run"]["request"]["metadata"]["workflow_name"], "async-wf")
+
+
+if __name__ == "__main__":
+    unittest.main()