agentcompile 0.1.0__py3-none-any.whl

agentcompile/__init__.py

@@ -0,0 +1,100 @@
+"""AgentCompile: wrap your agent's model client.
+
+    import agentcompile
+    client = agentcompile.wrap(OpenAI(), key="ack_...")
+    client.chat.completions.create(model=..., messages=..., conversation_id=ticket.id)
+
+Known jobs run compiled (no model call); everything else goes to your model unchanged, with your
+own provider key. If AgentCompile is down or slow, calls go straight to your model. Every call
+is written to the trail (`agentcompile trail`).
+"""
+
+from __future__ import annotations
+
+import inspect
+import os
+from typing import Any
+
+from ._conversation import conversation
+from ._core import LIVE, SHADOW, Proxy, Router, async_create, sync_create
+from ._decide import AsyncDecider, Decider, Settings
+from ._trail import OnEvent, Trail
+
+__all__ = ["LIVE", "SHADOW", "conversation", "wrap"]
+__version__ = "0.1.0"
+
+DEFAULT_URL = "https://api.tryagentcompile.com"
+
+
+def wrap(
+    client: Any,
+    *,
+    key: str | None = None,
+    base_url: str | None = None,
+    mode: str = LIVE,
+    timeout: float = 2.0,
+    trail: str | bool | None = True,
+    on_event: OnEvent | None = None,
+    company: str | None = None,
+    http_client: Any = None,
+) -> Any:
+    """Wrap an OpenAI- or Anthropic-style client; returns an object you use exactly like it.
+
+    key: your AgentCompile key (or AGENTCOMPILE_KEY). base_url: AGENTCOMPILE_URL or the default.
+    mode: "live" answers known jobs; "shadow" decides but always calls your model, so you can
+    see what it would have done. timeout: seconds to wait for a decision before failing open.
+    trail: a path, True for ~/.agentcompile/trail.jsonl, or False. on_event: called per call.
+    """
+    settings = Settings(
+        base_url=base_url or os.environ.get("AGENTCOMPILE_URL", DEFAULT_URL),
+        key=key or os.environ.get("AGENTCOMPILE_KEY"),
+        company=company or os.environ.get("AGENTCOMPILE_COMPANY"),
+        timeout=timeout,
+    )
+    the_trail = Trail(trail, on_event)
+
+    chat = getattr(client, "chat", None)
+    completions = getattr(chat, "completions", None)
+    if completions is not None and hasattr(completions, "create"):
+        from . import _openai
+
+        router = _router("openai", completions.create, settings, the_trail, mode, http_client)
+        create = _create(router, completions.create, _openai.build)
+        return Proxy(
+            client,
+            {"chat": Proxy(chat, {"completions": Proxy(completions, {"create": create})})},
+        )
+
+    messages = getattr(client, "messages", None)
+    if messages is not None and hasattr(messages, "create"):
+        from . import _anthropic
+
+        router = _router("anthropic", messages.create, settings, the_trail, mode, http_client)
+        create = _create(router, messages.create, _anthropic.build)
+        return Proxy(client, {"messages": Proxy(messages, {"create": create})})
+
+    raise TypeError("agentcompile.wrap expects an OpenAI- or Anthropic-style client")
+
+
+def _router(
+    provider: str, create: Any, settings: Settings, trail: Trail, mode: str, http_client: Any
+) -> Router:
+    decider: Any = (
+        AsyncDecider(settings, http_client)
+        if _is_async(create)
+        else Decider(settings, http_client)
+    )
+    return Router(provider, decider, trail, mode)
+
+
+def _create(router: Router, original: Any, build: Any) -> Any:
+    return (
+        async_create(router, original, build)
+        if _is_async(original)
+        else sync_create(router, original, build)
+    )
+
+
+def _is_async(fn: Any) -> bool:
+    """The SDKs wrap create() in decorators; look through them."""
+    return inspect.iscoroutinefunction(inspect.unwrap(fn))

agentcompile/_anthropic.py

