traceiq-capture 0.1.0__tar.gz

traceiq_capture-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+sdk/.venv/
+sdk/.pytest_cache/
+sdk/traces/
+backend/.venv/
+backend/.env
+**/__pycache__/
+*.sqlite3
+node_modules/
+.env

traceiq_capture-0.1.0/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.

traceiq_capture-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,94 @@
+# 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/example.py

@@ -0,0 +1,45 @@
+"""Manual example — init-only happy path (no decorators required).
+
+Uses OpenAI if OPENAI_API_KEY is set; otherwise emits a fake LLM span.
+Unset TRACEIQ_ENDPOINT → spans land in ./traces/
+"""
+
+from __future__ import annotations
+
+import os
+
+import traceiq
+
+
+def main() -> None:
+    api_key = os.environ.get("OPENAI_API_KEY")
+    if api_key:
+        from openai import OpenAI
+
+        client = OpenAI(api_key=api_key)
+        resp = client.chat.completions.create(
+            model="gpt-4o-mini",
+            messages=[{"role": "user", "content": "Say hi in one word."}],
+        )
+        print("openai:", resp.choices[0].message.content)
+    else:
+        from opentelemetry import trace
+
+        tracer = trace.get_tracer("demo")
+        with tracer.start_as_current_span("fake_llm") as span:
+            span.set_attribute("gen_ai.request.model", "gpt-4o-mini")
+            span.set_attribute("gen_ai.usage.input_tokens", 5)
+            span.set_attribute("gen_ai.usage.output_tokens", 1)
+            span.set_attribute("gen_ai.system", "openai")
+        print("no OPENAI_API_KEY — emitted fake_llm span")
+
+
+if __name__ == "__main__":
+    # Zero-arg init: env TRACEIQ_* or local ./traces/ when endpoint unset.
+    # disable_batch so this short script writes spans before exit.
+    os.environ.setdefault("TRACEIQ_APP_NAME", "sdk-example")
+    os.environ.setdefault("TRACEIQ_ENVIRONMENT", "dev")
+    traceiq.init(disable_batch=True)
+    main()
+    # Optional upgrades: @workflow / set_context for run trees & attribution.
+    print("done — check ./traces/ if TRACEIQ_ENDPOINT is unset")

traceiq_capture-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "traceiq-capture"
+version = "0.1.0"
+description = "TraceIQ Capture — OpenTelemetry instrumentation with a locked attribute contract"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "TraceIQ" }]
+keywords = ["ai", "observability", "opentelemetry", "otlp", "llm", "cost"]
+dependencies = [
+    "opentelemetry-api>=1.27.0",
+    "opentelemetry-sdk>=1.27.0",
+    "opentelemetry-exporter-otlp-proto-http>=1.27.0",
+]
+
+[project.optional-dependencies]
+openai = ["opentelemetry-instrumentation-openai", "openai"]
+anthropic = ["opentelemetry-instrumentation-anthropic"]
+langchain = ["opentelemetry-instrumentation-langchain"]
+langgraph = ["opentelemetry-instrumentation-langchain", "langgraph"]
+llamaindex = ["opentelemetry-instrumentation-llamaindex"]
+all = [
+    "opentelemetry-instrumentation-openai",
+    "opentelemetry-instrumentation-anthropic",
+    "opentelemetry-instrumentation-langchain",
+    "opentelemetry-instrumentation-llamaindex",
+    "openai",
+]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/traceiq"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/README.md", "/LICENSE", "/example.py"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"

traceiq_capture-0.1.0/src/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_capture-0.1.0/src/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_capture-0.1.0/src/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