traceiq-capture 0.1.0__py3-none-any.whl

traceiq/__init__.py

@@ -0,0 +1,17 @@
+"""TraceIQ Capture — OpenTelemetry instrumentation with a locked attribute contract."""
+
+from traceiq._context import clear_context, set_context
+from traceiq._init import flush, init
+from traceiq.decorators import agent, task, tool, workflow
+
+__all__ = [
+    "init",
+    "flush",
+    "set_context",
+    "clear_context",
+    "workflow",
+    "task",
+    "tool",
+    "agent",
+]
+__version__ = "0.1.0"

traceiq/_compat.py

@@ -0,0 +1,113 @@
+"""Normalize gen_ai.* token/model/provider attrs (read-only fallbacks)."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, MutableMapping
+
+ATTR_SYSTEM = "gen_ai.system"
+ATTR_REQUEST_MODEL = "gen_ai.request.model"
+ATTR_RESPONSE_MODEL = "gen_ai.response.model"
+ATTR_INPUT_TOKENS = "gen_ai.usage.input_tokens"
+ATTR_OUTPUT_TOKENS = "gen_ai.usage.output_tokens"
+ATTR_PROMPT_TOKENS = "gen_ai.usage.prompt_tokens"
+ATTR_COMPLETION_TOKENS = "gen_ai.usage.completion_tokens"
+ATTR_PROVIDER_NAME = "gen_ai.provider.name"
+
+# Cache key variants seen in the wild
+CACHE_READ_CANDIDATES = (
+    "gen_ai.usage.cache_read_input_tokens",
+    "gen_ai.usage.cache_read_tokens",
+    "llm.usage.cache_read_input_tokens",
+)
+CACHE_WRITE_CANDIDATES = (
+    "gen_ai.usage.cache_creation_input_tokens",
+    "gen_ai.usage.cache_write_tokens",
+    "llm.usage.cache_creation_input_tokens",
+)
+
+_MODEL_PREFIX_TO_SYSTEM = (
+    (("gpt-", "o1", "o3", "text-embedding", "whisper", "tts-"), "openai"),
+    (("claude-",), "anthropic"),
+    (("gemini-",), "google"),
+)
+
+
+def _get(attrs: Mapping[str, Any], *keys: str) -> Any:
+    for key in keys:
+        if key in attrs and attrs[key] is not None:
+            return attrs[key]
+    return None
+
+
+def normalize_tokens(attrs: MutableMapping[str, Any]) -> None:
+    """prompt/completion → input/output tokens."""
+    if ATTR_INPUT_TOKENS not in attrs:
+        legacy = _get(attrs, ATTR_PROMPT_TOKENS, "llm.usage.prompt_tokens")
+        if legacy is not None:
+            attrs[ATTR_INPUT_TOKENS] = int(legacy)
+    if ATTR_OUTPUT_TOKENS not in attrs:
+        legacy = _get(attrs, ATTR_COMPLETION_TOKENS, "llm.usage.completion_tokens")
+        if legacy is not None:
+            attrs[ATTR_OUTPUT_TOKENS] = int(legacy)
+
+
+def ensure_model(attrs: MutableMapping[str, Any]) -> None:
+    if ATTR_REQUEST_MODEL not in attrs or not attrs[ATTR_REQUEST_MODEL]:
+        resp = _get(attrs, ATTR_RESPONSE_MODEL, "llm.request.model", "llm.model_name")
+        if resp:
+            attrs[ATTR_REQUEST_MODEL] = str(resp)
+
+
+def ensure_provider(attrs: MutableMapping[str, Any]) -> None:
+    if attrs.get(ATTR_SYSTEM):
+        return
+    provider = _get(attrs, ATTR_PROVIDER_NAME)
+    if provider:
+        attrs[ATTR_SYSTEM] = str(provider)
+        return
+    model = str(attrs.get(ATTR_REQUEST_MODEL) or "")
+    lower = model.lower()
+    for prefixes, system in _MODEL_PREFIX_TO_SYSTEM:
+        if any(lower.startswith(p) for p in prefixes):
+            attrs[ATTR_SYSTEM] = system
+            return
+
+
+def extract_cache_usage(attrs: Mapping[str, Any]) -> dict[str, int]:
+    out: dict[str, int] = {}
+    for key in CACHE_READ_CANDIDATES:
+        if key in attrs and attrs[key] is not None:
+            out["traceiq.usage.cache_read_tokens"] = int(attrs[key])
+            break
+    for key in CACHE_WRITE_CANDIDATES:
+        if key in attrs and attrs[key] is not None:
+            out["traceiq.usage.cache_write_tokens"] = int(attrs[key])
+            break
+    return out
+
+
+def extract_audio_vision_usage(attrs: Mapping[str, Any]) -> dict[str, int]:
+    out: dict[str, int] = {}
+    audio_in = _get(
+        attrs,
+        "gen_ai.usage.input_audio_tokens",
+        "traceiq.usage.audio_input_tokens",
+    )
+    audio_out = _get(
+        attrs,
+        "gen_ai.usage.output_audio_tokens",
+        "traceiq.usage.audio_output_tokens",
+    )
+    vision = _get(
+        attrs,
+        "gen_ai.usage.image_tokens",
+        "llm.usage.image_tokens",
+        "traceiq.usage.vision_tokens",
+    )
+    if audio_in is not None:
+        out["traceiq.usage.audio_input_tokens"] = int(audio_in)
+    if audio_out is not None:
+        out["traceiq.usage.audio_output_tokens"] = int(audio_out)
+    if vision is not None:
+        out["traceiq.usage.vision_tokens"] = int(vision)
+    return out

traceiq/_context.py

@@ -0,0 +1,120 @@
+"""Process globals + per-request ContextVar (locked §3.1 fields only)."""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from dataclasses import dataclass, fields
+from typing import Any
+
+INGEST_SOURCE = "sdk"
+
+# Allowlisted ContextVar keys (set_context)
+_CONTEXT_KEYS = frozenset(
+    {
+        "workflow_id",
+        "agent_name",
+        "product_id",
+        "product_name",
+        "project_id",
+        "project_name",
+    }
+)
+
+
+@dataclass
+class _Globals:
+    app_name: str = ""
+    environment: str = ""
+    ingest_source: str = INGEST_SOURCE
+    api_key: str = ""
+    endpoint: str = ""
+    export_mode: str = "otlp"
+    disable_batch: bool = False
+    initialized: bool = False
+
+
+@dataclass
+class _RequestContext:
+    workflow_id: str = ""
+    agent_name: str = ""
+    product_id: str = ""
+    product_name: str = ""
+    project_id: str = ""
+    project_name: str = ""
+
+
+_globals = _Globals()
+_request_ctx: ContextVar[_RequestContext] = ContextVar(
+    "traceiq_request_ctx", default=_RequestContext()
+)
+
+
+def configure_globals(
+    *,
+    app_name: str = "",
+    environment: str = "",
+    api_key: str = "",
+    endpoint: str = "",
+    export_mode: str = "otlp",
+    disable_batch: bool = False,
+) -> None:
+    _globals.app_name = app_name or ""
+    _globals.environment = environment or ""
+    _globals.ingest_source = INGEST_SOURCE
+    _globals.api_key = api_key or ""
+    _globals.endpoint = (endpoint or "").rstrip("/")
+    _globals.export_mode = export_mode or "otlp"
+    _globals.disable_batch = bool(disable_batch)
+    _globals.initialized = True
+
+
+def get_globals() -> _Globals:
+    return _globals
+
+
+def set_context(**kwargs: Any) -> None:
+    """Per-request dims. Allowed: workflow_id, agent_name, product_*, project_*."""
+    unknown = set(kwargs) - _CONTEXT_KEYS
+    if unknown:
+        raise TypeError(f"Unknown set_context fields: {sorted(unknown)}")
+    current = _request_ctx.get()
+    data = {f.name: getattr(current, f.name) for f in fields(current)}
+    for key, value in kwargs.items():
+        if value is None:
+            continue
+        data[key] = str(value)
+    _request_ctx.set(_RequestContext(**data))
+
+
+def clear_context() -> None:
+    _request_ctx.set(_RequestContext())
+
+
+def get_request_context() -> _RequestContext:
+    return _request_ctx.get()
+
+
+def merged_trace_attrs() -> dict[str, str]:
+    """Globals + request context for stamping on every span (§3.1)."""
+    g = _globals
+    r = _request_ctx.get()
+    out: dict[str, str] = {
+        "traceiq.ingest_source": INGEST_SOURCE,
+    }
+    if g.app_name:
+        out["traceiq.app_name"] = g.app_name
+    if g.environment:
+        out["traceiq.environment"] = g.environment
+    if r.workflow_id:
+        out["traceiq.workflow_id"] = r.workflow_id
+    if r.agent_name:
+        out["traceiq.agent_name"] = r.agent_name
+    if r.product_id:
+        out["traceiq.product.id"] = r.product_id
+    if r.product_name:
+        out["traceiq.product.name"] = r.product_name
+    if r.project_id:
+        out["traceiq.project.id"] = r.project_id
+    if r.project_name:
+        out["traceiq.project.name"] = r.project_name
+    return out

traceiq/_enrich.py

@@ -0,0 +1,168 @@
+"""Lean enrichment — stamp §3 attrs; allowlist contract."""
+
+from __future__ import annotations
+
+from typing import Any, Sequence
+
+from opentelemetry.context import Context
+from opentelemetry.sdk.trace import ReadableSpan, Span, SpanProcessor
+from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
+
+from traceiq._compat import (
+    ensure_model,
+    ensure_provider,
+    extract_audio_vision_usage,
+    extract_cache_usage,
+    normalize_tokens,
+)
+from traceiq._context import merged_trace_attrs
+from traceiq._modality import ATTR_MODALITY, infer_modality
+from traceiq._step import ATTR_STEP_TYPE, infer_step_type
+
+TRACEIQ_ALLOWLIST = frozenset(
+    {
+        "traceiq.workflow_id",
+        "traceiq.environment",
+        "traceiq.app_name",
+        "traceiq.agent_name",
+        "traceiq.product.id",
+        "traceiq.product.name",
+        "traceiq.project.id",
+        "traceiq.project.name",
+        "traceiq.ingest_source",
+        "traceiq.step_type",
+        "traceiq.modality",
+        "traceiq.trace.root",
+        "traceiq.usage.cache_read_tokens",
+        "traceiq.usage.cache_write_tokens",
+        "traceiq.usage.audio_input_tokens",
+        "traceiq.usage.audio_output_tokens",
+        "traceiq.usage.vision_tokens",
+    }
+)
+
+GEN_AI_ALLOWLIST = frozenset(
+    {
+        "gen_ai.system",
+        "gen_ai.request.model",
+        "gen_ai.response.model",
+        "gen_ai.usage.input_tokens",
+        "gen_ai.usage.output_tokens",
+    }
+)
+
+
+def enrich_attributes(raw: dict[str, Any]) -> dict[str, Any]:
+    """Apply §3 enrichment. Never adds illicit traceiq.* keys."""
+    attrs = dict(raw)
+
+    for key, value in merged_trace_attrs().items():
+        if key in attrs and attrs[key] not in (None, ""):
+            continue
+        attrs[key] = value
+
+    normalize_tokens(attrs)
+    ensure_model(attrs)
+    ensure_provider(attrs)
+
+    step = infer_step_type(attrs)
+    if step:
+        attrs[ATTR_STEP_TYPE] = step
+
+    attrs[ATTR_MODALITY] = infer_modality(attrs)
+
+    for key, value in extract_cache_usage(attrs).items():
+        attrs[key] = value
+    for key, value in extract_audio_vision_usage(attrs).items():
+        attrs[key] = value
+
+    attrs["traceiq.ingest_source"] = "sdk"
+
+    for k in [k for k in attrs if k.startswith("traceiq.") and k not in TRACEIQ_ALLOWLIST]:
+        del attrs[k]
+
+    return attrs
+
+
+def filter_for_spans_json(attrs: dict[str, Any]) -> dict[str, Any]:
+    """Defense-in-depth for /v1/spans: only §3 + allowlisted gen_ai."""
+    out: dict[str, Any] = {}
+    for key, value in attrs.items():
+        if key.startswith("traceiq.") and key in TRACEIQ_ALLOWLIST:
+            out[key] = value
+        elif key in GEN_AI_ALLOWLIST:
+            out[key] = value
+    return out
+
+
+class LeanEnricher(SpanProcessor):
+    """Stamp process/request context as soon as a span starts (writable)."""
+
+    def on_start(self, span: Span, parent_context: Context | None = None) -> None:
+        for key, value in merged_trace_attrs().items():
+            if key not in (span.attributes or {}):
+                span.set_attribute(key, value)
+        span.set_attribute("traceiq.ingest_source", "sdk")
+
+    def on_end(self, span: ReadableSpan) -> None:
+        return
+
+    def shutdown(self) -> None:
+        return
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        return True
+
+
+class EnrichingSpanExporter(SpanExporter):
+    """Wraps an exporter; normalizes attrs on each span before export."""
+
+    def __init__(self, inner: SpanExporter, *, spans_json_filter: bool = False) -> None:
+        self._inner = inner
+        self._spans_json_filter = spans_json_filter
+
+    def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:
+        enriched: list[ReadableSpan] = []
+        for span in spans:
+            enriched.append(_span_with_attrs(span, self._spans_json_filter))
+        try:
+            return self._inner.export(enriched)
+        except Exception:
+            # Never break the agent path
+            import logging
+
+            logging.getLogger("traceiq").exception("span export failed")
+            return SpanExportResult.FAILURE
+
+    def shutdown(self) -> None:
+        self._inner.shutdown()
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        return self._inner.force_flush(timeout_millis)
+
+
+def _span_with_attrs(span: ReadableSpan, spans_json_filter: bool) -> ReadableSpan:
+    raw = dict(span.attributes or {})
+    enriched = enrich_attributes(raw)
+    if spans_json_filter:
+        # Keep non-traceiq instrumentation attrs for OTLP; filter only for JSON mode
+        # Callers set spans_json_filter when using /v1/spans exporter.
+        base = filter_for_spans_json(enriched)
+        # merge back identity-only? filter_for_spans_json already has allowlist
+        enriched = base
+
+    attrs_obj = getattr(span, "_attributes", None)
+    if isinstance(attrs_obj, dict):
+        attrs_obj.clear()
+        attrs_obj.update(enriched)
+        return span
+
+    # BoundedAttributes — replace via mutable copy if possible
+    try:
+        mutable = dict(attrs_obj) if attrs_obj is not None else {}
+        mutable.clear()
+        mutable.update(enriched)
+        object.__setattr__(span, "_attributes", mutable)
+    except Exception:
+        pass
+    return span

traceiq/_exporter.py

@@ -0,0 +1,220 @@
+"""OTLP/HTTP JSON exporter + optional TraceIQ /v1/spans JSON + file debug sink."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from datetime import datetime, timezone
+from typing import Any, Sequence
+from urllib.error import URLError
+from urllib.request import Request, urlopen
+
+from opentelemetry.sdk.trace import ReadableSpan
+from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
+
+from traceiq._enrich import enrich_attributes, filter_for_spans_json
+
+logger = logging.getLogger("traceiq")
+
+OTLP_TRACES_SUFFIX = "/v1/otlp/v1/traces"
+SPANS_PATH = "/v1/spans/batch"
+
+
+def normalize_otlp_endpoint(endpoint: str) -> str:
+    """Accept origin or full traces URL."""
+    ep = endpoint.rstrip("/")
+    if ep.endswith("/v1/otlp/v1/traces"):
+        return ep
+    if ep.endswith("/v1/otlp"):
+        return f"{ep}/v1/traces"
+    return f"{ep}{OTLP_TRACES_SUFFIX}"
+
+
+def _ns_to_iso(ns: int | None) -> str | None:
+    if ns is None:
+        return None
+    return datetime.fromtimestamp(ns / 1e9, tz=timezone.utc).isoformat()
+
+
+def _otlp_any_value(value: Any) -> dict[str, Any]:
+    if isinstance(value, bool):
+        return {"boolValue": value}
+    if isinstance(value, int) and not isinstance(value, bool):
+        return {"intValue": str(value)}
+    if isinstance(value, float):
+        return {"doubleValue": value}
+    if isinstance(value, bytes):
+        return {"bytesValue": value.hex()}
+    return {"stringValue": str(value)}
+
+
+def _otlp_attributes(attrs: dict[str, Any]) -> list[dict[str, Any]]:
+    return [{"key": k, "value": _otlp_any_value(v)} for k, v in attrs.items()]
+
+
+def readable_span_to_otlp(span: ReadableSpan) -> dict[str, Any]:
+    ctx = span.get_span_context()
+    parent = span.parent
+    parent_id = format(parent.span_id, "016x") if parent and parent.is_valid else ""
+    attrs = enrich_attributes(dict(span.attributes or {}))
+    status = span.status
+    status_code = 1  # UNSET
+    if status is not None:
+        # StatusCode.OK = 1 in OTel API but OTLP uses 1=OK, 2=ERROR after remap
+        from opentelemetry.trace import StatusCode
+
+        if status.status_code == StatusCode.OK:
+            status_code = 1
+        elif status.status_code == StatusCode.ERROR:
+            status_code = 2
+    body: dict[str, Any] = {
+        "traceId": format(ctx.trace_id, "032x"),
+        "spanId": format(ctx.span_id, "016x"),
+        "name": span.name,
+        "kind": int(span.kind.value) if span.kind is not None else 1,
+        "startTimeUnixNano": str(span.start_time or 0),
+        "endTimeUnixNano": str(span.end_time or 0),
+        "attributes": _otlp_attributes(attrs),
+        "status": {"code": status_code},
+    }
+    if parent_id:
+        body["parentSpanId"] = parent_id
+    return body
+
+
+def readable_span_to_traceiq_json(span: ReadableSpan) -> dict[str, Any]:
+    ctx = span.get_span_context()
+    parent = span.parent
+    parent_id = format(parent.span_id, "016x") if parent and parent.is_valid else ""
+    attrs = filter_for_spans_json(enrich_attributes(dict(span.attributes or {})))
+    start = span.start_time
+    end = span.end_time
+    duration_ms = None
+    if start is not None and end is not None:
+        duration_ms = (end - start) / 1e6
+    return {
+        "trace_id": format(ctx.trace_id, "032x"),
+        "span_id": format(ctx.span_id, "016x"),
+        "parent_span_id": parent_id,
+        "name": span.name,
+        "start_time": _ns_to_iso(start),
+        "end_time": _ns_to_iso(end),
+        "duration_ms": duration_ms,
+        "attributes": attrs,
+        "events": [],
+    }
+
+
+def _post_json(url: str, api_key: str, body: dict[str, Any]) -> None:
+    data = json.dumps(body).encode("utf-8")
+    req = Request(
+        url,
+        data=data,
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {api_key}",
+        },
+        method="POST",
+    )
+    with urlopen(req, timeout=30) as resp:
+        resp.read()
+
+
+class OTLPJsonSpanExporter(SpanExporter):
+    """POST ExportTraceServiceRequest-shaped JSON to TraceIQ OTLP endpoint."""
+
+    def __init__(self, endpoint: str, api_key: str) -> None:
+        self._url = normalize_otlp_endpoint(endpoint)
+        self._api_key = api_key
+
+    def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:
+        if not spans:
+            return SpanExportResult.SUCCESS
+        payload = {
+            "resourceSpans": [
+                {
+                    "resource": {
+                        "attributes": _otlp_attributes(
+                            {"service.name": "traceiq-sdk"}
+                        )
+                    },
+                    "scopeSpans": [
+                        {
+                            "scope": {"name": "traceiq", "version": "0.1.0"},
+                            "spans": [readable_span_to_otlp(s) for s in spans],
+                        }
+                    ],
+                }
+            ]
+        }
+        try:
+            _post_json(self._url, self._api_key, payload)
+            return SpanExportResult.SUCCESS
+        except (URLError, OSError, TimeoutError) as exc:
+            logger.warning("OTLP export failed: %s", exc)
+            return SpanExportResult.FAILURE
+
+    def shutdown(self) -> None:
+        return
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        return True
+
+
+class TraceIQSpansJsonExporter(SpanExporter):
+    """Fallback POST /v1/spans/batch with filtered attributes."""
+
+    def __init__(self, endpoint: str, api_key: str) -> None:
+        base = endpoint.rstrip("/")
+        if base.endswith("/v1/spans") or base.endswith("/v1/spans/batch"):
+            self._url = base if base.endswith("/batch") else f"{base}/batch"
+        else:
+            self._url = f"{base}{SPANS_PATH}"
+        self._api_key = api_key
+
+    def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:
+        if not spans:
+            return SpanExportResult.SUCCESS
+        body = {"spans": [readable_span_to_traceiq_json(s) for s in spans]}
+        try:
+            _post_json(self._url, self._api_key, body)
+            return SpanExportResult.SUCCESS
+        except (URLError, OSError, TimeoutError) as exc:
+            logger.warning("spans JSON export failed: %s", exc)
+            return SpanExportResult.FAILURE
+
+    def shutdown(self) -> None:
+        return
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        return True
+
+
+class FileSpanExporter(SpanExporter):
+    """Local debug: write enriched OTLP-ish JSON files under ./traces/."""
+
+    def __init__(self, directory: str = "./traces") -> None:
+        self._dir = directory
+        os.makedirs(self._dir, exist_ok=True)
+
+    def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:
+        for span in spans:
+            doc = readable_span_to_otlp(span)
+            path = os.path.join(
+                self._dir,
+                f"{doc['traceId']}_{doc['spanId']}.json",
+            )
+            try:
+                with open(path, "w", encoding="utf-8") as fh:
+                    json.dump(doc, fh, indent=2)
+            except OSError as exc:
+                logger.warning("file export failed: %s", exc)
+                return SpanExportResult.FAILURE
+        return SpanExportResult.SUCCESS
+
+    def shutdown(self) -> None:
+        return
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        return True