@@ -0,0 +1,80 @@
+"""Anthropic-style clients (Anthropic, AsyncAnthropic, AnthropicBedrock, AnthropicVertex):
+compiled answers shaped exactly like messages.create() results."""
+
+from __future__ import annotations
+
+import json
+import uuid
+from typing import Any
+
+from ._decide import Decision
+from ._streams import AsyncCompiledStream, CompiledStream
+
+
+def _block(decision: Decision) -> dict[str, Any]:
+    if decision.action == "tool_call":
+        return {
+            "type": "tool_use",
+            "id": decision.call_id or f"toolu_ac_{uuid.uuid4().hex[:12]}",
+            "name": decision.tool,
+            "input": decision.args,
+        }
+    return {"type": "text", "text": decision.text or ""}
+
+
+def build(decision: Decision, kwargs: dict[str, Any], stream: bool, is_async: bool) -> Any:
+    from anthropic.types import (
+        Message,
+        RawContentBlockDeltaEvent,
+        RawContentBlockStartEvent,
+        RawContentBlockStopEvent,
+        RawMessageDeltaEvent,
+        RawMessageStartEvent,
+        RawMessageStopEvent,
+    )
+
+    model = str(kwargs.get("model") or "agentcompile")
+    block = _block(decision)
+    stop = "tool_use" if decision.action == "tool_call" else "end_turn"
+    message = {
+        "id": f"msg_ac_{uuid.uuid4().hex[:16]}",
+        "type": "message",
+        "role": "assistant",
+        "model": model,
+        "content": [block],
+        "stop_reason": stop,
+        "stop_sequence": None,
+        "usage": {"input_tokens": 0, "output_tokens": 0},
+    }
+    if not stream:
+        return Message.model_validate(message)
+    if block["type"] == "tool_use":
+        start_block = {**block, "input": {}}
+        delta = {"type": "input_json_delta", "partial_json": json.dumps(block["input"])}
+    else:
+        start_block = {"type": "text", "text": ""}
+        delta = {"type": "text_delta", "text": block["text"]}
+    events: list[Any] = [
+        RawMessageStartEvent.model_validate(
+            {
+                "type": "message_start",
+                "message": {**message, "content": [], "stop_reason": None},
+            }
+        ),
+        RawContentBlockStartEvent.model_validate(
+            {"type": "content_block_start", "index": 0, "content_block": start_block}
+        ),
+        RawContentBlockDeltaEvent.model_validate(
+            {"type": "content_block_delta", "index": 0, "delta": delta}
+        ),
+        RawContentBlockStopEvent.model_validate({"type": "content_block_stop", "index": 0}),
+        RawMessageDeltaEvent.model_validate(
+            {
+                "type": "message_delta",
+                "delta": {"stop_reason": stop, "stop_sequence": None},
+                "usage": {"output_tokens": 0},
+            }
+        ),
+        RawMessageStopEvent.model_validate({"type": "message_stop"}),
+    ]
+    return AsyncCompiledStream(events) if is_async else CompiledStream(events)

agentcompile/_conversation.py

@@ -0,0 +1,29 @@
+"""The conversation id: a `conversation_id=` keyword on create(), or a context block."""
+
+from __future__ import annotations
+
+import contextlib
+import contextvars
+from collections.abc import Iterator
+
+_current: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "agentcompile_conversation", default=None
+)
+
+
+@contextlib.contextmanager
+def conversation(conversation_id: str) -> Iterator[None]:
+    """Every model call inside the block belongs to this conversation:
+
+    with agentcompile.conversation(ticket.id):
+        run_agent(...)
+    """
+    token = _current.set(conversation_id)
+    try:
+        yield
+    finally:
+        _current.reset(token)
+
+
+def current() -> str | None:
+    return _current.get()

agentcompile/_core.py

