powerailabs-core 0.1.0__tar.gz

powerailabs_core-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.uv/
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.idea/
+.vscode/
+.DS_Store
+*.log

powerailabs_core-0.1.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: powerailabs-core
+Version: 0.1.0
+Summary: Foundation for the PowerAI Labs stack: shared types, token counting, prices, instrument(), event bus, OTel.
+Author: Raghav Mishra
+License-Expression: MIT
+Requires-Python: >=3.11
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30; extra == 'anthropic'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.25; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.25; extra == 'otel'
+Provides-Extra: tiktoken
+Requires-Dist: tiktoken>=0.7; extra == 'tiktoken'
+Description-Content-Type: text/markdown
+
+# powerailabs-core
+
+The shared foundation for the PowerAI Labs stack: canonical types, provider-aware token
+counting, an offline price table, one `instrument()` interception point, an in-process event
+bus, and OpenTelemetry GenAI emitters. Tiny on purpose — it's the blast radius for every other tool.
+
+**One `instrument()` call, every sibling tool observes the stream — no per-call wiring, offline by default.**
+
+![status](https://img.shields.io/badge/status-building-yellow) ![license](https://img.shields.io/badge/license-MIT-blue)
+
+🚧 building · usually installed transitively · `import powerailabs.core`
+
+```python
+from powerailabs.core import tokens, prices, instrument, bus
+
+# Count tokens and price a call — fully offline, no API key, no network:
+n = tokens.count([{"role": "user", "content": "Summarize the attached report in 3 bullets."}],
+                 model="claude-opus-4-8")
+cost = prices.estimate("claude-opus-4-8", input_tokens=n, output_tokens=200)
+print(n, cost)                       # -> 20  0.0051000 USD
+
+# Instrument any client once; tools subscribe to the normalized event stream:
+@bus.subscribe
+def on_call(call):                   # receives a normalized LLMCall with usage + cost
+    print(call.provider, call.model, call.cost)
+
+client = instrument(openai_or_anthropic_client)   # idempotent, additive, sync + async
+```
+
+Install `powerailabs-core[tiktoken]` for exact OpenAI token counts (a documented heuristic is
+used otherwise), or `[otel]` to emit `gen_ai.*` spans. Provider SDKs are always optional extras.
+
+See [`docs/core.md`](../../docs/core.md). *Part of the PowerAI Labs stack — github.com/PowerAI-Labs/powerailabs.*

powerailabs_core-0.1.0/README.md

@@ -0,0 +1,33 @@
+# powerailabs-core
+
+The shared foundation for the PowerAI Labs stack: canonical types, provider-aware token
+counting, an offline price table, one `instrument()` interception point, an in-process event
+bus, and OpenTelemetry GenAI emitters. Tiny on purpose — it's the blast radius for every other tool.
+
+**One `instrument()` call, every sibling tool observes the stream — no per-call wiring, offline by default.**
+
+![status](https://img.shields.io/badge/status-building-yellow) ![license](https://img.shields.io/badge/license-MIT-blue)
+
+🚧 building · usually installed transitively · `import powerailabs.core`
+
+```python
+from powerailabs.core import tokens, prices, instrument, bus
+
+# Count tokens and price a call — fully offline, no API key, no network:
+n = tokens.count([{"role": "user", "content": "Summarize the attached report in 3 bullets."}],
+                 model="claude-opus-4-8")
+cost = prices.estimate("claude-opus-4-8", input_tokens=n, output_tokens=200)
+print(n, cost)                       # -> 20  0.0051000 USD
+
+# Instrument any client once; tools subscribe to the normalized event stream:
+@bus.subscribe
+def on_call(call):                   # receives a normalized LLMCall with usage + cost
+    print(call.provider, call.model, call.cost)
+
+client = instrument(openai_or_anthropic_client)   # idempotent, additive, sync + async
+```
+
+Install `powerailabs-core[tiktoken]` for exact OpenAI token counts (a documented heuristic is
+used otherwise), or `[otel]` to emit `gen_ai.*` spans. Provider SDKs are always optional extras.
+
+See [`docs/core.md`](../../docs/core.md). *Part of the PowerAI Labs stack — github.com/PowerAI-Labs/powerailabs.*

powerailabs_core-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "powerailabs-core"
+version = "0.1.0"
+description = "Foundation for the PowerAI Labs stack: shared types, token counting, prices, instrument(), event bus, OTel."
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Raghav Mishra" }]
+readme = "README.md"
+dependencies = []
+
+[project.optional-dependencies]
+openai = ["openai>=1.0"]
+anthropic = ["anthropic>=0.30"]
+otel = ["opentelemetry-api>=1.25", "opentelemetry-sdk>=1.25"]
+tiktoken = ["tiktoken>=0.7"]   # optional: exact OpenAI token counts (heuristic fallback otherwise)
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/powerailabs"]     # contributes powerailabs/core only — NEVER add src/powerailabs/__init__.py

powerailabs_core-0.1.0/src/powerailabs/core/__init__.py

@@ -0,0 +1,21 @@
+"""powerailabs.core — the shared foundation. Keep this public surface small and stable."""
+
+from __future__ import annotations
+
+from . import bus, otel, prices, protocols, tokens
+from .instrument import instrument, instrument_tool
+from .types import LLMCall, Money, ToolCall, Usage
+
+__all__ = [
+    "LLMCall",
+    "ToolCall",
+    "Usage",
+    "Money",
+    "bus",
+    "tokens",
+    "prices",
+    "otel",
+    "protocols",
+    "instrument",
+    "instrument_tool",
+]

powerailabs_core-0.1.0/src/powerailabs/core/bus.py

@@ -0,0 +1,27 @@
+"""In-process pub/sub event bus: one instrument() emits, many tools subscribe. docs/core.md §6."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+_subscribers: list[Callable[[Any], None]] = []
+
+
+def subscribe(fn: Callable[[Any], None]) -> Callable[[Any], None]:
+    """Register a subscriber. Usable as a decorator. Idempotent: re-registering the
+    same callable is a no-op, so a sibling tool can safely ensure its subscription."""
+    if fn not in _subscribers:
+        _subscribers.append(fn)
+    return fn
+
+
+def emit(event: Any) -> None:
+    """Publish an event to all subscribers (synchronous)."""
+    for fn in list(_subscribers):
+        fn(event)
+
+
+def _reset() -> None:
+    """Test helper: clear all subscribers."""
+    _subscribers.clear()

powerailabs_core-0.1.0/src/powerailabs/core/instrument.py

@@ -0,0 +1,246 @@
+"""Single interception point: wrap a provider client (or tool) once; emit normalized events.
+
+docs/core.md §6. Idempotent (re-wrapping is a no-op) and additive (coexists with other
+instrumentation like OpenLLMetry). Supports sync and async. Uses duck typing — the provider
+SDKs are never imported here, so they stay optional.
+
+Two cooperation hooks (used by ``cassette``; harmless otherwise):
+  * **record** — the raw provider response is attached at ``call.metadata["response"]`` before
+    the event is emitted, so a subscriber can persist it.
+  * **replay** — registered *interceptors* run *before* the real call; one may return a response
+    to short-circuit it (returning :data:`MISS` to decline). This is how record/replay avoids a
+    second instrumentation point: tools cooperate through ``core``, they never patch the client.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import time
+import uuid
+from collections.abc import Callable
+from datetime import UTC, datetime
+from typing import Any, TypeVar
+
+from . import bus, prices
+from .types import LLMCall, ToolCall, Usage
+
+T = TypeVar("T")
+
+_WRAPPED = "_powerailabs_wrapped"
+
+#: Sentinel an interceptor returns to decline a call (let it proceed normally). A recorded
+#: response may legitimately be ``None``, so "no replay" needs its own distinct value.
+MISS: Any = object()
+
+_interceptors: list[Callable[[Any], Any]] = []
+
+
+def add_interceptor(fn: Callable[[Any], Any]) -> Callable[[Any], Any]:
+    """Register a pre-call interceptor. It receives the event (``LLMCall``/``ToolCall``) and
+    returns a response to short-circuit the real call, or :data:`MISS` to proceed. Idempotent."""
+    if fn not in _interceptors:
+        _interceptors.append(fn)
+    return fn
+
+
+def remove_interceptor(fn: Callable[[Any], Any]) -> None:
+    """Unregister a previously added interceptor (no error if absent)."""
+    if fn in _interceptors:
+        _interceptors.remove(fn)
+
+
+def _intercept(event: Any) -> Any:
+    for fn in list(_interceptors):
+        result = fn(event)
+        if result is not MISS:
+            return result
+    return MISS
+
+
+# --------------------------------------------------------------------------- model clients
+
+
+def instrument(client: T) -> T:
+    """Wrap an OpenAI- or Anthropic-shaped client so each call emits an ``LLMCall`` on the bus.
+
+    Detection is structural: an object exposing ``chat.completions.create`` is treated as
+    OpenAI-style; one exposing ``messages.create`` as Anthropic-style. Unknown clients are
+    returned untouched. Wrapping is idempotent and returns the same client object.
+    """
+    target = _find_target(client)
+    if target is None:
+        return client
+    owner, attr, provider = target
+    fn = getattr(owner, attr)
+    if getattr(fn, _WRAPPED, False):
+        return client  # already instrumented — no double-wrap
+    setattr(owner, attr, _wrap(fn, provider))
+    return client
+
+
+def _find_target(client: Any) -> tuple[Any, str, str] | None:
+    chat = getattr(client, "chat", None)
+    completions = getattr(chat, "completions", None) if chat is not None else None
+    if completions is not None and callable(getattr(completions, "create", None)):
+        return completions, "create", "openai"
+    messages = getattr(client, "messages", None)
+    if messages is not None and callable(getattr(messages, "create", None)):
+        return messages, "create", "anthropic"
+    return None
+
+
+def _wrap(fn: Any, provider: str) -> Any:
+    if inspect.iscoroutinefunction(fn):
+
+        @functools.wraps(fn)
+        async def awrapper(*args: Any, **kwargs: Any) -> Any:
+            call, start = _pre(provider, kwargs)
+            replayed = _intercept(call)
+            if replayed is not MISS:
+                call.metadata["replayed"] = True
+                response = replayed
+            else:
+                response = await fn(*args, **kwargs)
+            _post(call, response, provider, start)
+            return response
+
+        setattr(awrapper, _WRAPPED, True)
+        return awrapper
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        call, start = _pre(provider, kwargs)
+        replayed = _intercept(call)
+        if replayed is not MISS:
+            call.metadata["replayed"] = True
+            response = replayed
+        else:
+            response = fn(*args, **kwargs)
+        _post(call, response, provider, start)
+        return response
+
+    setattr(wrapper, _WRAPPED, True)
+    return wrapper
+
+
+def _pre(provider: str, kwargs: dict) -> tuple[LLMCall, float]:
+    call = LLMCall(
+        id=uuid.uuid4().hex,
+        provider=provider,
+        model=kwargs.get("model", ""),
+        messages=list(kwargs.get("messages") or []),
+        ts=datetime.now(UTC),
+    )
+    return call, time.perf_counter()
+
+
+def _post(call: LLMCall, response: Any, provider: str, start: float) -> None:
+    call.latency_ms = (time.perf_counter() - start) * 1000.0
+    usage = _extract_usage(response, provider)
+    call.usage = usage
+    if usage is not None:
+        try:
+            call.cost = prices.estimate(
+                call.model, usage.input_tokens, usage.output_tokens, usage.cached_tokens
+            )
+        except KeyError:
+            call.cost = None
+    call.metadata["response"] = response  # for recorders (cassette); a reference, not a copy
+    bus.emit(call)
+
+
+def _get(obj: Any, name: str, default: Any = None) -> Any:
+    if isinstance(obj, dict):
+        return obj.get(name, default)
+    return getattr(obj, name, default)
+
+
+def _extract_usage(response: Any, provider: str) -> Usage | None:
+    u = _get(response, "usage")
+    if u is None:
+        return None
+    if provider == "openai":
+        inp = _get(u, "prompt_tokens")
+        out = _get(u, "completion_tokens", 0) or 0
+        details = _get(u, "prompt_tokens_details")
+        cached = _get(details, "cached_tokens", 0) or 0 if details is not None else 0
+    else:  # anthropic
+        inp = _get(u, "input_tokens")
+        out = _get(u, "output_tokens", 0) or 0
+        cached = _get(u, "cache_read_input_tokens", 0) or 0
+    if inp is None:
+        return None
+    return Usage(input_tokens=int(inp), output_tokens=int(out), cached_tokens=int(cached))
+
+
+# --------------------------------------------------------------------------- tools
+
+
+def instrument_tool(name: str | Callable | None = None) -> Callable:
+    """Wrap a tool/function so each invocation emits a ``ToolCall`` on the bus.
+
+    Usable as ``@instrument_tool`` or ``@instrument_tool("search")``. Mirrors :func:`instrument`:
+    idempotent, sync + async, replay-aware. The return value is stored on ``ToolCall.result`` so
+    ``cassette`` can record/replay tool side effects.
+    """
+    if callable(name):  # bare @instrument_tool
+        return _wrap_tool(name, str(getattr(name, "__name__", "tool")))
+
+    def decorator(fn: Callable) -> Callable:
+        return _wrap_tool(fn, name or str(getattr(fn, "__name__", "tool")))
+
+    return decorator
+
+
+def _wrap_tool(fn: Callable, tool_name: str) -> Callable:
+    if getattr(fn, _WRAPPED, False):
+        return fn
+
+    if inspect.iscoroutinefunction(fn):
+
+        @functools.wraps(fn)
+        async def awrapper(*args: Any, **kwargs: Any) -> Any:
+            tc, start = _pre_tool(tool_name, args, kwargs)
+            replayed = _intercept(tc)
+            if replayed is not MISS:
+                tc.metadata["replayed"] = True
+                result = replayed
+            else:
+                result = await fn(*args, **kwargs)
+            _post_tool(tc, result, start)
+            return result
+
+        setattr(awrapper, _WRAPPED, True)
+        return awrapper
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        tc, start = _pre_tool(tool_name, args, kwargs)
+        replayed = _intercept(tc)
+        if replayed is not MISS:
+            tc.metadata["replayed"] = True
+            result = replayed
+        else:
+            result = fn(*args, **kwargs)
+        _post_tool(tc, result, start)
+        return result
+
+    setattr(wrapper, _WRAPPED, True)
+    return wrapper
+
+
+def _pre_tool(name: str, args: tuple, kwargs: dict) -> tuple[ToolCall, float]:
+    tc = ToolCall(
+        id=uuid.uuid4().hex,
+        name=name,
+        arguments={"args": list(args), "kwargs": dict(kwargs)},
+        ts=datetime.now(UTC),
+    )
+    return tc, time.perf_counter()
+
+
+def _post_tool(tc: ToolCall, result: Any, start: float) -> None:
+    tc.latency_ms = (time.perf_counter() - start) * 1000.0
+    tc.result = result
+    bus.emit(tc)

powerailabs_core-0.1.0/src/powerailabs/core/otel.py

@@ -0,0 +1,36 @@
+"""OpenTelemetry GenAI span helpers (optional). No-op if OTel isn't installed. docs/core.md §6.
+
+Emits ``gen_ai.*`` spans following the OpenTelemetry GenAI semantic conventions, so the whole
+stack speaks the standard everyone is converging on — no proprietary telemetry format.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any
+
+
+@contextmanager
+def span(model: str, *, provider: str | None = None, **attributes: Any) -> Iterator[Any]:
+    """Emit a ``gen_ai`` span around a call. Yields the span, or ``None`` if OTel is absent.
+
+    Args:
+        model: Model id, recorded as ``gen_ai.request.model``.
+        provider: Optional system name, recorded as ``gen_ai.system``.
+        **attributes: Extra span attributes to set verbatim.
+    """
+    try:
+        from opentelemetry import trace
+    except ImportError:
+        yield None
+        return
+
+    tracer = trace.get_tracer("powerailabs.core")
+    with tracer.start_as_current_span(f"chat {model}") as current:
+        current.set_attribute("gen_ai.request.model", model)
+        if provider is not None:
+            current.set_attribute("gen_ai.system", provider)
+        for key, value in attributes.items():
+            current.set_attribute(key, value)
+        yield current

powerailabs_core-0.1.0/src/powerailabs/core/prices.json

@@ -0,0 +1,12 @@
+{
+  "_note": "Illustrative snapshot of per-token USD rates. Not authoritative — refresh via prices.refresh(url=...) or replace with a real dated snapshot. See docs/core.md §7.",
+  "_updated": "2026-06-01",
+  "models": {
+    "gpt-4o":            {"input": 0.0000025,  "output": 0.00001,   "cached": 0.00000125},
+    "gpt-4o-mini":       {"input": 0.00000015, "output": 0.0000006},
+    "gpt-4.1":           {"input": 0.000002,   "output": 0.000008},
+    "claude-opus-4-8":   {"input": 0.000005,   "output": 0.000025,  "cached": 0.0000005},
+    "claude-sonnet-4-6": {"input": 0.000003,   "output": 0.000015},
+    "claude-haiku-4-5":  {"input": 0.0000008,  "output": 0.000004}
+  }
+}

powerailabs_core-0.1.0/src/powerailabs/core/prices.py

@@ -0,0 +1,117 @@
+"""Offline-first price registry: bundled snapshot + optional refresh. docs/core.md §7.
+
+A dated ``prices.json`` ships in the wheel, so cost estimation works with no network.
+``refresh(url=...)`` optionally pulls a *static* JSON file (GitHub raw / CDN) — never a
+running service — and falls back silently to the bundled snapshot if it can't.
+"""
+
+from __future__ import annotations
+
+import json
+from decimal import Decimal
+
+from .types import Money
+
+
+class UnknownModelError(KeyError):
+    """Raised when a model id is not present in the price table."""
+
+
+_table: dict | None = None
+_source: str = "bundled"
+
+
+def _bundled_text() -> str:
+    try:
+        from importlib.resources import files
+
+        return (files("powerailabs.core") / "prices.json").read_text(encoding="utf-8")
+    except Exception:
+        from pathlib import Path
+
+        return (Path(__file__).with_name("prices.json")).read_text(encoding="utf-8")
+
+
+def _ensure_loaded() -> dict:
+    global _table
+    if _table is None:
+        _table = json.loads(_bundled_text())
+    return _table
+
+
+def _rates(model: str) -> dict:
+    models = _ensure_loaded().get("models", {})
+    if model not in models:
+        raise UnknownModelError(model)
+    return models[model]
+
+
+def estimate(
+    model: str,
+    input_tokens: int,
+    output_tokens: int = 0,
+    cached_tokens: int = 0,
+) -> Money:
+    """Estimate the cost of a call from the price snapshot, as exact ``Decimal`` ``Money``.
+
+    Args:
+        model: Model id; must exist in the table (else :class:`UnknownModelError`).
+        input_tokens: Billed input tokens.
+        output_tokens: Billed output tokens.
+        cached_tokens: Cache-read tokens (priced at the model's ``cached`` rate if present).
+
+    Returns:
+        The estimated :class:`~powerailabs.core.types.Money` cost in USD.
+    """
+    r = _rates(model)
+    amount = (
+        Decimal(str(r["input"])) * input_tokens
+        + Decimal(str(r.get("output", 0))) * output_tokens
+        + Decimal(str(r.get("cached", 0))) * cached_tokens
+    )
+    return Money(amount)
+
+
+def models() -> list[str]:
+    """Sorted list of model ids known to the current price table."""
+    return sorted(_ensure_loaded().get("models", {}))
+
+
+def snapshot_date() -> str | None:
+    """The ``_updated`` date of the loaded snapshot, so callers can surface its age."""
+    return _ensure_loaded().get("_updated")
+
+
+def source() -> str:
+    """``"bundled"`` or ``"refreshed"`` — where the active table came from."""
+    return _source
+
+
+def refresh(url: str | None = None, *, timeout: float = 5.0) -> bool:
+    """Optionally replace the table from a static JSON URL. Never raises.
+
+    Returns ``True`` if the table was updated, ``False`` if no URL was given or the fetch
+    failed (the bundled/last-good snapshot stays active). docs/core.md §7.
+    """
+    global _table, _source
+    if not url:
+        return False
+    try:
+        import urllib.request
+
+        with urllib.request.urlopen(url, timeout=timeout) as resp:  # noqa: S310 - static JSON only
+            data = json.loads(resp.read().decode("utf-8"))
+        if isinstance(data, dict) and "models" in data:
+            _table = data
+            _source = "refreshed"
+            return True
+    except Exception:
+        return False
+    return False
+
+
+def _reset() -> None:
+    """Test helper: drop the loaded table so the bundled snapshot reloads."""
+    global _table, _source
+    _table = None
+    _source = "bundled"

powerailabs_core-0.1.0/src/powerailabs/core/protocols.py

@@ -0,0 +1,63 @@
+"""Structural interfaces shared across the stack. docs/core.md §2, architecture.md §2 (Layer 1).
+
+These are ``typing.Protocol``s, so a library satisfies an interface by *shape* — no imports, no
+base classes, zero directional coupling. ``squeeze`` *is* a ``Compressor`` without importing
+``contextkit``; ``acttrace`` *is* a ``Subscriber`` without importing the bus' producers.
+
+Grown incrementally as tools land: ``Compressor``/``EvictionStrategy``/``Handle`` (contextkit +
+squeeze), ``Sink``/``Subscriber`` (cassette + acttrace).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Handle(Protocol):
+    """A restore handle for a reversible compression. ``expand()`` returns the original."""
+
+    def expand(self) -> Any: ...
+
+
+@runtime_checkable
+class Compressor(Protocol):
+    """Shrinks content toward a token budget and returns a restorable :class:`Handle`.
+
+    ``squeeze`` satisfies this; ``contextkit`` accepts anything of this shape for
+    ``Block(evict="compress")`` without importing ``squeeze``.
+    """
+
+    def compress(
+        self,
+        content: Any,
+        *,
+        target_tokens: int | None = None,
+        model: str | None = None,
+        kind: str = "auto",
+    ) -> tuple[str, Handle]: ...
+
+
+@runtime_checkable
+class EvictionStrategy(Protocol):
+    """A pluggable per-block shrink rule. Returns ``(new_content_or_None, action_label)``.
+
+    ``None`` content means the block was dropped. ``contextkit`` ships string-named built-ins
+    (``drop_oldest``/``truncate``) and accepts custom strategies of this shape.
+    """
+
+    def evict(self, content: str, remaining_tokens: int, model: str) -> tuple[str | None, str]: ...
+
+
+@runtime_checkable
+class Sink(Protocol):
+    """A destination for records/entries (in-memory, JSONL, SQLite, OTel, ...)."""
+
+    def write(self, entry: Any) -> None: ...
+
+
+@runtime_checkable
+class Subscriber(Protocol):
+    """A bus subscriber: a callable that receives normalized events. ``acttrace`` is one."""
+
+    def __call__(self, event: Any) -> None: ...

powerailabs_core-0.1.0/src/powerailabs/core/tokens.py

@@ -0,0 +1,102 @@
+"""Provider-aware token counting. docs/core.md §4, §8.
+
+Best-effort and **offline by default**: a character-based heuristic per model family,
+so counting never hits the network and is fully deterministic. If ``tiktoken`` is installed
+(``pip install powerailabs-core[tiktoken]``) it is used for exact OpenAI counts. Register a
+precise counter for any family via :func:`register` to override the heuristic.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable
+
+# Counts for chat messages add a small fixed overhead per message plus a one-off priming
+# cost, mirroring the framing real chat tokenizers add around each turn.
+_MESSAGE_OVERHEAD = 4
+_PRIMING = 3
+
+# Approximate characters-per-token by family (heuristic fallback). Documented accuracy:
+# within ~10-15% of provider tokenizers for English prose.
+_CHARS_PER_TOKEN: dict[str, float] = {
+    "openai": 4.0,
+    "anthropic": 3.5,
+    "default": 4.0,
+}
+
+Counter = Callable[["str | list[dict]", str], int]
+_counters: dict[str, Counter] = {}
+
+
+def family(model: str) -> str:
+    """Tokenizer family for a model id: ``"openai"``, ``"anthropic"``, or ``"default"``."""
+    m = model.lower()
+    if m.startswith(("gpt", "o1", "o3", "o4", "chatgpt", "text-", "davinci")):
+        return "openai"
+    if m.startswith("claude"):
+        return "anthropic"
+    return "default"
+
+
+def register(fam: str, counter: Counter) -> None:
+    """Override the counter for a family (e.g. plug in a precise tokenizer). See docs/core.md §8."""
+    _counters[fam] = counter
+
+
+def count(text_or_messages: str | list[dict], model: str) -> int:
+    """Count tokens for a string or a list of chat messages under ``model``.
+
+    Args:
+        text_or_messages: Raw text, or a list of ``{"role", "content"}`` message dicts.
+            ``content`` may itself be a list of content blocks (multimodal); text parts are summed.
+        model: The model id; selects the tokenizer family.
+
+    Returns:
+        The estimated token count.
+    """
+    fam = family(model)
+    if fam in _counters:
+        return _counters[fam](text_or_messages, model)
+
+    if isinstance(text_or_messages, str):
+        return _count_text(text_or_messages, fam, model)
+
+    total = _PRIMING
+    for msg in text_or_messages:
+        total += _MESSAGE_OVERHEAD
+        total += _count_text(_message_text(msg), fam, model)
+    return total
+
+
+def _message_text(msg: dict) -> str:
+    content = msg.get("content", "")
+    if isinstance(content, list):
+        parts = [p.get("text", "") for p in content if isinstance(p, dict)]
+        return "".join(parts)
+    return str(content or "")
+
+
+def _count_text(text: str, fam: str, model: str) -> int:
+    if not text:
+        return 0
+    if fam == "openai":
+        enc = _tiktoken_encoding(model)
+        if enc is not None:
+            return len(enc.encode(text))
+    cpt = _CHARS_PER_TOKEN.get(fam, _CHARS_PER_TOKEN["default"])
+    return math.ceil(len(text) / cpt)
+
+
+def _tiktoken_encoding(model: str):  # noqa: ANN202 - third-party type is optional
+    """Return a tiktoken encoding for ``model`` if tiktoken is installed, else ``None``."""
+    try:
+        import tiktoken
+    except ImportError:
+        return None
+    try:
+        return tiktoken.encoding_for_model(model)
+    except KeyError:
+        try:
+            return tiktoken.get_encoding("o200k_base")
+        except Exception:
+            return None

powerailabs_core-0.1.0/src/powerailabs/core/types.py

@@ -0,0 +1,117 @@
+"""Canonical data types shared across the powerailabs stack. See docs/core.md §5."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from decimal import Decimal
+
+
+@dataclass(frozen=True)
+class Usage:
+    """Token usage for a single LLM call."""
+
+    input_tokens: int
+    output_tokens: int = 0
+    cached_tokens: int = 0
+
+    @property
+    def total_tokens(self) -> int:
+        """Input + output tokens (cached tokens are a subset of input, not added)."""
+        return self.input_tokens + self.output_tokens
+
+
+@dataclass(frozen=True)
+class Money:
+    """A Decimal-backed monetary amount. Never use ``float`` for money.
+
+    Accepts ``int``/``float``/``str``/``Decimal`` for ``amount`` and coerces to
+    ``Decimal`` (floats via their string form, to avoid binary-float noise).
+    Arithmetic and comparisons require a matching ``currency``.
+    """
+
+    amount: Decimal
+    currency: str = "USD"
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.amount, Decimal):
+            object.__setattr__(self, "amount", Decimal(str(self.amount)))
+
+    @classmethod
+    def zero(cls, currency: str = "USD") -> Money:
+        """A zero amount in the given currency."""
+        return cls(Decimal("0"), currency)
+
+    def _check(self, other: Money) -> None:
+        if self.currency != other.currency:
+            raise ValueError(f"currency mismatch: {self.currency} vs {other.currency}")
+
+    def __add__(self, other: Money | int) -> Money:
+        if other == 0:  # supports sum([...]) which starts at 0
+            return self
+        if not isinstance(other, Money):
+            return NotImplemented
+        self._check(other)
+        return Money(self.amount + other.amount, self.currency)
+
+    __radd__ = __add__
+
+    def __sub__(self, other: Money) -> Money:
+        if not isinstance(other, Money):
+            return NotImplemented
+        self._check(other)
+        return Money(self.amount - other.amount, self.currency)
+
+    def __mul__(self, scalar: int | Decimal) -> Money:
+        return Money(self.amount * Decimal(str(scalar)), self.currency)
+
+    __rmul__ = __mul__
+
+    def __lt__(self, other: Money) -> bool:
+        self._check(other)
+        return self.amount < other.amount
+
+    def __le__(self, other: Money) -> bool:
+        self._check(other)
+        return self.amount <= other.amount
+
+    def __gt__(self, other: Money) -> bool:
+        self._check(other)
+        return self.amount > other.amount
+
+    def __ge__(self, other: Money) -> bool:
+        self._check(other)
+        return self.amount >= other.amount
+
+    def __str__(self) -> str:
+        return f"{self.amount} {self.currency}"
+
+
+@dataclass
+class LLMCall:
+    """A normalized provider-agnostic record of one model call. Emitted on the bus."""
+
+    id: str
+    provider: str
+    model: str
+    messages: list[dict]
+    usage: Usage | None = None
+    cost: Money | None = None
+    latency_ms: float | None = None
+    trace_id: str = ""
+    ts: datetime | None = None
+    metadata: dict = field(default_factory=dict)
+
+
+@dataclass
+class ToolCall:
+    """A normalized record of one tool invocation. Emitted when the dispatcher is wrapped."""
+
+    id: str
+    name: str
+    arguments: dict
+    result: object | None = None
+    latency_ms: float | None = None
+    trace_id: str = ""
+    ts: datetime | None = None
+    metadata: dict = field(default_factory=dict)

powerailabs_core-0.1.0/tests/test_bus.py

@@ -0,0 +1,9 @@
+from powerailabs.core import bus
+
+
+def test_emit_reaches_subscriber():
+    bus._reset()
+    seen = []
+    bus.subscribe(seen.append)
+    bus.emit("hello")
+    assert seen == ["hello"]

powerailabs_core-0.1.0/tests/test_instrument.py

@@ -0,0 +1,89 @@
+"""instrument(): mock clients only, no network. Idempotent wrap + normalized LLMCall events."""
+
+from decimal import Decimal
+from types import SimpleNamespace
+
+import pytest
+from powerailabs.core import bus, instrument
+from powerailabs.core.types import LLMCall, Money, Usage
+
+
+@pytest.fixture
+def events():
+    bus._reset()
+    seen: list = []
+    bus.subscribe(seen.append)
+    yield seen
+    bus._reset()
+
+
+def _openai_client(prompt_tokens=100, completion_tokens=50):
+    class Completions:
+        def create(self, **kwargs):
+            return SimpleNamespace(
+                usage=SimpleNamespace(
+                    prompt_tokens=prompt_tokens, completion_tokens=completion_tokens
+                )
+            )
+
+    return SimpleNamespace(chat=SimpleNamespace(completions=Completions()))
+
+
+def _anthropic_async_client(input_tokens=10, output_tokens=20):
+    class Messages:
+        async def create(self, **kwargs):
+            return SimpleNamespace(
+                usage=SimpleNamespace(input_tokens=input_tokens, output_tokens=output_tokens)
+            )
+
+    return SimpleNamespace(messages=Messages())
+
+
+def test_sync_openai_emits_normalized_llmcall(events):
+    client = instrument(_openai_client())
+    client.chat.completions.create(model="gpt-4o", messages=[{"role": "user", "content": "hi"}])
+
+    assert len(events) == 1
+    call = events[0]
+    assert isinstance(call, LLMCall)
+    assert call.provider == "openai"
+    assert call.model == "gpt-4o"
+    assert call.usage == Usage(input_tokens=100, output_tokens=50)
+    assert isinstance(call.cost, Money)
+    # 0.0000025*100 + 0.00001*50 = 0.00075
+    assert call.cost.amount == Decimal("0.00075")
+    assert call.latency_ms is not None and call.latency_ms >= 0
+
+
+def test_instrument_is_idempotent(events):
+    client = _openai_client()
+    instrument(client)
+    first = client.chat.completions.create
+    returned = instrument(client)
+    assert returned is client
+    assert client.chat.completions.create is first  # not double-wrapped
+
+    client.chat.completions.create(model="gpt-4o", messages=[])
+    assert len(events) == 1  # exactly one event per call, not two
+
+
+async def test_async_anthropic_emits_event(events):
+    client = instrument(_anthropic_async_client())
+    await client.messages.create(
+        model="claude-opus-4-8", messages=[{"role": "user", "content": "hi"}]
+    )
+    assert len(events) == 1
+    assert events[0].provider == "anthropic"
+    assert events[0].usage == Usage(input_tokens=10, output_tokens=20)
+
+
+def test_unknown_client_returned_untouched(events):
+    sentinel = SimpleNamespace(foo="bar")
+    assert instrument(sentinel) is sentinel
+
+
+def test_unpriced_model_yields_no_cost(events):
+    client = instrument(_openai_client())
+    client.chat.completions.create(model="totally-unknown", messages=[])
+    assert events[0].cost is None
+    assert events[0].usage is not None  # usage still captured

powerailabs_core-0.1.0/tests/test_otel.py

@@ -0,0 +1,9 @@
+"""otel.span is a no-op (yields None) when OpenTelemetry isn't installed — never raises."""
+
+from powerailabs.core import otel
+
+
+def test_span_is_noop_without_otel():
+    # OTel is an optional extra and not installed in the test env.
+    with otel.span("gpt-4o", provider="openai", custom="x") as s:
+        assert s is None

powerailabs_core-0.1.0/tests/test_prices.py

@@ -0,0 +1,72 @@
+"""Prices: exact Decimal estimates from the bundled snapshot + offline refresh fallback."""
+
+from decimal import Decimal
+
+import pytest
+from powerailabs.core import prices
+from powerailabs.core.types import Money
+
+
+@pytest.fixture(autouse=True)
+def _fresh_table():
+    prices._reset()
+    yield
+    prices._reset()
+
+
+def test_estimate_is_exact_decimal_money():
+    # 0.000005*1200 + 0.000025*300 = 0.006 + 0.0075 = 0.0135
+    cost = prices.estimate("claude-opus-4-8", input_tokens=1200, output_tokens=300)
+    assert isinstance(cost, Money)
+    assert cost.amount == Decimal("0.0135")
+
+
+def test_estimate_includes_cached_rate():
+    # 0.0000025*1000 + 0.00001*500 + 0.00000125*200 = 0.0025 + 0.005 + 0.00025 = 0.00775
+    cost = prices.estimate("gpt-4o", 1000, 500, cached_tokens=200)
+    assert cost.amount == Decimal("0.00775")
+
+
+def test_unknown_model_raises():
+    with pytest.raises(prices.UnknownModelError):
+        prices.estimate("does-not-exist", 100)
+
+
+def test_bundled_snapshot_metadata():
+    assert prices.source() == "bundled"
+    assert prices.snapshot_date() == "2026-06-01"
+    assert "claude-opus-4-8" in prices.models()
+
+
+def test_refresh_no_url_is_noop():
+    assert prices.refresh() is False
+    assert prices.source() == "bundled"
+
+
+def test_refresh_falls_back_silently_when_offline(monkeypatch):
+    def boom(*args, **kwargs):
+        raise OSError("no network")
+
+    monkeypatch.setattr("urllib.request.urlopen", boom)
+    assert prices.refresh("https://example.com/prices.json") is False
+    assert prices.source() == "bundled"
+    # bundled table still usable
+    assert prices.estimate("gpt-4o", 1000).amount == Decimal("0.0025")
+
+
+def test_refresh_updates_from_static_json(monkeypatch):
+    import contextlib
+    import io
+    import json
+
+    table = {"_updated": "2099-01-01", "models": {"gpt-4o": {"input": 0.001, "output": 0}}}
+    payload = json.dumps(table)
+
+    @contextlib.contextmanager
+    def fake_urlopen(url, timeout=5.0):
+        yield io.BytesIO(payload.encode("utf-8"))
+
+    monkeypatch.setattr("urllib.request.urlopen", fake_urlopen)
+    assert prices.refresh("https://example.com/prices.json") is True
+    assert prices.source() == "refreshed"
+    assert prices.estimate("gpt-4o", 1000).amount == Decimal("1")

powerailabs_core-0.1.0/tests/test_protocols.py

@@ -0,0 +1,27 @@
+"""Protocols are structural: an object satisfies one by shape, with no import or base class."""
+
+from powerailabs.core import protocols
+
+
+def test_compressor_is_satisfied_by_shape():
+    class MyCompressor:
+        def compress(self, content, *, target_tokens=None, model=None, kind="auto"):
+            return content[: target_tokens or 10], None
+
+    assert isinstance(MyCompressor(), protocols.Compressor)
+    assert not isinstance(object(), protocols.Compressor)
+
+
+def test_subscriber_and_sink_shapes():
+    assert isinstance(lambda event: None, protocols.Subscriber)
+
+    class JsonlSink:
+        def write(self, entry):
+            pass
+
+    assert isinstance(JsonlSink(), protocols.Sink)
+
+
+def test_handle_and_eviction_protocols_exist():
+    assert hasattr(protocols, "Handle")
+    assert hasattr(protocols, "EvictionStrategy")

powerailabs_core-0.1.0/tests/test_tokens.py

@@ -0,0 +1,49 @@
+"""Golden token counts: known input -> expected count per model family. No network.
+
+OpenAI counts are forced onto the heuristic path (tiktoken absent / patched off) so the
+goldens are deterministic regardless of whether tiktoken happens to be installed.
+"""
+
+import pytest
+from powerailabs.core import tokens
+
+
+@pytest.fixture(autouse=True)
+def _no_tiktoken(monkeypatch):
+    # Force the offline heuristic so OpenAI goldens are stable everywhere.
+    monkeypatch.setattr(tokens, "_tiktoken_encoding", lambda model: None)
+    yield
+
+
+def test_family_detection():
+    assert tokens.family("gpt-4o") == "openai"
+    assert tokens.family("o3-mini") == "openai"
+    assert tokens.family("claude-opus-4-8") == "anthropic"
+    assert tokens.family("mistral-large") == "default"
+
+
+def test_golden_text_counts_differ_by_family():
+    # "hello world" is 11 chars: openai @4.0 -> 3, anthropic @3.5 -> 4.
+    assert tokens.count("hello world", "gpt-4o") == 3
+    assert tokens.count("hello world", "claude-opus-4-8") == 4
+    assert tokens.count("", "gpt-4o") == 0
+
+
+def test_golden_message_counts_include_overhead():
+    # priming(3) + per-message overhead(4) + content(3) = 10
+    msgs = [{"role": "user", "content": "hello world"}]
+    assert tokens.count(msgs, "gpt-4o") == 10
+
+
+def test_multimodal_content_blocks_sum_text():
+    content = [{"type": "text", "text": "hello world"}, {"type": "image"}]
+    msgs = [{"role": "user", "content": content}]
+    assert tokens.count(msgs, "gpt-4o") == 10
+
+
+def test_register_overrides_family():
+    tokens.register("default", lambda t, m: 42)
+    try:
+        assert tokens.count("anything", "some-unknown-model") == 42
+    finally:
+        tokens._counters.clear()

powerailabs_core-0.1.0/tests/test_tools_and_replay.py

@@ -0,0 +1,79 @@
+"""instrument_tool emits ToolCall; interceptors short-circuit calls (replay). No network."""
+
+from types import SimpleNamespace
+
+import pytest
+from powerailabs.core import bus, instrument, instrument_tool
+from powerailabs.core.instrument import MISS, add_interceptor, remove_interceptor
+from powerailabs.core.types import LLMCall, ToolCall
+
+
+@pytest.fixture
+def events():
+    bus._reset()
+    seen: list = []
+    bus.subscribe(seen.append)
+    yield seen
+    bus._reset()
+
+
+def test_instrument_tool_emits_toolcall(events):
+    @instrument_tool
+    def search(query, top_k=3):
+        return [f"result for {query}"]
+
+    out = search("refunds", top_k=2)
+    assert out == ["result for refunds"]
+    assert len(events) == 1
+    tc = events[0]
+    assert isinstance(tc, ToolCall)
+    assert tc.name == "search"
+    assert tc.arguments == {"args": ["refunds"], "kwargs": {"top_k": 2}}
+    assert tc.result == ["result for refunds"]
+
+
+def test_instrument_tool_named_and_idempotent(events):
+    @instrument_tool("lookup")
+    def f(x):
+        return x
+
+    wrapped_again = instrument_tool("lookup")(f)
+    assert wrapped_again is f  # idempotent
+    f(5)
+    assert events[0].name == "lookup"
+
+
+async def test_async_tool(events):
+    @instrument_tool
+    async def fetch(url):
+        return "body"
+
+    assert await fetch("http://x") == "body"
+    assert events[0].name == "fetch"
+
+
+def test_interceptor_replays_llm_call_without_running_it(events):
+    calls = {"n": 0}
+
+    class Completions:
+        def create(self, **kwargs):
+            calls["n"] += 1
+            return SimpleNamespace(usage=SimpleNamespace(prompt_tokens=1, completion_tokens=1))
+
+    client = instrument(SimpleNamespace(chat=SimpleNamespace(completions=Completions())))
+
+    canned = SimpleNamespace(usage=SimpleNamespace(prompt_tokens=10, completion_tokens=20))
+
+    def replayer(event):
+        return canned if isinstance(event, LLMCall) else MISS
+
+    add_interceptor(replayer)
+    try:
+        resp = client.chat.completions.create(model="gpt-4o", messages=[])
+    finally:
+        remove_interceptor(replayer)
+
+    assert resp is canned
+    assert calls["n"] == 0  # real method never ran
+    assert events[0].metadata.get("replayed") is True
+    assert events[0].usage.input_tokens == 10  # usage taken from the replayed response

powerailabs_core-0.1.0/tests/test_types.py

@@ -0,0 +1,42 @@
+"""Money arithmetic must be exact (Decimal) and never use float. See write-tests skill."""
+
+from decimal import Decimal
+
+import pytest
+from powerailabs.core.types import Money, Usage
+
+
+def test_money_coerces_to_decimal_without_float_noise():
+    # 0.1 + 0.2 is the classic float trap; Money must stay exact.
+    assert (Money(0.1) + Money(0.2)).amount == Decimal("0.3")
+    assert Money(0.1).amount == Decimal("0.1")
+    assert Money("0.0000025").amount == Decimal("0.0000025")
+
+
+def test_money_arithmetic():
+    assert (Money(Decimal("0.01")) + Money(Decimal("0.02"))).amount == Decimal("0.03")
+    assert (Money(Decimal("0.05")) - Money(Decimal("0.02"))).amount == Decimal("0.03")
+    assert (Money(Decimal("0.001")) * 5).amount == Decimal("0.005")
+    assert (3 * Money(Decimal("0.002"))).amount == Decimal("0.006")
+
+
+def test_money_sum_starts_at_zero():
+    total = sum([Money(Decimal("0.01")), Money(Decimal("0.02")), Money(Decimal("0.03"))])
+    assert total == Money(Decimal("0.06"))
+
+
+def test_money_comparisons():
+    assert Money(Decimal("1")) < Money(Decimal("2"))
+    assert Money(Decimal("2")) >= Money(Decimal("2"))
+    assert Money.zero() == Money(Decimal("0"))
+
+
+def test_money_currency_mismatch_raises():
+    with pytest.raises(ValueError):
+        Money(Decimal("1"), "USD") + Money(Decimal("1"), "EUR")
+    with pytest.raises(ValueError):
+        _ = Money(Decimal("1"), "USD") < Money(Decimal("1"), "EUR")
+
+
+def test_usage_total():
+    assert Usage(input_tokens=100, output_tokens=50).total_tokens == 150