autotune-hook 0.1.1

Autotune Hook

Autotune Hook

Python instrumentation for reporting OpenRouter calls to AutoTune.

Transport integration (recommended)

When requests are built inside an SDK (openai-python, pydantic-ai), wrap the app's httpx transport once and every OpenRouter chat completion that flows through it is shadow-reported in the background — no call-site changes, observation only, and AutoTune being down can never block or fail a model call. Requires the httpx extra (pip install autotune-hook[httpx]).

import httpx
from autotune_hook import AutotuneAsyncTransport

client = httpx.AsyncClient(transport=AutotuneAsyncTransport())
openrouter = AsyncOpenAI(base_url="https://openrouter.ai/api/v1", http_client=client)

Already wrapping transports (retries, sanitizers)? Put the AutoTune transport outermost so one logical call maps to one recorded run — the final response the app saw.

Wrapper / decorator integration

For call sites that hold the request payload directly. These also honor cloud workflow policy: the request is preflighted, and AutoTune answers with an explicit envelope — {"mode": "shadow", "ttl_seconds": N} (execute the wrapped call, report its output in the background, and skip further preflights for that workflow until the TTL expires) or {"mode": "proxy", "response": {...}} (return the AutoTune-executed response). Any response without the envelope falls back to the app's own call, so an intermediary's bare 200 can never be mistaken for an LLM response. Streaming requests pass through unobserved.

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:

@hook.openrouter()
def call_openrouter(**payload):
    return openrouter_client.chat.completions.create(**payload)

Sessions

from autotune_hook import with_session

with with_session(session_id=run_id, user_id=user_id, workflow="ocr"):
    ...  # every hooked/teed call inside is attributed

Reporting behavior

Reports ride a single background thread with a bounded queue: they never block the calling thread or event loop, overflow drops reports (with a warning) rather than growing memory, and flush_reports() drains pending reports at worker shutdown (also registered via atexit). Inline data: URLs larger than 256 bytes (base64 images) are replaced with a size-and-hash placeholder before reporting; disable with AUTOTUNE_HOOK_REDACT_DATA_URLS=0. Reports whose serialized size exceeds AUTOTUNE_HOOK_MAX_REPORT_BYTES (default 4 MB) are dropped with a warning.

Configuration

Defaults come from environment variables:

• AUTOTUNE_ENDPOINT (unset = the hook stays fully out of the way)
• AUTOTUNE_API_KEY
• AUTOTUNE_WORKFLOW
• AUTOTUNE_PROJECT
• AUTOTUNE_ENVIRONMENT
• AUTOTUNE_SESSION_ID
• AUTOTUNE_USER_ID
• AUTOTUNE_HOOK_TIMEOUT (seconds per hook HTTP request, default 2.0)
• AUTOTUNE_HOOK_MODE_TTL (seconds to cache a shadow decision, default 60)
• AUTOTUNE_HOOK_REDACT_DATA_URLS (default on)
• AUTOTUNE_HOOK_MAX_REPORT_BYTES (default 4000000)

Publishing

This package publishes from GitHub Actions using PyPI Trusted Publishing. No PyPI token is stored in GitHub.

One-time PyPI setup for autotune-hook:

• Go to the autotune-hook project on PyPI.
• Add a trusted publisher for GitHub Actions.
• Use owner shellzbt, repository sota-autotune.
• Use workflow filename publish-python-hook.yml.
• Use environment name pypi.

To publish a new release:

1. Bump the version in pyproject.toml and src/autotune_hook/__init__.py.
2. Merge the version bump to main.
3. Create and publish a GitHub release whose tag exactly matches that version, prefixed with autotune-hook-v, for example autotune-hook-v0.1.1.

The workflow fails before publishing if the version already exists on PyPI, if the release tag does not match the package version, or if pyproject.toml and src/autotune_hook/__init__.py disagree. Manual dispatch from main is available for retries before a version has been accepted by PyPI.