costzera 0.1.0__tar.gz

costzera-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.pytest_cache/

costzera-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 costzera-ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

costzera-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.5
+Name: costzera
+Version: 0.1.0
+Summary: Find and fix what makes AI agents slow and expensive. Prompts and completions never leave your process.
+Project-URL: Homepage, https://costzera.com
+Project-URL: Documentation, https://costzera.com/docs#sdk
+Project-URL: Repository, https://github.com/costzera-ai/costzera-sdk
+Project-URL: Issues, https://github.com/costzera-ai/costzera-sdk/issues
+Author: Costzera
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,cost,llm,observability,openinference,opentelemetry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Requires-Dist: opentelemetry-api>=1.24
+Requires-Dist: opentelemetry-sdk>=1.24
+Provides-Extra: anthropic
+Requires-Dist: openinference-instrumentation-anthropic; extra == 'anthropic'
+Provides-Extra: bedrock
+Requires-Dist: openinference-instrumentation-bedrock; extra == 'bedrock'
+Provides-Extra: crewai
+Requires-Dist: openinference-instrumentation-crewai; extra == 'crewai'
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Provides-Extra: dspy
+Requires-Dist: openinference-instrumentation-dspy; extra == 'dspy'
+Provides-Extra: langchain
+Requires-Dist: openinference-instrumentation-langchain; extra == 'langchain'
+Provides-Extra: litellm
+Requires-Dist: openinference-instrumentation-litellm; extra == 'litellm'
+Provides-Extra: llama-index
+Requires-Dist: openinference-instrumentation-llama-index; extra == 'llama-index'
+Provides-Extra: openai
+Requires-Dist: openinference-instrumentation-openai; extra == 'openai'
+Provides-Extra: openai-agents
+Requires-Dist: openinference-instrumentation-openai-agents; extra == 'openai-agents'
+Description-Content-Type: text/markdown
+
+# Costzera for Python
+
+Find and fix what makes your AI agents slow and expensive, without a tracing
+tool and without sending us your prompts.
+
+```bash
+pip install "costzera[openai]"      # or [anthropic], [langchain], [llama-index], ...
+export COSTZERA_API_KEY=czk_...      # Settings → API keys → Send traces
+```
+
+```python
+import costzera
+costzera.init(agent="support-agent")
+```
+
+That is the whole setup for agents built on OpenAI, Anthropic, LangChain,
+LlamaIndex, LiteLLM, CrewAI, Bedrock, the OpenAI Agents SDK or DSPy: their model,
+tool and retrieval calls are traced automatically.
+
+## Hand-written agents
+
+```python
+@costzera.tool
+def fetch_order(order_id: str) -> dict: ...
+
+with costzera.run("handle_ticket"):      # one trace per run of the agent
+    with costzera.step("plan"):           # a named stage within it
+        ...
+```
+
+Group each run of your agent in `costzera.run()`. Without it, every model call
+is its own trace, and Costzera cannot see loops, retries or repeated tool calls
+across a run.
+
+## What leaves your process
+
+Costzera receives the model, token counts, timings, errors, tool names, and the
+*sizes* and *fingerprints* of inputs and outputs. It never receives prompts,
+completions, tool arguments, tool results or retrieved documents. User and
+session ids are sent as fingerprints.
+
+This is enforced by allowlist in [`costzera/_wire.py`](https://github.com/costzera-ai/costzera-sdk/blob/main/python/src/costzera/_wire.py):
+a span is converted into what is sent, and only the attributes named there are
+copied. Anything else, including anything a framework adds in a future
+release, is never read into the payload.
+
+Exception messages are not sent by default, because they often quote the
+input that caused them. Only the exception's type is. Pass
+`error_messages=True` to send them, cut to 500 characters.
+
+## Already using OpenTelemetry?
+
+`init()` adds Costzera to your existing tracer provider instead of replacing
+it, so your current exporters keep working. To send the same traces to
+Langfuse, Phoenix or anything else, add their exporter as you normally would.
+
+## Options
+
+| `init(...)` | Default | |
+|---|---|---|
+| `agent` | `COSTZERA_AGENT` | The name the agent appears under in Costzera |
+| `api_key` | `COSTZERA_API_KEY` | A key with the Send traces scope |
+| `sample_rate` | `1.0` | Share of successful traces kept. Traces with an error are always kept |
+| `instrument` | `True` | Trace installed frameworks automatically |
+| `error_messages` | `False` | Also send exception messages |
+
+Without a key, `init()` logs once and does nothing.
+
+## Behaviour you can rely on
+
+- Only whole traces are sent, once their root span finishes.
+- Tracing never raises into your code. Export runs on a background thread with
+  bounded memory; if Costzera is unreachable, traces are dropped, not queued
+  forever.
+- Traces are batched, at most one request every 15 seconds per process under
+  steady load.
+- `costzera.flush()` sends what has finished, for short scripts and serverless
+  functions. It also runs at exit.
+
+## Licence
+
+MIT

costzera-0.1.0/README.md

@@ -0,0 +1,82 @@
+# Costzera for Python
+
+Find and fix what makes your AI agents slow and expensive, without a tracing
+tool and without sending us your prompts.
+
+```bash
+pip install "costzera[openai]"      # or [anthropic], [langchain], [llama-index], ...
+export COSTZERA_API_KEY=czk_...      # Settings → API keys → Send traces
+```
+
+```python
+import costzera
+costzera.init(agent="support-agent")
+```
+
+That is the whole setup for agents built on OpenAI, Anthropic, LangChain,
+LlamaIndex, LiteLLM, CrewAI, Bedrock, the OpenAI Agents SDK or DSPy: their model,
+tool and retrieval calls are traced automatically.
+
+## Hand-written agents
+
+```python
+@costzera.tool
+def fetch_order(order_id: str) -> dict: ...
+
+with costzera.run("handle_ticket"):      # one trace per run of the agent
+    with costzera.step("plan"):           # a named stage within it
+        ...
+```
+
+Group each run of your agent in `costzera.run()`. Without it, every model call
+is its own trace, and Costzera cannot see loops, retries or repeated tool calls
+across a run.
+
+## What leaves your process
+
+Costzera receives the model, token counts, timings, errors, tool names, and the
+*sizes* and *fingerprints* of inputs and outputs. It never receives prompts,
+completions, tool arguments, tool results or retrieved documents. User and
+session ids are sent as fingerprints.
+
+This is enforced by allowlist in [`costzera/_wire.py`](https://github.com/costzera-ai/costzera-sdk/blob/main/python/src/costzera/_wire.py):
+a span is converted into what is sent, and only the attributes named there are
+copied. Anything else, including anything a framework adds in a future
+release, is never read into the payload.
+
+Exception messages are not sent by default, because they often quote the
+input that caused them. Only the exception's type is. Pass
+`error_messages=True` to send them, cut to 500 characters.
+
+## Already using OpenTelemetry?
+
+`init()` adds Costzera to your existing tracer provider instead of replacing
+it, so your current exporters keep working. To send the same traces to
+Langfuse, Phoenix or anything else, add their exporter as you normally would.
+
+## Options
+
+| `init(...)` | Default | |
+|---|---|---|
+| `agent` | `COSTZERA_AGENT` | The name the agent appears under in Costzera |
+| `api_key` | `COSTZERA_API_KEY` | A key with the Send traces scope |
+| `sample_rate` | `1.0` | Share of successful traces kept. Traces with an error are always kept |
+| `instrument` | `True` | Trace installed frameworks automatically |
+| `error_messages` | `False` | Also send exception messages |
+
+Without a key, `init()` logs once and does nothing.
+
+## Behaviour you can rely on
+
+- Only whole traces are sent, once their root span finishes.
+- Tracing never raises into your code. Export runs on a background thread with
+  bounded memory; if Costzera is unreachable, traces are dropped, not queued
+  forever.
+- Traces are batched, at most one request every 15 seconds per process under
+  steady load.
+- `costzera.flush()` sends what has finished, for short scripts and serverless
+  functions. It also runs at exit.
+
+## Licence
+
+MIT

costzera-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "costzera"
+version = "0.1.0"
+description = "Find and fix what makes AI agents slow and expensive. Prompts and completions never leave your process."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Costzera" }]
+keywords = ["llm", "agents", "observability", "cost", "opentelemetry", "openinference"]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: System :: Monitoring",
+]
+dependencies = [
+  "opentelemetry-api>=1.24",
+  "opentelemetry-sdk>=1.24",
+]
+
+[project.optional-dependencies]
+openai = ["openinference-instrumentation-openai"]
+anthropic = ["openinference-instrumentation-anthropic"]
+langchain = ["openinference-instrumentation-langchain"]
+llama-index = ["openinference-instrumentation-llama-index"]
+litellm = ["openinference-instrumentation-litellm"]
+crewai = ["openinference-instrumentation-crewai"]
+bedrock = ["openinference-instrumentation-bedrock"]
+openai-agents = ["openinference-instrumentation-openai-agents"]
+dspy = ["openinference-instrumentation-dspy"]
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://costzera.com"
+Documentation = "https://costzera.com/docs#sdk"
+Repository = "https://github.com/costzera-ai/costzera-sdk"
+Issues = "https://github.com/costzera-ai/costzera-sdk/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/costzera"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

costzera-0.1.0/scripts/verify_cache_tokens.py

@@ -0,0 +1,26 @@
+"""Does the Anthropic instrumentor report cached tokens? Two calls sharing a
+cached ~6k-token system prompt; the second should read from the cache."""
+import gzip, json, os, sys
+from pathlib import Path
+for line in Path(sys.argv[1]).read_text(encoding="utf-8").splitlines():
+    if line.startswith("ANTHROPIC_API_KEY="):
+        os.environ["ANTHROPIC_API_KEY"] = line.split("=", 1)[1].strip().strip('"')
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
+import costzera, anthropic
+sent = []
+costzera.init(agent="cache-check", api_key="czk_local_only",
+              _transport=lambda b: (sent.append(json.loads(gzip.decompress(b))), (202, {}))[1])
+system = [{"type": "text", "text": "Reference notes. " + " ".join(f"Fact {i}: item {i} ships in {i % 7 + 1} days." for i in range(900)),
+           "cache_control": {"type": "ephemeral"}}]
+client = anthropic.Anthropic()
+usage = []
+with costzera.run("cache_run"):
+    for q in ("How long does item 5 take?", "How long does item 12 take?"):
+        r = client.messages.create(model="claude-opus-5-5", max_tokens=1024, output_config={"effort": "low"},
+                                   system=system, messages=[{"role": "user", "content": q}])
+        usage.append({k: getattr(r.usage, k, None) for k in ("input_tokens", "cache_creation_input_tokens", "cache_read_input_tokens", "output_tokens")})
+costzera.flush(10)
+print("API usage:", usage)
+for s in sent[0]["traces"][0]["spans"]:
+    if s["span_kind"] == "LLM":
+        print("span tokens:", {k: v for k, v in s["attributes"].items() if k.startswith("llm.token_count")})

costzera-0.1.0/scripts/verify_instrumentors.py

@@ -0,0 +1,174 @@
+"""Check what the real OpenInference instrumentors emit, through the SDK.
+
+Makes a few live Claude calls (Anthropic SDK, then LangChain), each a small
+tool-use exchange, with the Costzera SDK capturing what it *would* send --
+nothing goes to Costzera. Then checks:
+
+  - the secret marker in the prompt is in no payload;
+  - every LLM span carries model and token counts;
+  - tool spans exist and are named;
+  - each run is one complete trace.
+
+Writes the payloads to tests/fixtures/real_*.json for the server contract test,
+and prints the attribute names each instrumentor emitted (names only).
+
+    python scripts/verify_instrumentors.py path/to/.env   # needs ANTHROPIC_API_KEY
+"""
+
+from __future__ import annotations
+
+import gzip
+import json
+import os
+import sys
+from pathlib import Path
+
+from opentelemetry.sdk.trace import SpanProcessor
+
+MODEL = "claude-opus-5-5"
+SECRET = "ZEBRA-7741-account-code"
+HERE = Path(__file__).resolve().parent
+FIXTURES = HERE.parent / "tests" / "fixtures"
+
+
+def load_key(env_path: str) -> None:
+    for line in Path(env_path).read_text(encoding="utf-8").splitlines():
+        if line.startswith("ANTHROPIC_API_KEY="):
+            os.environ["ANTHROPIC_API_KEY"] = line.split("=", 1)[1].strip().strip('"')
+            return
+    sys.exit("ANTHROPIC_API_KEY not found in the env file")
+
+
+class RawKeys(SpanProcessor):
+    """Attribute names per span, as the instrumentor emitted them."""
+
+    def __init__(self):
+        self.spans = []
+
+    def on_end(self, span):
+        self.spans.append((span.name, (span.attributes or {}).get("openinference.span.kind"),
+                           sorted((span.attributes or {}).keys())))
+
+
+def main(env_path: str) -> int:
+    load_key(env_path)
+    sys.path.insert(0, str(HERE.parent / "src"))
+    import costzera
+
+    sent: list = []
+
+    def transport(body: bytes):
+        sent.append(json.loads(gzip.decompress(body)))
+        return 202, {"data": {"rejected": {"over_cap": 0}}}
+
+    assert costzera.init(agent="verify-agent", api_key="czk_local_only", _transport=transport)
+    raw = RawKeys()
+    costzera._provider.add_span_processor(raw)
+
+    question = f"My account code is {SECRET}. What is the status of order A-1001? Use the tool."
+    tool_schema = {
+        "name": "get_order_status",
+        "description": "Look up an order's shipping status by id.",
+        "input_schema": {
+            "type": "object",
+            "properties": {"order_id": {"type": "string"}},
+            "required": ["order_id"],
+        },
+    }
+
+    # ── 1. Anthropic SDK, a manual tool loop ─────────────────────────────
+    import anthropic
+
+    client = anthropic.Anthropic()
+
+    @costzera.tool
+    def get_order_status(order_id: str) -> dict:
+        return {"order_id": order_id, "status": "shipped", "note": SECRET}
+
+    with costzera.run("anthropic_sdk_run"):
+        messages = [{"role": "user", "content": question}]
+        first = client.messages.create(
+            model=MODEL, max_tokens=2048, output_config={"effort": "low"},
+            tools=[tool_schema], messages=messages,
+        )
+        messages.append({"role": "assistant", "content": first.content})
+        results = []
+        for block in first.content:
+            if block.type == "tool_use":
+                out = get_order_status(**block.input)
+                results.append({"type": "tool_result", "tool_use_id": block.id, "content": json.dumps(out)})
+        if results:
+            messages.append({"role": "user", "content": results})
+            client.messages.create(
+                model=MODEL, max_tokens=2048, output_config={"effort": "low"},
+                tools=[tool_schema], messages=messages,
+            )
+    costzera.flush(10)
+    anthropic_batches = list(sent)
+    sent.clear()
+
+    # ── 2. LangChain ─────────────────────────────────────────────────────
+    from langchain_anthropic import ChatAnthropic
+    from langchain_core.messages import HumanMessage, ToolMessage
+    from langchain_core.tools import tool as lc_tool
+
+    @lc_tool
+    def lookup_order(order_id: str) -> str:
+        """Look up an order's shipping status by id."""
+        return json.dumps({"order_id": order_id, "status": "shipped", "note": SECRET})
+
+    llm = ChatAnthropic(model=MODEL, max_tokens=2048).bind_tools([lookup_order])
+    with costzera.run("langchain_run"):
+        msgs = [HumanMessage(question)]
+        ai = llm.invoke(msgs)
+        msgs.append(ai)
+        for call in ai.tool_calls:
+            msgs.append(ToolMessage(lookup_order.invoke(call["args"]), tool_call_id=call["id"]))
+        if ai.tool_calls:
+            llm.invoke(msgs)
+    costzera.flush(10)
+    langchain_batches = list(sent)
+
+    # ── checks ───────────────────────────────────────────────────────────
+    FIXTURES.mkdir(parents=True, exist_ok=True)
+    ok = True
+    for label, batches in (("anthropic", anthropic_batches), ("langchain", langchain_batches)):
+        print(f"\n=== {label}: {len(batches)} request(s)")
+        if not batches:
+            print("  NOTHING SENT"); ok = False; continue
+        payload = batches[0] if len(batches) == 1 else {**batches[0], "traces": [t for b in batches for t in b["traces"]]}
+        (FIXTURES / f"real_{label}.json").write_text(json.dumps(payload, indent=2))
+        text = json.dumps(batches)
+        leaked = SECRET in text
+        print(f"  traces: {len(payload['traces'])}  secret in payload: {leaked}")
+        ok &= not leaked and len(payload["traces"]) == 1
+        for tr in payload["traces"]:
+            for s in tr["spans"]:
+                a, m = s["attributes"], s.get("measured", {})
+                if s["span_kind"] == "LLM":
+                    has = all(k in a for k in ("llm.token_count.prompt", "llm.token_count.completion")) and (
+                        "llm.model_name" in a)
+                    ok &= has
+                    print(f"  LLM  {s['name']:<28} model={a.get('llm.model_name')} in={a.get('llm.token_count.prompt')} "
+                          f"out={a.get('llm.token_count.completion')} cache_read={a.get('llm.token_count.prompt_details.cache_read')} "
+                          f"finish={m.get('finish_reason')} in_chars={m.get('input_chars')} {'OK' if has else 'MISSING FIELDS'}")
+                else:
+                    print(f"  {s['span_kind']:<4} {s['name']:<28} parent={'root' if not s['parent_id'] else 'child'} "
+                          f"tool={a.get('tool.name')} hash={str(m.get('input_hash'))[:8]} items={m.get('output_items')}")
+
+    print("\n=== attribute names emitted (raw, before conversion)")
+    seen = {}
+    for name, kind, keys in raw.spans:
+        for k in keys:
+            # Collapse indexed keys so the list stays readable.
+            import re
+            seen.setdefault(kind or "-", set()).add(re.sub(r"\.\d+\.", ".N.", k))
+    for kind, keys in sorted(seen.items()):
+        print(f"  {kind}: {', '.join(sorted(keys))}")
+
+    print("\nRESULT:", "PASS" if ok else "FAIL")
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1] if len(sys.argv) > 1 else ".env"))