@@ -0,0 +1,182 @@
+"""What every wrapped create() does: decide, then answer compiled or call the real method."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable
+
+from ._conversation import current
+from ._decide import Decision
+from ._payload import payload
+from ._trail import Trail
+
+LIVE, SHADOW = "live", "shadow"
+
+
+class Router:
+    """Holds the decision client, the trail and the mode for one wrapped client."""
+
+    def __init__(self, provider: str, decider: Any, trail: Trail, mode: str) -> None:
+        if mode not in (LIVE, SHADOW):
+            raise ValueError("mode must be 'live' or 'shadow'")
+        self.provider = provider
+        self.decider = decider
+        self.trail = trail
+        self.mode = mode
+
+    def prepare(self, kwargs: dict[str, Any]) -> tuple[str | None, dict[str, Any]]:
+        """(conversation id, kwargs for the real call): our keyword never reaches the model."""
+        kwargs = dict(kwargs)
+        conversation_id = kwargs.pop("conversation_id", None) or current()
+        return conversation_id, kwargs
+
+    def plan(
+        self, conversation_id: str | None, decision: Decision | None, error: str | None
+    ) -> tuple[str, Decision | None]:
+        """(route, the decision to answer with or None to forward)."""
+        if conversation_id is None:
+            return "no-conversation", None
+        if decision is None:
+            return "fail-open", None
+        if decision.action == "forward":
+            return "forwarded", None
+        if self.mode == SHADOW:
+            return "shadow", None
+        return "compiled", decision
+
+    def record(
+        self,
+        *,
+        route: str,
+        conversation_id: str | None,
+        kwargs: dict[str, Any],
+        decision: Decision | None,
+        decide_ms: float | None,
+        error: str | None,
+        started: float,
+        stream: bool,
+    ) -> None:
+        self.trail.record(
+            conversation=conversation_id,
+            provider=self.provider,
+            model=kwargs.get("model"),
+            route=route,
+            action=decision.action if decision else None,
+            tool=decision.tool if decision else None,
+            reason=(decision.reason if decision and decision.action == "forward" else None)
+            or error,
+            decide_ms=round(decide_ms, 1) if decide_ms is not None else None,
+            total_ms=round((time.perf_counter() - started) * 1000, 1),
+            stream=stream or None,
+        )
+
+
+def sync_create(
+    router: Router, original: Callable[..., Any], build: Callable[..., Any]
+) -> Callable[..., Any]:
+    def create(*args: Any, **kwargs: Any) -> Any:
+        started = time.perf_counter()
+        conversation_id, real_kwargs = router.prepare(kwargs)
+        decision = decide_ms = error = None
+        if conversation_id is not None:
+            decision, decide_ms, error = router.decider.decide(
+                router.provider, conversation_id, payload(real_kwargs)
+            )
+        route, answer = router.plan(conversation_id, decision, error)
+        stream = bool(real_kwargs.get("stream"))
+        if answer is not None:
+            try:
+                result = build(answer, real_kwargs, stream, False)
+            except (
+                Exception
+            ) as exc:  # fail open: a compiled answer we can't shape goes to the model
+                route, error = "fail-open", f"build: {type(exc).__name__}"
+            else:
+                router.record(
+                    route=route,
+                    conversation_id=conversation_id,
+                    kwargs=real_kwargs,
+                    decision=decision,
+                    decide_ms=decide_ms,
+                    error=error,
+                    started=started,
+                    stream=stream,
+                )
+                return result
+        result = original(*args, **real_kwargs)
+        router.record(
+            route=route,
+            conversation_id=conversation_id,
+            kwargs=real_kwargs,
+            decision=decision,
+            decide_ms=decide_ms,
+            error=error,
+            started=started,
+            stream=stream,
+        )
+        return result
+
+    return create
+
+
+def async_create(
+    router: Router, original: Callable[..., Any], build: Callable[..., Any]
+) -> Callable[..., Any]:
+    async def create(*args: Any, **kwargs: Any) -> Any:
+        started = time.perf_counter()
+        conversation_id, real_kwargs = router.prepare(kwargs)
+        decision = decide_ms = error = None
+        if conversation_id is not None:
+            decision, decide_ms, error = await router.decider.decide(
+                router.provider, conversation_id, payload(real_kwargs)
+            )
+        route, answer = router.plan(conversation_id, decision, error)
+        stream = bool(real_kwargs.get("stream"))
+        if answer is not None:
+            try:
+                result = build(answer, real_kwargs, stream, True)
+            except Exception as exc:
+                route, error = "fail-open", f"build: {type(exc).__name__}"
+            else:
+                router.record(
+                    route=route,
+                    conversation_id=conversation_id,
+                    kwargs=real_kwargs,
+                    decision=decision,
+                    decide_ms=decide_ms,
+                    error=error,
+                    started=started,
+                    stream=stream,
+                )
+                return result
+        result = await original(*args, **real_kwargs)
+        router.record(
+            route=route,
+            conversation_id=conversation_id,
+            kwargs=real_kwargs,
+            decision=decision,
+            decide_ms=decide_ms,
+            error=error,
+            started=started,
+            stream=stream,
+        )
+        return result
+
+    return create
+
+
+class Proxy:
+    """Everything delegates to the real object except the attributes we override."""
+
+    def __init__(self, target: Any, overrides: dict[str, Any]) -> None:
+        object.__setattr__(self, "_target", target)
+        object.__setattr__(self, "_overrides", overrides)
+
+    def __getattr__(self, name: str) -> Any:
+        overrides = object.__getattribute__(self, "_overrides")
+        if name in overrides:
+            return overrides[name]
+        return getattr(object.__getattribute__(self, "_target"), name)
+
+    def __repr__(self) -> str:
+        return f"agentcompile({object.__getattribute__(self, '_target')!r})"

agentcompile/_decide.py

@@ -0,0 +1,116 @@
+"""The decision call to AgentCompile. Never raises: any problem is a `None` decision, which the
+wrapper treats as forward (fail open)."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+
+COMPANY_HEADER = "x-agentcompiler-company"
+CONVERSATION_HEADER = "x-agentcompiler-conversation"
+KEY_HEADER = "x-agentcompiler-key"
+
+
+@dataclass(frozen=True)
+class Decision:
+    action: str  # "tool_call" | "say" | "forward"
+    tool: str | None = None
+    args: dict[str, Any] = field(default_factory=dict)
+    call_id: str | None = None
+    text: str | None = None
+    reason: str | None = None
+
+    @classmethod
+    def parse(cls, body: Any) -> Decision | None:
+        if not isinstance(body, dict):
+            return None
+        action = body.get("action")
+        if (
+            action == "tool_call"
+            and isinstance(body.get("tool"), str)
+            and isinstance(body.get("args"), dict)
+        ):
+            return cls(
+                action,
+                tool=body["tool"],
+                args=body["args"],
+                call_id=str(body.get("call_id") or ""),
+            )
+        if action == "say" and isinstance(body.get("text"), str):
+            return cls(action, text=body["text"])
+        if action == "forward":
+            return cls(action, reason=str(body.get("reason") or ""))
+        return None
+
+
+@dataclass(frozen=True)
+class Settings:
+    base_url: str
+    key: str | None
+    company: str | None
+    timeout: float
+
+
+def _request(
+    settings: Settings, provider: str, conversation_id: str, payload: dict[str, Any]
+) -> tuple[str, dict[str, str], dict[str, Any]]:
+    headers = {CONVERSATION_HEADER: conversation_id}
+    if settings.company:  # optional: the key names the company
+        headers[COMPANY_HEADER] = settings.company
+    if settings.key:
+        headers[KEY_HEADER] = settings.key
+    return (
+        f"{settings.base_url.rstrip('/')}/v1/decide",
+        headers,
+        {"provider": provider, "request": payload},
+    )
+
+
+class Decider:
+    def __init__(self, settings: Settings, http: httpx.Client | None = None) -> None:
+        self.settings = settings
+        self._http = http or httpx.Client(timeout=settings.timeout)
+
+    def decide(
+        self, provider: str, conversation_id: str, payload: dict[str, Any]
+    ) -> tuple[Decision | None, float, str | None]:
+        """(decision or None, milliseconds, error text)."""
+        url, headers, body = _request(self.settings, provider, conversation_id, payload)
+        start = time.perf_counter()
+        try:
+            response = self._http.post(
+                url, headers=headers, json=body, timeout=self.settings.timeout
+            )
+            ms = (time.perf_counter() - start) * 1000
+            if response.status_code != 200:
+                return None, ms, f"HTTP {response.status_code}"
+            decision = Decision.parse(response.json())
+            return decision, ms, None if decision else "malformed decision"
+        except Exception as exc:  # fail open
+            return None, (time.perf_counter() - start) * 1000, type(exc).__name__
+
+
+class AsyncDecider:
+    def __init__(self, settings: Settings, http: httpx.AsyncClient | None = None) -> None:
+        self.settings = settings
+        self._http = http or httpx.AsyncClient(timeout=settings.timeout)
+
+    async def decide(
+        self, provider: str, conversation_id: str, payload: dict[str, Any]
+    ) -> tuple[Decision | None, float, str | None]:
+        url, headers, body = _request(self.settings, provider, conversation_id, payload)
+        start = time.perf_counter()
+        try:
+            response = await self._http.post(
+                url, headers=headers, json=body, timeout=self.settings.timeout
+            )
+            ms = (time.perf_counter() - start) * 1000
+            if response.status_code != 200:
+                return None, ms, f"HTTP {response.status_code}"
+            decision = Decision.parse(response.json())
+            return decision, ms, None if decision else "malformed decision"
+        except Exception as exc:  # fail open
+            return None, (time.perf_counter() - start) * 1000, type(exc).__name__