traceiq/_ids.py

@@ -0,0 +1,10 @@
+"""Stable id helpers for workflow_id derivation."""
+
+from __future__ import annotations
+
+import hashlib
+
+
+def stable_workflow_id(name: str) -> str:
+    """Deterministic workflow_id from a human name: sha1(name)[:16]."""
+    return hashlib.sha1(name.encode("utf-8")).hexdigest()[:16]

traceiq/_init.py

@@ -0,0 +1,167 @@
+"""traceiq.init / flush — TracerProvider, instrumentations, exporters."""
+
+from __future__ import annotations
+
+import atexit
+import importlib
+import logging
+import os
+from typing import Any
+
+from opentelemetry import trace
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import (
+    BatchSpanProcessor,
+    SimpleSpanProcessor,
+    SpanExporter,
+)
+
+from traceiq._context import configure_globals, get_globals
+from traceiq._enrich import EnrichingSpanExporter, LeanEnricher
+from traceiq._exporter import (
+    FileSpanExporter,
+    OTLPJsonSpanExporter,
+    TraceIQSpansJsonExporter,
+)
+
+logger = logging.getLogger("traceiq")
+
+FLUSH_INTERVAL_MS = 5000
+MAX_EXPORT_BATCH_SIZE = 512
+
+_provider: TracerProvider | None = None
+_atexit_registered = False
+_misconfig_warned = False
+
+
+def _instrument_installed() -> None:
+    for mod, starter in [
+        ("opentelemetry.instrumentation.openai", "OpenAIInstrumentor"),
+        ("opentelemetry.instrumentation.anthropic", "AnthropicInstrumentor"),
+        ("opentelemetry.instrumentation.langchain", "LangchainInstrumentor"),
+        ("opentelemetry.instrumentation.llamaindex", "LlamaIndexInstrumentor"),
+    ]:
+        try:
+            m = importlib.import_module(mod)
+            getattr(m, starter)().instrument()
+            logger.debug("instrumented %s", starter)
+        except Exception:
+            continue
+
+
+def _build_exporter(
+    *,
+    endpoint: str,
+    api_key: str,
+    export_mode: str,
+) -> SpanExporter:
+    if not endpoint:
+        return FileSpanExporter("./traces")
+    if export_mode == "spans":
+        return TraceIQSpansJsonExporter(endpoint, api_key)
+    return OTLPJsonSpanExporter(endpoint, api_key)
+
+
+def init(
+    *,
+    api_key: str | None = None,
+    endpoint: str | None = None,
+    app_name: str | None = None,
+    environment: str | None = None,
+    export_mode: str = "otlp",
+    disable_batch: bool = False,
+    exporter: SpanExporter | None = None,
+) -> None:
+    """
+    Configure TracerProvider, LeanEnricher, batch export, and installed OTel extras.
+
+    Zero-arg happy path: reads TRACEIQ_API_KEY, TRACEIQ_ENDPOINT, TRACEIQ_APP_NAME,
+    TRACEIQ_ENVIRONMENT from the environment. Empty endpoint → ./traces/ file export.
+    """
+    global _provider, _atexit_registered, _misconfig_warned
+
+    key = api_key if api_key is not None else os.environ.get("TRACEIQ_API_KEY", "")
+    ep = endpoint if endpoint is not None else os.environ.get("TRACEIQ_ENDPOINT", "")
+    name = (
+        app_name
+        if app_name is not None
+        else os.environ.get("TRACEIQ_APP_NAME", "traceiq-app")
+    ) or "traceiq-app"
+    env = (
+        environment
+        if environment is not None
+        else os.environ.get("TRACEIQ_ENVIRONMENT", "")
+    )
+
+    if ep and not key and not _misconfig_warned:
+        logger.warning(
+            "TRACEIQ_ENDPOINT is set but TRACEIQ_API_KEY is empty — "
+            "OTLP export will likely be rejected"
+        )
+        _misconfig_warned = True
+    if not ep and exporter is None:
+        logger.info("No TRACEIQ_ENDPOINT — writing spans to ./traces/")
+
+    configure_globals(
+        app_name=name,
+        environment=env,
+        api_key=key,
+        endpoint=ep,
+        export_mode=export_mode,
+        disable_batch=disable_batch,
+    )
+
+    resource = Resource.create({"service.name": name})
+    provider = TracerProvider(resource=resource)
+    provider.add_span_processor(LeanEnricher())
+
+    inner = exporter or _build_exporter(
+        endpoint=ep, api_key=key, export_mode=export_mode
+    )
+    # Always run enrichment before the concrete exporter
+    wrapped = EnrichingSpanExporter(
+        inner, spans_json_filter=(export_mode == "spans")
+    )
+
+    if disable_batch:
+        provider.add_span_processor(SimpleSpanProcessor(wrapped))
+    else:
+        provider.add_span_processor(
+            BatchSpanProcessor(
+                wrapped,
+                schedule_delay_millis=FLUSH_INTERVAL_MS,
+                max_export_batch_size=MAX_EXPORT_BATCH_SIZE,
+            )
+        )
+
+    try:
+        trace.set_tracer_provider(provider)
+    except Exception:
+        pass
+    _provider = provider
+
+    _instrument_installed()
+
+    if not _atexit_registered:
+        atexit.register(_atexit_flush)
+        _atexit_registered = True
+
+
+def flush(timeout_millis: int = 10_000) -> bool:
+    if _provider is None:
+        return True
+    return _provider.force_flush(timeout_millis)
+
+
+def _atexit_flush() -> None:
+    try:
+        flush()
+        if _provider is not None:
+            _provider.shutdown()
+    except Exception:
+        pass
+
+
+def get_provider() -> TracerProvider | None:
+    return _provider