costzera-0.1.0/src/costzera/__init__.py

@@ -0,0 +1,202 @@
+"""Costzera: find and fix what makes AI agents slow and expensive.
+
+    import costzera
+    costzera.init(agent="support-agent")      # reads COSTZERA_API_KEY
+
+That is the whole setup for agents built on a supported framework: their model,
+tool and retrieval calls are traced automatically. For hand-written agents:
+
+    @costzera.tool
+    def fetch_order(order_id): ...
+
+    with costzera.run("handle_ticket"):     # one trace per run of the agent
+        with costzera.step("plan"):          # a named stage within it
+            ...
+
+Prompts, completions, tool arguments and results never leave your process.
+Costzera receives their sizes and fingerprints, the model, token counts,
+timings and errors -- what it needs to find waste -- and nothing else. See
+`costzera._wire` for exactly what is sent.
+"""
+
+from __future__ import annotations
+
+import atexit
+import functools
+import inspect
+import json
+import logging
+import os
+import threading
+from contextlib import contextmanager
+from typing import Any, Callable, Iterator, Optional, TypeVar
+
+from opentelemetry import trace as otel_trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.trace import Status, StatusCode
+
+from ._instrument import instrument_installed
+from ._pipeline import Settings, TraceExporter, Transport
+
+__version__ = "0.1.0"
+__all__ = ["init", "run", "step", "tool", "flush", "shutdown", "__version__"]
+
+DEFAULT_ENDPOINT = "https://costzera.com/api/v1/traces"
+
+logger = logging.getLogger("costzera")
+F = TypeVar("F", bound=Callable[..., Any])
+
+_lock = threading.Lock()
+_exporter: Optional[TraceExporter] = None
+_provider: Optional[TracerProvider] = None
+
+
+def init(
+    agent: Optional[str] = None,
+    *,
+    api_key: Optional[str] = None,
+    endpoint: Optional[str] = None,
+    sample_rate: float = 1.0,
+    instrument: bool = True,
+    error_messages: bool = False,
+    _transport: Optional[Transport] = None,
+) -> bool:
+    """Start sending traces. Safe to call more than once; later calls do nothing.
+
+    agent:          the name this agent appears under in Costzera. Defaults to
+                    COSTZERA_AGENT.
+    api_key:        a Costzera key with the Send traces scope. Defaults to
+                    COSTZERA_API_KEY.
+    sample_rate:    the share of successful traces to keep, 0-1. Traces with an
+                    error are always kept.
+    instrument:     trace installed frameworks automatically.
+    error_messages: also send exception messages, cut to 500 characters. Off by
+                    default, because a message often quotes the input that
+                    caused it.
+
+    Returns True when tracing started. Without a key it logs once and does
+    nothing, so an unconfigured environment behaves exactly as before.
+    """
+    global _exporter, _provider
+    with _lock:
+        if _exporter is not None:
+            return True
+        key = api_key or os.environ.get("COSTZERA_API_KEY")
+        name = (agent or os.environ.get("COSTZERA_AGENT") or "").strip()
+        if not key:
+            logger.warning("Costzera is not tracing: set COSTZERA_API_KEY or pass api_key.")
+            return False
+        if not name:
+            logger.warning("Costzera is not tracing: pass agent= or set COSTZERA_AGENT.")
+            return False
+
+        settings = Settings(
+            api_key=key,
+            agent=name[:100],
+            endpoint=endpoint or os.environ.get("COSTZERA_ENDPOINT") or DEFAULT_ENDPOINT,
+            sdk_version=__version__,
+            sample_rate=min(1.0, max(0.0, float(sample_rate))),
+            error_messages=error_messages,
+        )
+        _exporter = TraceExporter(settings, transport=_transport)
+
+        # Join an OpenTelemetry setup the application already has rather than
+        # replacing it: its own exporters keep working, and ours is added.
+        current = otel_trace.get_tracer_provider()
+        if isinstance(current, TracerProvider):
+            _provider = current
+        else:
+            _provider = TracerProvider()
+            otel_trace.set_tracer_provider(_provider)
+        _provider.add_span_processor(_exporter)
+
+        if instrument:
+            instrument_installed(_provider)
+        atexit.register(shutdown)
+        return True
+
+
+def _tracer():
+    return (_provider or otel_trace.get_tracer_provider()).get_tracer("costzera", __version__)
+
+
+def _safe_json(value: Any) -> str:
+    try:
+        return json.dumps(value, default=str, sort_keys=True)
+    except Exception:
+        return repr(value)
+
+
+@contextmanager
+def _span(name: str, kind: str, attributes: Optional[dict] = None) -> Iterator[Any]:
+    attrs = {"openinference.span.kind": kind, **(attributes or {})}
+    with _tracer().start_as_current_span(name, attributes=attrs, record_exception=False) as span:
+        try:
+            yield span
+        except BaseException as exc:
+            span.record_exception(exc)
+            span.set_status(Status(StatusCode.ERROR))
+            raise
+
+
+@contextmanager
+def run(name: str = "run") -> Iterator[None]:
+    """One run of the agent: everything inside is one trace."""
+    with _span(name, "AGENT"):
+        yield
+
+
+@contextmanager
+def step(name: str) -> Iterator[None]:
+    """A named stage of a run, so cost and latency can be attributed to it."""
+    with _span(name, "CHAIN", {"metadata": json.dumps({"pipeline_step": name})}):
+        yield
+
+
+def tool(fn: Optional[F] = None, *, name: Optional[str] = None) -> Any:
+    """Trace a function as a tool call. Works on sync and async functions.
+
+    Arguments and the return value are recorded only so their size and
+    fingerprint can be measured; they are not sent.
+    """
+    def decorate(func: F) -> F:
+        tool_name = name or func.__name__
+
+        def attrs(args: tuple, kwargs: dict) -> dict:
+            return {"tool.name": tool_name, "input.value": _safe_json({"args": args, "kwargs": kwargs})}
+
+        if inspect.iscoroutinefunction(func):
+            @functools.wraps(func)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                with _span(tool_name, "TOOL", attrs(args, kwargs)) as span:
+                    result = await func(*args, **kwargs)
+                    span.set_attribute("output.value", _safe_json(result))
+                    return result
+            return async_wrapper  # type: ignore[return-value]
+
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            with _span(tool_name, "TOOL", attrs(args, kwargs)) as span:
+                result = func(*args, **kwargs)
+                span.set_attribute("output.value", _safe_json(result))
+                return result
+        return wrapper  # type: ignore[return-value]
+
+    return decorate(fn) if fn is not None else decorate
+
+
+def flush(timeout_s: float = 3.0) -> bool:
+    """Send everything finished so far. For short scripts and serverless."""
+    return _exporter.force_flush(int(timeout_s * 1000)) if _exporter else True
+
+
+def shutdown() -> None:
+    """Flush and stop. Registered at exit; call it yourself only to stop early."""
+    global _exporter
+    with _lock:
+        exporter, _exporter = _exporter, None
+    if exporter is not None:
+        try:
+            exporter.shutdown()
+        except Exception:
+            pass