agentcompile/_openai.py

@@ -0,0 +1,65 @@
+"""OpenAI-style clients (OpenAI, AsyncOpenAI, AzureOpenAI and any OpenAI-compatible base_url):
+compiled answers shaped exactly like chat.completions.create() results."""
+
+from __future__ import annotations
+
+import json
+import time
+import uuid
+from typing import Any
+
+from ._decide import Decision
+from ._streams import AsyncCompiledStream, CompiledStream
+
+
+def _message(decision: Decision) -> dict[str, Any]:
+    if decision.action == "tool_call":
+        return {
+            "role": "assistant",
+            "content": None,
+            "tool_calls": [
+                {
+                    "id": decision.call_id or f"call_ac_{uuid.uuid4().hex[:12]}",
+                    "type": "function",
+                    "function": {"name": decision.tool, "arguments": json.dumps(decision.args)},
+                }
+            ],
+        }
+    return {"role": "assistant", "content": decision.text}
+
+
+def build(decision: Decision, kwargs: dict[str, Any], stream: bool, is_async: bool) -> Any:
+    from openai.types.chat import ChatCompletion, ChatCompletionChunk
+
+    model = str(kwargs.get("model") or "agentcompile")
+    ident, created = f"chatcmpl-ac-{uuid.uuid4().hex[:16]}", int(time.time())
+    message = _message(decision)
+    finish = "tool_calls" if decision.action == "tool_call" else "stop"
+    if not stream:
+        return ChatCompletion.model_validate(
+            {
+                "id": ident,
+                "object": "chat.completion",
+                "created": created,
+                "model": model,
+                "choices": [
+                    {"index": 0, "message": message, "finish_reason": finish, "logprobs": None}
+                ],
+                "usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0},
+            }
+        )
+    delta: dict[str, Any] = {"role": "assistant", "content": message.get("content")}
+    if "tool_calls" in message:
+        delta["tool_calls"] = [
+            {**call, "index": i} for i, call in enumerate(message["tool_calls"])
+        ]
+    base = {"id": ident, "object": "chat.completion.chunk", "created": created, "model": model}
+    chunks: list[Any] = [
+        ChatCompletionChunk.model_validate(
+            {**base, "choices": [{"index": 0, "delta": delta, "finish_reason": None}]}
+        ),
+        ChatCompletionChunk.model_validate(
+            {**base, "choices": [{"index": 0, "delta": {}, "finish_reason": finish}]}
+        ),
+    ]
+    return AsyncCompiledStream(chunks) if is_async else CompiledStream(chunks)