traceiq/_modality.py

@@ -0,0 +1,32 @@
+"""Infer traceiq.modality from usage / request shape."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+ATTR_MODALITY = "traceiq.modality"
+
+
+def infer_modality(attrs: Mapping[str, Any]) -> str:
+    existing = attrs.get(ATTR_MODALITY)
+    if existing:
+        return str(existing)
+
+    has_vision = bool(
+        attrs.get("traceiq.usage.vision_tokens")
+        or attrs.get("gen_ai.usage.image_tokens")
+        or attrs.get("gen_ai.prompt.has_images")
+    )
+    has_audio = bool(
+        attrs.get("traceiq.usage.audio_input_tokens")
+        or attrs.get("traceiq.usage.audio_output_tokens")
+        or attrs.get("gen_ai.usage.input_audio_tokens")
+        or attrs.get("gen_ai.usage.output_audio_tokens")
+    )
+    if has_vision and has_audio:
+        return "multimodal"
+    if has_vision:
+        return "vision"
+    if has_audio:
+        return "audio"
+    return "text"

traceiq/_step.py

@@ -0,0 +1,27 @@
+"""Infer traceiq.step_type from decorator marks or span attrs."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+ATTR_STEP_TYPE = "traceiq.step_type"
+
+
+def infer_step_type(attrs: Mapping[str, Any]) -> str | None:
+    existing = attrs.get(ATTR_STEP_TYPE)
+    if existing:
+        return str(existing)
+
+    # Tool signals from instrumentations
+    if attrs.get("gen_ai.tool.name") or attrs.get("traceloop.entity.name") == "tool":
+        return "tool"
+
+    # LLM signals
+    if (
+        attrs.get("gen_ai.request.model")
+        or attrs.get("gen_ai.usage.input_tokens") is not None
+        or attrs.get("gen_ai.usage.prompt_tokens") is not None
+    ):
+        return "llm"
+
+    return None

traceiq/decorators.py

@@ -0,0 +1,147 @@
+"""@workflow / @task / @tool / @agent — thin OTel decorators (sync + async)."""
+
+# pyright: reportAttributeAccessIssue=false, reportArgumentType=false, reportAssignmentType=false
+
+from __future__ import annotations
+
+import functools
+import inspect
+from typing import Any, Callable, TypeVar
+
+from opentelemetry import trace
+from opentelemetry.trace import Status, StatusCode
+
+from traceiq._context import set_context
+from traceiq._ids import stable_workflow_id
+from traceiq._init import get_provider
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+TRACER_NAME = "traceiq"
+
+
+def _tracer():
+    """
+    Internal helper to obtain an OpenTelemetry tracer instance.
+    Code purpose: Ensures all tracing in this module uses a consistent tracer and version, whether or not a custom trace provider is registered.
+    Business purpose: Establishes the baseline for all traceable workflow, task, tool, and agent operations for downstream observability.
+    """
+    provider = get_provider()
+    if provider is not None:
+        return provider.get_tracer(TRACER_NAME, "0.1.0")
+    return trace.get_tracer(TRACER_NAME, "0.1.0")
+
+
+def _apply_kind_attrs(span: Any, kind: str, span_name: str, agent_name: str | None) -> None:
+    """
+    Adds kind-specific attributes to the OpenTelemetry span and updates TraceIQ context.
+    Code purpose: Configures metadata on spans according to their semantic kind (workflow, agent, etc.) for accurate attribution.
+    Business purpose: Enables filtering, grouping, and analysis of traces by logical step type in downstream analytics and dashboards.
+    """
+    span.set_attribute("traceiq.step_type", kind)
+    if kind == "workflow":
+        span.set_attribute("traceiq.trace.root", True)
+        wf_id = stable_workflow_id(span_name)
+        span.set_attribute("traceiq.workflow_id", wf_id)
+        set_context(workflow_id=wf_id)
+    if kind == "agent":
+        label = agent_name or span_name
+        span.set_attribute("traceiq.agent_name", label)
+        set_context(agent_name=label)
+
+
+def _decorate(kind: str, name: str | None, agent_name: str | None, fn: F) -> F:
+    """
+    Decorator implementation for workflow, task, tool, and agent.
+    Code purpose: Wraps sync and async functions in a tracing span, sets span attributes, captures errors, and manages context propagation.
+    Business purpose: Provides standardized, zero-boilerplate tracing instrumentation for business-critical process and execution steps.
+    """
+    span_name = name or fn.__name__
+
+    if inspect.iscoroutinefunction(fn):
+
+        @functools.wraps(fn)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+            with _tracer().start_as_current_span(span_name) as span:
+                _apply_kind_attrs(span, kind, span_name, agent_name)
+                try:
+                    return await fn(*args, **kwargs)
+                except Exception as exc:
+                    span.set_status(Status(StatusCode.ERROR, str(exc)))
+                    span.record_exception(exc)
+                    raise
+                else:
+                    span.set_status(Status(StatusCode.OK))
+
+        return async_wrapper  # type: ignore[return-value]
+
+    @functools.wraps(fn)
+    def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+        with _tracer().start_as_current_span(span_name) as span:
+            _apply_kind_attrs(span, kind, span_name, agent_name)
+            try:
+                return fn(*args, **kwargs)
+            except Exception as exc:
+                span.set_status(Status(StatusCode.ERROR, str(exc)))
+                span.record_exception(exc)
+                raise
+            else:
+                span.set_status(Status(StatusCode.OK))
+
+    return sync_wrapper  # type: ignore[return-value]
+
+
+def _factory(kind: str, name: str | None = None, agent_name: str | None = None):
+    """
+    Returns an appropriate decorator for the requested kind.
+    Code purpose: Supports flexible decorator syntax for both parameterized and parameterless use.
+    Business purpose: Allows business logic to be annotated with tracing decorators in multiple ergonomic styles.
+    """
+    def decorator(fn: F) -> F:
+        return _decorate(kind, name, agent_name, fn)
+
+    return decorator
+
+
+def workflow(name: str | None = None) -> Any:
+    """
+    Decorator for marking a function as a workflow for tracing.
+    Code purpose: Provides an entrypoint to instrument top-level orchestrations with TraceIQ tracing.
+    Business purpose: Identifies root workflow steps for business process tracking and performance reporting.
+    """
+    if callable(name):
+        return _decorate("workflow", name.__name__, None, name)
+    return _factory("workflow", name=name)
+
+
+def task(name: str | None = None) -> Any:
+    """
+    Decorator for marking a function as a task for tracing.
+    Code purpose: Supports the recording of logical tasks within a workflow for detailed trace breakdowns.
+    Business purpose: Enables analysis of individual business operations and their performance within orchestration.
+    """
+    if callable(name):
+        return _decorate("task", name.__name__, None, name)
+    return _factory("task", name=name)
+
+
+def tool(name: str | None = None) -> Any:
+    """
+    Decorator for marking a function as a tool step for tracing.
+    Code purpose: Tracks invocation and performance of tools/utilities used within workflows/tasks.
+    Business purpose: Allows correlation of supporting tool usage within business processes for audit and optimization.
+    """
+    if callable(name):
+        return _decorate("tool", name.__name__, None, name)
+    return _factory("tool", name=name)
+
+
+def agent(name: str | None = None) -> Any:
+    """
+    Decorator for marking a function as an agent step for tracing.
+    Code purpose: Adds agent-level attributes and enables trace splitting/labeling for agent actions.
+    Business purpose: Supports agentized business logic, allowing per-agent metrics, reporting, and debugging.
+    """
+    if callable(name):
+        return _decorate("agent", name.__name__, name.__name__, name)
+    return _factory("agent", name=name, agent_name=name)