agentcompile/_payload.py

@@ -0,0 +1,26 @@
+"""Turning create() keyword arguments into the JSON the decision call sends."""
+
+from __future__ import annotations
+
+from typing import Any
+
+# What the engine reads; everything else stays between the customer and their provider.
+_FIELDS = ("model", "messages", "system", "tools")
+
+
+def jsonable(value: Any) -> Any:
+    """Plain JSON from what agent loops put in messages: dicts, lists, and the SDKs' own
+    response objects appended back into the history (pydantic models)."""
+    if hasattr(value, "model_dump"):
+        return jsonable(value.model_dump(exclude_none=True))
+    if isinstance(value, dict):
+        return {str(k): jsonable(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [jsonable(v) for v in value]
+    if isinstance(value, (str, int, float, bool)) or value is None:
+        return value
+    return str(value)
+
+
+def payload(kwargs: dict[str, Any]) -> dict[str, Any]:
+    return {k: jsonable(kwargs[k]) for k in _FIELDS if k in kwargs and kwargs[k] is not None}

agentcompile/_streams.py

@@ -0,0 +1,47 @@
+"""Compiled answers as streams: iterators shaped like the SDKs' Stream objects."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+
+class CompiledStream:
+    def __init__(self, items: list[Any]) -> None:
+        self._items = items
+
+    def __iter__(self) -> Iterator[Any]:
+        return iter(self._items)
+
+    def __enter__(self) -> CompiledStream:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        return None
+
+    def close(self) -> None:
+        return None
+
+
+class AsyncCompiledStream:
+    def __init__(self, items: list[Any]) -> None:
+        self._items = items
+
+    def __aiter__(self) -> AsyncCompiledStream:
+        self._it = iter(self._items)
+        return self
+
+    async def __anext__(self) -> Any:
+        try:
+            return next(self._it)
+        except StopIteration:
+            raise StopAsyncIteration from None
+
+    async def __aenter__(self) -> AsyncCompiledStream:
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        return None
+
+    async def close(self) -> None:
+        return None

agentcompile/_trail.py

@@ -0,0 +1,50 @@
+"""The trail: one JSON line per model call, so you can see what AgentCompile did with each one.
+
+Routes: `compiled` (answered without your model), `forwarded` (sent to your model),
+`fail-open` (AgentCompile failed or was slow; sent to your model), `shadow` (decided but always
+forwarded), `no-conversation` (no conversation id; sent to your model)."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import threading
+import time
+from pathlib import Path
+from typing import Any, Callable
+
+DEFAULT_PATH = Path(
+    os.environ.get("AGENTCOMPILE_TRAIL", Path.home() / ".agentcompile" / "trail.jsonl")
+)
+
+OnEvent = Callable[[dict[str, Any]], None]
+
+
+class Trail:
+    def __init__(
+        self, path: str | Path | bool | None = True, on_event: OnEvent | None = None
+    ) -> None:
+        self.path: Path | None = (
+            DEFAULT_PATH if path is True else (Path(path) if path else None)
+        )
+        self.on_event = on_event
+        self._lock = threading.Lock()
+
+    def record(self, **event: Any) -> dict[str, Any]:
+        event = {
+            "ts": round(time.time(), 3),
+            **{k: v for k, v in event.items() if v is not None},
+        }
+        if self.path is not None:
+            try:
+                with self._lock:
+                    self.path.parent.mkdir(parents=True, exist_ok=True)
+                    with self.path.open("a", encoding="utf-8") as fh:
+                        fh.write(json.dumps(event, default=str) + "\n")
+            except OSError:
+                pass  # the trail never breaks the agent
+        if self.on_event is not None:
+            with contextlib.suppress(Exception):
+                self.on_event(event)
+        return event

agentcompile/cli.py

@@ -0,0 +1,100 @@
+"""`agentcompile trail`: see what AgentCompile did with each model call."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from collections.abc import Iterator
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from ._trail import DEFAULT_PATH
+
+COLORS = {
+    "compiled": "\033[33m",
+    "forwarded": "\033[0m",
+    "fail-open": "\033[31m",
+    "shadow": "\033[36m",
+    "no-conversation": "\033[2m",
+}
+RESET = "\033[0m"
+
+
+def line(event: dict[str, Any], color: bool) -> str:
+    ts = datetime.fromtimestamp(event.get("ts", 0)).strftime("%H:%M:%S")
+    route = event.get("route", "?")
+    what = event.get("tool") or event.get("action") or event.get("reason") or ""
+    if route in ("forwarded", "fail-open") and event.get("reason"):
+        what = event["reason"]
+    timing = f"{event['decide_ms']:.0f} ms decide" if event.get("decide_ms") is not None else ""
+    convo = str(event.get("conversation", "-"))[:12]
+    model = event.get("model", "")
+    text = f"{ts}  {convo:<12}  {route:<15}  {str(what)[:40]:<40}  {model}  {timing}"
+    return f"{COLORS.get(route, '')}{text}{RESET}" if color else text
+
+
+def follow(path: Path, start_at_end: bool) -> Iterator[str]:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.touch(exist_ok=True)
+    with path.open(encoding="utf-8") as fh:
+        if start_at_end:
+            fh.seek(0, 2)
+        while True:
+            row = fh.readline()
+            if row:
+                yield row
+            else:
+                time.sleep(0.25)
+
+
+def summary(rows: list) -> str:
+    total = len(rows)
+    counts: dict[str, int] = {}
+    for r in rows:
+        counts[r.get("route", "?")] = counts.get(r.get("route", "?"), 0) + 1
+    parts = ", ".join(f"{k} {v}" for k, v in sorted(counts.items()))
+    compiled = counts.get("compiled", 0)
+    share = f"{100 * compiled / total:.0f}%" if total else "0%"
+    return f"{total} calls: {parts}. Model calls avoided: {compiled} ({share})."
+
+
+def main(argv: Any = None) -> int:
+    parser = argparse.ArgumentParser(prog="agentcompile")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    t = sub.add_parser("trail", help="show the trail of model calls")
+    t.add_argument("-f", "--follow", action="store_true", help="keep printing new calls")
+    t.add_argument("-n", type=int, default=50, help="how many recent calls to show")
+    t.add_argument("--path", type=Path, default=DEFAULT_PATH)
+    t.add_argument("--json", action="store_true", help="raw JSON lines")
+    args = parser.parse_args(argv)
+    color = sys.stdout.isatty() and not args.json
+    rows = []
+    if args.path.exists():
+        for raw in args.path.read_text(encoding="utf-8").splitlines()[-args.n :]:
+            try:
+                rows.append(json.loads(raw))
+            except ValueError:
+                continue
+    for r in rows:
+        print(json.dumps(r) if args.json else line(r, color))
+    if not args.follow:
+        if not args.json:
+            print(summary(rows))
+        return 0
+    try:
+        for raw in follow(args.path, start_at_end=True):
+            try:
+                event = json.loads(raw)
+            except ValueError:
+                continue
+            print(json.dumps(event) if args.json else line(event, color), flush=True)
+    except KeyboardInterrupt:
+        return 0
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agentcompile-0.1.0.dist-info/METADATA

@@ -0,0 +1,87 @@
+Metadata-Version: 2.5
+Name: agentcompile
+Version: 0.1.0
+Summary: Wrap your agent's model client: repeated jobs run compiled, everything else goes to your model unchanged.
+Project-URL: Homepage, https://tryagentcompile.com
+Author-email: AgentCompile <founders@tryagentcompile.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: anthropic>=0.40; extra == 'dev'
+Requires-Dist: openai>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# agentcompile
+
+```
+pip install agentcompile
+```
+
+Wrap your agent's model client. Jobs your agent repeats run compiled, with no model call; everything else goes to your model unchanged, with your own provider key.
+
+```python
+from openai import OpenAI
+import agentcompile
+
+client = agentcompile.wrap(OpenAI(), key="ack_...")   # or AGENTCOMPILE_KEY
+
+resp = client.chat.completions.create(
+    model="gpt-5", messages=messages, tools=tools,
+    conversation_id=ticket.id,                         # one id per conversation
+)
+```
+
+Anthropic works the same way (`agentcompile.wrap(Anthropic())`, then `client.messages.create(...)`). So do async clients, streaming and tool calls. Instead of the keyword, you can set the id for a block of calls:
+
+```python
+with agentcompile.conversation(ticket.id):
+    run_agent(client)
+```
+
+## What happens on each call
+
+1. With a conversation id, the SDK asks AgentCompile for a decision (`/v1/decide`; it waits at most `timeout`, default 2 s).
+2. **compiled**: the answer (a tool call or a reply) comes back in exactly the provider's response shape; your loop runs the tool as usual.
+3. **forwarded**: your model is called as normal.
+4. **fail-open**: AgentCompile errored, was slow or sent something unusable, so your model is called as normal.
+5. **no conversation id**: your model is called and no decision is made.
+
+Your provider key never leaves your process. `mode="shadow"` decides but always calls your model, so you can see what it would have done before you switch it on.
+
+## The trail
+
+Every call is written to `~/.agentcompile/trail.jsonl` (`trail=` sets a path, or `False` turns it off; `on_event=` gets each event).
+
+```
+agentcompile trail          # recent calls and a summary
+agentcompile trail -f       # follow live
+```
+
+```
+14:02:11  c1            compiled         get_order_details                         gpt-5  48 ms decide
+14:02:12  c2            forwarded        no job matched                            gpt-5  51 ms decide
+2 calls: compiled 1, forwarded 1. Model calls avoided: 1 (50%).
+```
+
+## Keys
+
+Your AgentCompile key (`ack_...`) identifies your company by itself. We show it once and store only its hash; a new key revokes the old one. AgentCompile is pre-launch: to get a key, write to founders@tryagentcompile.com.
+
+## Development
+
+```
+pip install -e ".[dev]"
+pytest tests
+```

agentcompile-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+agentcompile/__init__.py,sha256=nfgkxePglg0SN9FP_yaDXZM3NJg0YwXgamcl_8C1MFw,3603
+agentcompile/_anthropic.py,sha256=TLUhUfxdf6cBf0jgG4XczHQC5vL4s-xfo8Qpoh5hItQ,2839
+agentcompile/_conversation.py,sha256=VF0sUXXST6W4BJHlTv0n1caaGr6zhRXuHLE9bAtAduU,722
+agentcompile/_core.py,sha256=-V_P6DLaCoj7nGB9dgiAzzv70bZTnD4gKG__x083-w8,6480
+agentcompile/_decide.py,sha256=1njRPUaf24NlX9xtzmT__SvEBwjxqbxj-tGX-sL1XW4,4227
+agentcompile/_openai.py,sha256=gsByu3b9tMXs9CeUd316QdLZzsCOVLlDe3HejsMllpY,2506
+agentcompile/_payload.py,sha256=kskH_qX7c1Qa1MtgNpvDmKMXhT2-C81r_TR4Ic1xKWo,1018
+agentcompile/_streams.py,sha256=HsrkyaM_f4NM77RvcuZ_JhXT9v7aqIylYTmrSTZC58k,1114
+agentcompile/_trail.py,sha256=UxjmdVTFUPjiKN-GSrsftEx4S8oPqe_KFUV7MyddpCY,1715
+agentcompile/cli.py,sha256=UATyVSMDhIGDQCZPBBFkWjo_1nuGo8PNCCwndU5TNYI,3426
+agentcompile-0.1.0.dist-info/METADATA,sha256=RtoJdZ-ripeYVRd0sYrtasBT4Fw-dfwFdOiIXy_y17o,3309
+agentcompile-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+agentcompile-0.1.0.dist-info/entry_points.txt,sha256=s7G0_-Ni50SGRqUMhjB7FpAt6UtfLX77xPfHjGgghwk,55
+agentcompile-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+agentcompile-0.1.0.dist-info/RECORD,,

agentcompile-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

agentcompile-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agentcompile = agentcompile.cli:main

agentcompile-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.