traceiq_capture-0.1.0.dist-info/METADATA

@@ -0,0 +1,129 @@
+Metadata-Version: 2.5
+Name: traceiq-capture
+Version: 0.1.0
+Summary: TraceIQ Capture — OpenTelemetry instrumentation with a locked attribute contract
+Author: TraceIQ
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,cost,llm,observability,opentelemetry,otlp
+Requires-Python: >=3.10
+Requires-Dist: opentelemetry-api>=1.27.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27.0
+Requires-Dist: opentelemetry-sdk>=1.27.0
+Provides-Extra: all
+Requires-Dist: openai; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-anthropic; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-langchain; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-llamaindex; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-openai; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: opentelemetry-instrumentation-anthropic; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: opentelemetry-instrumentation-langchain; extra == 'langchain'
+Provides-Extra: langgraph
+Requires-Dist: langgraph; extra == 'langgraph'
+Requires-Dist: opentelemetry-instrumentation-langchain; extra == 'langgraph'
+Provides-Extra: llamaindex
+Requires-Dist: opentelemetry-instrumentation-llamaindex; extra == 'llamaindex'
+Provides-Extra: openai
+Requires-Dist: openai; extra == 'openai'
+Requires-Dist: opentelemetry-instrumentation-openai; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# TraceIQ Capture (`traceiq-capture`)
+
+OpenTelemetry-native Python SDK for AI agent / LLM cost observability. Locked attribute contract (no field sprawl). Framework coverage via optional OTel instrumentations — not Traceloop.
+
+Install name: **`traceiq-capture`**. Import: **`import traceiq`**.
+
+## Install
+
+```bash
+cd sdk
+pip install -e .                 # installs package traceiq-capture
+pip install -e ".[openai]"       # OpenAI auto-instrumentation
+pip install -e ".[langchain]"    # LangChain / LangGraph
+pip install -e ".[anthropic]"
+pip install -e ".[llamaindex]"
+pip install -e ".[all]"
+pip install -e ".[dev]"          # pytest
+```
+
+## Quickstart
+
+Set env (optional for local file export):
+
+```bash
+export TRACEIQ_API_KEY=...
+export TRACEIQ_ENDPOINT=https://api.example.com   # omit → ./traces/
+export TRACEIQ_APP_NAME=support-agent-api         # optional
+export TRACEIQ_ENVIRONMENT=production             # optional
+```
+
+```python
+import traceiq
+
+traceiq.init()
+
+# Existing OpenAI / LangChain / Anthropic / LlamaIndex code unchanged.
+# Installed extras are auto-instrumented on init — no decorators required.
+```
+
+No `TRACEIQ_ENDPOINT` → spans written under `./traces/` for local debug. Batch export every **5s**; process exit flushes automatically (`flush()` is only needed in short scripts/tests).
+
+## Optional: agent trees and attribution
+
+Use decorators when you want a run root and step types. Use `set_context` when you want product / project / agent rollups.
+
+```python
+from traceiq import workflow, set_context
+
+@workflow(name="triage_ticket")
+def handle(ticket_id: str, user_msg: str):
+    set_context(agent_name="triage", product_name="Pro")
+    return run_agent(user_msg)
+```
+
+Also available: `@task`, `@tool`, `@agent`, `clear_context`.
+
+## Frameworks
+
+Install the matching extra; call `init()` once. LLM library calls emit child spans automatically.
+
+| Stack | Extra |
+|-------|-------|
+| OpenAI | `[openai]` |
+| Anthropic | `[anthropic]` |
+| LangChain / LangGraph | `[langchain]` / `[langgraph]` |
+| LlamaIndex | `[llamaindex]` |
+| CrewAI | `[openai]` and/or `[langchain]` |
+
+Decorators are optional — add `@workflow` on your entrypoint only if you want TraceIQ run identity around the call tree.
+
+## Public API
+
+`init`, `flush`, `set_context`, `clear_context`, `@workflow`, `@task`, `@tool`, `@agent`
+
+## Export
+
+- Default: OTLP/HTTP JSON → `{endpoint}/v1/otlp/v1/traces` (Bearer)
+- Fallback: `export_mode="spans"` → `/v1/spans/batch`
+- Batch every **5s** (`disable_batch=True` for sync scripts)
+
+## Attributes (locked)
+
+See build spec §3. Only allowlisted `traceiq.*` plus `gen_ai.system` / `gen_ai.request.model` / usage tokens. No prompt/completion content capture. No client-side pricing.
+
+## Develop
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

traceiq_capture-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+traceiq/__init__.py,sha256=6O66QL9W5113kyAS1LPYYBkopbt7-zFm2Jl9ztqZbWk,399
+traceiq/_compat.py,sha256=IrKJnwkSEpE8ATvk1N3beIGDyIxZ8x3LuinJP1qcV0g,3792
+traceiq/_context.py,sha256=gG-TQxW5G990Tq057-VQCgVeukmhudavUV-kn5frFiE,3147
+traceiq/_enrich.py,sha256=ga8byKFLnkkdVBxopB69D1WpehzHZ9m-PvfIekvVZL8,5287
+traceiq/_exporter.py,sha256=MzC3xFx203UeNDMM3BJBUqNyLrZJmDCXshrE-PG_Hy8,7418
+traceiq/_ids.py,sha256=9rRszlBimKpr8eYNpxyPPYcGe6IejLade4tMKpfG7yk,283
+traceiq/_init.py,sha256=2MKuqgnzAhvwOP2cBK3AF5e_kJYtUFx3XotPV18wRGE,4724
+traceiq/_modality.py,sha256=biBeDIqY8iWevwVf9Nc1RhWA_LYt0ee_LUGYo_SFlYQ,897
+traceiq/_step.py,sha256=HUYgLvRr2zpjM9qegazuj2wc6qxDMAtWiVi5FXjh-vg,713
+traceiq/decorators.py,sha256=3YDzYZtw1l9nTu5xZxMaUV_rzGQOGcbj4GdbI7WXc38,6110
+traceiq/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+traceiq_capture-0.1.0.dist-info/METADATA,sha256=Ooq1gCaG_mMXX2x7BWpbSBkqg_H8UMkm8f3CUlbB0XE,4335
+traceiq_capture-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+traceiq_capture-0.1.0.dist-info/licenses/LICENSE,sha256=AcIBGJD8Of_dlodvArZCiQ1JrIxG-lt923vdALyL7sc,1064
+traceiq_capture-0.1.0.dist-info/RECORD,,

traceiq_capture-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

traceiq_capture-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TraceIQ
+
+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.