asi-telemetry 0.2.0__tar.gz

asi_telemetry-0.2.0/LICENSE

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

asi_telemetry-0.2.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: asi-telemetry
+Version: 0.2.0
+Summary: Observability and Distributed Tracing SDK for AI Agents and LLMs
+Author: Devrithm Labs
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Devrithm-Labs/ASI-Telemetry
+Project-URL: Repository, https://github.com/Devrithm-Labs/ASI-Telemetry
+Project-URL: Bug Tracker, https://github.com/Devrithm-Labs/ASI-Telemetry/issues
+Keywords: telemetry,tracing,observability,ai-agents,llm,metrics,gemini,openai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ASI Telemetry SDK
+
+The official lightweight observability, runtime metrics, and distributed tracing SDK for AI agents, LLMs (Google Gemini, OpenAI, ASI-1, DeepSeek), and tool execution pipelines.
+
+## Installation
+
+```bash
+pip install asi-telemetry
+```
+
+Zero external dependencies required (built using standard Python libraries).
+
+
+## Architecture & Features
+
+- **Agent & Tool Performance Tracking (`MetricsTracker`)**:
+  - Measures execution latency, request counts, and success/error status.
+  - Asynchronously dispatches metrics to the ASI Telemetry backend and ClickHouse.
+  - Zero performance overhead; non-blocking background workers.
+  - Clean real-time terminal telemetry reporting.
+
+- **Distributed LLM Tracing (`@traceable`)**:
+  - Trace multi-hop agent swarms and workflow chains with distributed context propagation (`trace_id`, `span_id`, `parent_id`).
+  - Supports both synchronous and asynchronous coroutine functions.
+  - Native auto-instrumentation for Google Gemini (`instrument_gemini`) and OpenAI/ASI (`instrument_openai` / `instrument_client`).
+  - Real-time token usage calculation and cost estimation per model.
+
+---
+
+## Quick Start
+
+### 1. Monitoring Agent Tools & Functions
+
+```python
+from asi_telemetry import MetricsTracker
+
+tracker = MetricsTracker(agent_name="assistant")
+
+@tracker.track(tool_name="weather_tool")
+async def get_weather(city: str):
+    return f"Weather in {city}: 72°F Sunny"
+```
+
+*(Note: `AgentMonitor` is retained as a backward-compatible alias for `MetricsTracker`)*
+
+### 2. Tracing LLMs and Multi-Agent Workflows
+
+```python
+from asi_telemetry import traceable, instrument_gemini
+from google import genai
+
+client = genai.Client(api_key="YOUR_API_KEY")
+instrument_gemini(client)
+
+@traceable(name="generate_summary", run_type="llm")
+def summarize(text: str):
+    response = client.models.generate_content(
+        model="gemini-2.5-flash",
+        contents=f"Summarize this: {text}"
+    )
+    return response.text
+```
+
+### 3. Distributed Context Propagation Across Swarms
+
+```python
+from asi_telemetry import traceable, create_trace_context
+
+@traceable(name="orchestrator", run_type="chain")
+async def orchestrate():
+    # Generate trace context to pass across network boundaries
+    context = create_trace_context()
+    # Pass context={"trace_id": ..., "parent_id": ...} to sub-agents
+```
+
+### 4. Direct Cost Estimation
+
+```python
+from asi_telemetry import calculate_cost
+
+# Approximate cost in USD for a model call
+cost = calculate_cost(model="gemini-3.8-flash", input_tokens=1200, output_tokens=350)
+print(f"Cost: ${cost}")
+```

asi_telemetry-0.2.0/README.md

@@ -0,0 +1,84 @@
+# ASI Telemetry SDK
+
+The official lightweight observability, runtime metrics, and distributed tracing SDK for AI agents, LLMs (Google Gemini, OpenAI, ASI-1, DeepSeek), and tool execution pipelines.
+
+## Installation
+
+```bash
+pip install asi-telemetry
+```
+
+Zero external dependencies required (built using standard Python libraries).
+
+
+## Architecture & Features
+
+- **Agent & Tool Performance Tracking (`MetricsTracker`)**:
+  - Measures execution latency, request counts, and success/error status.
+  - Asynchronously dispatches metrics to the ASI Telemetry backend and ClickHouse.
+  - Zero performance overhead; non-blocking background workers.
+  - Clean real-time terminal telemetry reporting.
+
+- **Distributed LLM Tracing (`@traceable`)**:
+  - Trace multi-hop agent swarms and workflow chains with distributed context propagation (`trace_id`, `span_id`, `parent_id`).
+  - Supports both synchronous and asynchronous coroutine functions.
+  - Native auto-instrumentation for Google Gemini (`instrument_gemini`) and OpenAI/ASI (`instrument_openai` / `instrument_client`).
+  - Real-time token usage calculation and cost estimation per model.
+
+---
+
+## Quick Start
+
+### 1. Monitoring Agent Tools & Functions
+
+```python
+from asi_telemetry import MetricsTracker
+
+tracker = MetricsTracker(agent_name="assistant")
+
+@tracker.track(tool_name="weather_tool")
+async def get_weather(city: str):
+    return f"Weather in {city}: 72°F Sunny"
+```
+
+*(Note: `AgentMonitor` is retained as a backward-compatible alias for `MetricsTracker`)*
+
+### 2. Tracing LLMs and Multi-Agent Workflows
+
+```python
+from asi_telemetry import traceable, instrument_gemini
+from google import genai
+
+client = genai.Client(api_key="YOUR_API_KEY")
+instrument_gemini(client)
+
+@traceable(name="generate_summary", run_type="llm")
+def summarize(text: str):
+    response = client.models.generate_content(
+        model="gemini-2.5-flash",
+        contents=f"Summarize this: {text}"
+    )
+    return response.text
+```
+
+### 3. Distributed Context Propagation Across Swarms
+
+```python
+from asi_telemetry import traceable, create_trace_context
+
+@traceable(name="orchestrator", run_type="chain")
+async def orchestrate():
+    # Generate trace context to pass across network boundaries
+    context = create_trace_context()
+    # Pass context={"trace_id": ..., "parent_id": ...} to sub-agents
+```
+
+### 4. Direct Cost Estimation
+
+```python
+from asi_telemetry import calculate_cost
+
+# Approximate cost in USD for a model call
+cost = calculate_cost(model="gemini-3.8-flash", input_tokens=1200, output_tokens=350)
+print(f"Cost: ${cost}")
+```

asi_telemetry-0.2.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "asi-telemetry"
+version = "0.2.0"
+description = "Observability and Distributed Tracing SDK for AI Agents and LLMs"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "Devrithm Labs" }
+]
+keywords = [
+    "telemetry",
+    "tracing",
+    "observability",
+    "ai-agents",
+    "llm",
+    "metrics",
+    "gemini",
+    "openai",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Monitoring",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/Devrithm-Labs/ASI-Telemetry"
+Repository = "https://github.com/Devrithm-Labs/ASI-Telemetry"
+"Bug Tracker" = "https://github.com/Devrithm-Labs/ASI-Telemetry/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

asi_telemetry-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

asi_telemetry-0.2.0/setup.py

@@ -0,0 +1,4 @@
+from setuptools import setup
+
+if __name__ == "__main__":
+    setup()

asi_telemetry-0.2.0/src/asi_telemetry/__init__.py

@@ -0,0 +1,168 @@
+import os
+from typing import Any, Callable, Dict, Optional
+
+from .metrics import MetricsTracker
+from .tracer import (
+    traceable,
+    create_trace_context,
+    set_agent_info,
+    set_api_key,
+)
+from .instrumentation import (
+    instrument_gemini,
+    instrument_openai,
+    instrument_client,
+    instrument_llm_provider,
+)
+from .models import calculate_cost
+
+__version__ = "0.2.0"
+
+
+class ASI_Telemetry:
+    """
+    Unified ASI Telemetry client.
+
+    Usage:
+        from asi_telemetry import ASI_Telemetry
+
+        observe = ASI_Telemetry(
+            api_key="asi_live_...",
+            agent_name="assistant",
+            agent_address=agent.address,
+        )
+
+        @observe.track("handle_message")
+        @observe.traceable(name="handle_message", run_type="tool")
+        async def handle_message(ctx, sender, msg):
+            ...
+    """
+
+    DEFAULT_BACKEND_URL = "http://127.0.0.1:8080"
+
+    def __init__(
+        self,
+        api_key: str = "",
+        agent_name: str = "assistant",
+        agent_address: str = "",
+        backend_url: Optional[str] = None,
+    ):
+        self.api_key = (
+            api_key
+            or os.getenv("ASI_API_KEY")
+            or os.getenv("ASI_TELEMETRY_API_KEY")
+            or os.getenv("TELEMETRY_API_KEY")
+            or ""
+        )
+        self.backend_url = (
+            backend_url
+            or os.getenv("TELEMETRY_BACKEND_URL")
+            or self.DEFAULT_BACKEND_URL
+        )
+        self.agent_name = agent_name
+        self.agent_address = agent_address
+
+        # Initialize global environment & agent identities
+        if self.api_key:
+            set_api_key(self.api_key)
+            os.environ["ASI_API_KEY"] = self.api_key
+        if self.backend_url:
+            os.environ["TELEMETRY_BACKEND_URL"] = self.backend_url
+            os.environ["TELEMETRY_METRICS_URL"] = (
+                self.backend_url
+                if "/api/metrics" in self.backend_url or "/api/telemetry" in self.backend_url
+                else f"{self.backend_url.rstrip('/')}/api/metrics"
+            )
+            os.environ["TELEMETRY_TRACES_URL"] = (
+                self.backend_url
+                if "/api/llm/traces" in self.backend_url
+                else f"{self.backend_url.rstrip('/')}/api/llm/traces"
+            )
+
+        set_agent_info(agent_name=self.agent_name, agent_address=self.agent_address)
+
+        # Internal metrics tracker
+        self.metrics = MetricsTracker(
+            agent_name=self.agent_name,
+            agent_address=self.agent_address,
+            api_key=self.api_key,
+            backend_url=os.environ.get("TELEMETRY_METRICS_URL", self.backend_url),
+        )
+
+    def track(self, tool_name: Optional[Any] = None) -> Callable:
+        """Track function execution time, status, and agent performance metrics."""
+        return self.metrics.track(tool_name)
+
+    # Alias for track
+    tool_monitoring = track
+
+    def traceable(
+        self,
+        name: Optional[Any] = None,
+        run_type: str = "chain",
+        metadata: Optional[Dict[str, Any]] = None,
+        agent_address: Optional[str] = None,
+    ) -> Callable:
+        """Trace function execution, inputs, outputs, errors, latency, and tokens."""
+        return traceable(
+            name=name,
+            run_type=run_type,
+            metadata=metadata,
+            agent_address=agent_address or self.agent_address,
+        )
+
+    def create_trace_context(self) -> Dict[str, Optional[str]]:
+        """Create a distributed tracing context dictionary for inter-agent messages."""
+        return create_trace_context()
+
+    def instrument_gemini(self, client: Any) -> Any:
+        """Auto-instrument Google GenAI Gemini client."""
+        return instrument_gemini(client)
+
+    def instrument_openai(self, client: Any) -> Any:
+        """Auto-instrument OpenAI client."""
+        return instrument_openai(client)
+
+    def instrument_client(self, client: Any, provider: str = "custom") -> Any:
+        """Auto-instrument any LLM client."""
+        return instrument_client(client, provider)
+
+
+# Aliases for backward compatibility
+ASITelemetry = ASI_Telemetry
+
+
+def init(
+    api_key: str = "",
+    agent_name: str = "assistant",
+    agent_address: str = "",
+    backend_url: Optional[str] = None,
+) -> ASI_Telemetry:
+    """Initialize the ASI Telemetry SDK with global client settings."""
+    return ASI_Telemetry(
+        api_key=api_key,
+        agent_name=agent_name,
+        agent_address=agent_address,
+        backend_url=backend_url,
+    )
+
+
+
+__all__ = [
+    "__version__",
+    # Primary Client
+    "ASI_Telemetry",
+    "ASITelemetry",
+    # Core Entry Points
+    "init",
+    "traceable",
+    "create_trace_context",
+    "MetricsTracker",
+    # Instrumentations
+    "instrument_gemini",
+    "instrument_openai",
+    "instrument_client",
+    "instrument_llm_provider",
+    # Cost Utility
+    "calculate_cost",
+]

asi_telemetry-0.2.0/src/asi_telemetry/instrumentation.py

@@ -0,0 +1,114 @@
+"""
+Client auto-instrumentation for Google Gemini, OpenAI, and compatible LLM providers.
+"""
+
+import functools
+from typing import Any, Optional
+from .models import calculate_cost
+
+
+def save_token_usage(response: Any, span: dict, model: Optional[str] = None) -> None:
+    """
+    Extracts token usage metadata from Gemini or OpenAI/ASI responses
+    and writes token counts and estimated costs into the span.
+    """
+    if not isinstance(span, dict):
+        return
+
+    # 1. Google Gemini style: response.usage_metadata
+    usage = getattr(response, "usage_metadata", None)
+    if usage:
+        input_tokens = getattr(usage, "prompt_token_count", 0) or 0
+        output_tokens = getattr(usage, "candidates_token_count", 0) or 0
+        total_tokens = getattr(usage, "total_token_count", 0) or (input_tokens + output_tokens)
+        resolved_model = model or span.get("metadata", {}).get("model", "gemini-3.8-flash")
+    else:
+        # 2. OpenAI / ASI style: response.usage
+        usage = getattr(response, "usage", None)
+        if not usage:
+            return  # Not an LLM response with token usage
+        input_tokens = getattr(usage, "prompt_tokens", 0) or 0
+        output_tokens = getattr(usage, "completion_tokens", 0) or 0
+        total_tokens = getattr(usage, "total_tokens", 0) or (input_tokens + output_tokens)
+        resolved_model = model or getattr(response, "model", span.get("metadata", {}).get("model", "asi1-mini"))
+
+    span.setdefault("metadata", {})["model"] = resolved_model
+    span["tokens"] = {
+        "input": input_tokens,
+        "output": output_tokens,
+        "total": total_tokens,
+    }
+    span["cost"] = calculate_cost(resolved_model, input_tokens, output_tokens)
+
+
+def instrument_gemini(client: Any) -> None:
+    """
+    Auto-instruments Google Gemini genai client (client.models.generate_content)
+    to automatically extract tokens and calculate costs for any enclosing span.
+    """
+    from .tracer import current_span
+
+    if not hasattr(client, "models") or not hasattr(client.models, "generate_content"):
+        return
+
+    original_generate = client.models.generate_content
+
+    @functools.wraps(original_generate)
+    def wrapped_generate(*args, **kwargs):
+        span = current_span.get()
+        model_name = kwargs.get("model", args[0] if args else "gemini-3.8-flash")
+        if span is not None:
+            span.setdefault("metadata", {})["model"] = model_name
+
+        response = original_generate(*args, **kwargs)
+
+        if span is not None:
+            save_token_usage(response, span, model=model_name)
+        return response
+
+    client.models.generate_content = wrapped_generate
+
+
+def instrument_openai(client: Any) -> None:
+    """
+    Auto-instruments OpenAI / ASI client (client.chat.completions.create)
+    to capture token usage and calculate costs.
+    """
+    from .tracer import current_span
+
+    if not hasattr(client, "chat") or not hasattr(client.chat, "completions"):
+        return
+
+    original_create = client.chat.completions.create
+
+    @functools.wraps(original_create)
+    def wrapped_create(*args, **kwargs):
+        span = current_span.get()
+        model_name = kwargs.get("model", "asi1-mini")
+        if span is not None:
+            span.setdefault("metadata", {})["model"] = model_name
+
+        response = original_create(*args, **kwargs)
+
+        if span is not None:
+            save_token_usage(response, span, model=model_name)
+        return response
+
+    client.chat.completions.create = wrapped_create
+
+
+def instrument_client(client: Any) -> None:
+    """
+    Automatically detects LLM client type (Google Gemini, OpenAI, or ASI)
+    and applies tracing instrumentation.
+    """
+    if hasattr(client, "models") and hasattr(client.models, "generate_content"):
+        instrument_gemini(client)
+    elif hasattr(client, "chat") and hasattr(client.chat, "completions"):
+        instrument_openai(client)
+
+
+# Backward-compatible alias
+instrument_llm_provider = instrument_client
+
+

asi_telemetry-0.2.0/src/asi_telemetry/metrics.py

@@ -0,0 +1,164 @@
+"""
+Metrics tracking and runtime performance monitoring for AI agents and tools.
+"""
+
+import asyncio
+import inspect
+import json
+import os
+import threading
+import time
+import urllib.request
+from datetime import datetime, timezone
+from functools import wraps
+from typing import Any, Callable, Optional
+
+
+class MetricsTracker:
+
+    def __init__(
+        self,
+        agent_name: str = "assistant",
+        agent_address: str = "",
+        api_key: str = "",
+        backend_url: str = "",
+    ):
+        self.agent_name = agent_name
+        self.agent_address = agent_address
+        self.api_key = api_key
+        self.backend_url = backend_url
+
+        # Sync process-level agent identity and API key with tracer
+        try:
+            from .tracer import set_agent_info, set_api_key
+            set_agent_info(
+                agent_name=agent_name,
+                agent_address=agent_address,
+            )
+            if self.api_key:
+                set_api_key(self.api_key)
+        except Exception:
+            pass
+
+    def _get_metrics_url(self) -> str:
+        url = (
+            self.backend_url
+            or os.getenv("TELEMETRY_METRICS_URL")
+            or os.getenv("TELEMETRY_BACKEND_URL")
+            or "http://127.0.0.1:8080"
+        )
+        if "/api/llm/traces" in url:
+            url = url.replace("/api/llm/traces", "/api/metrics")
+        elif not url.endswith("/api/metrics") and not url.endswith("/api/telemetry"):
+            url = f"{url.rstrip('/')}/api/metrics"
+        return url
+
+    def _dispatch_payload(self, payload: dict) -> None:
+        def _worker():
+            url = self._get_metrics_url()
+            try:
+                headers = {"Content-Type": "application/json"}
+                api_key = (
+                    self.api_key
+                    or os.getenv("ASI_API_KEY")
+                    or os.getenv("ASI_TELEMETRY_API_KEY")
+                    or os.getenv("TELEMETRY_API_KEY")
+                )
+                if not api_key:
+                    try:
+                        from .tracer import get_api_key
+                        api_key = get_api_key()
+                    except Exception:
+                        pass
+
+                if api_key:
+                    headers["x-api-key"] = api_key
+                    headers["Authorization"] = f"Bearer {api_key}"
+                    payload["api_key"] = api_key
+
+                data = json.dumps(payload, default=str).encode("utf-8")
+                req = urllib.request.Request(
+                    url,
+                    data=data,
+                    headers=headers,
+                    method="POST",
+                )
+                with urllib.request.urlopen(req, timeout=3.0):
+                    pass
+            except Exception as e:
+                # Log when debugging is requested
+                if os.getenv("ASI_DEBUG") or os.getenv("TELEMETRY_DEBUG"):
+                    print(f"[ASI-Telemetry Metrics Error] Failed to send metrics to {url}: {e}")
+
+        threading.Thread(target=_worker, daemon=True).start()
+
+    def track(self, tool_name: Optional[Any] = None) -> Callable:
+        """
+        Decorator to track function execution time, status, and agent metrics.
+        Can be used as:
+            @monitor.track
+            @monitor.track()
+            @monitor.track("custom_name")
+        Supports both sync and async functions.
+        """
+        def decorator(func: Callable) -> Callable:
+            target_name = (tool_name if isinstance(tool_name, str) else None) or func.__name__
+
+            if inspect.iscoroutinefunction(func):
+                @wraps(func)
+                async def async_wrapper(*args, **kwargs):
+                    start_time = time.perf_counter()
+                    status = "success"
+                    try:
+                        return await func(*args, **kwargs)
+                    except asyncio.CancelledError:
+                        status = "cancelled"
+                        raise
+                    except Exception:
+                        status = "error"
+                        raise
+                    finally:
+                        duration_ms = (time.perf_counter() - start_time) * 1000
+                        payload = {
+                            "agent_name": self.agent_name,
+                            "agent_address": self.agent_address,
+                            "func_name": target_name,
+                            "status": status,
+                            "response_time_ms": round(duration_ms, 2),
+                            "timestamp": datetime.now(timezone.utc).isoformat(),
+                        }
+                        self._dispatch_payload(payload)
+
+                return async_wrapper
+            else:
+                @wraps(func)
+                def sync_wrapper(*args, **kwargs):
+                    start_time = time.perf_counter()
+                    status = "success"
+                    try:
+                        return func(*args, **kwargs)
+                    except Exception:
+                        status = "error"
+                        raise
+                    finally:
+                        duration_ms = (time.perf_counter() - start_time) * 1000
+                        payload = {
+                            "agent_name": self.agent_name,
+                            "agent_address": self.agent_address,
+                            "func_name": target_name,
+                            "status": status,
+                            "response_time_ms": round(duration_ms, 2),
+                            "timestamp": datetime.now(timezone.utc).isoformat(),
+                        }
+                        self._dispatch_payload(payload)
+
+                return sync_wrapper
+
+        if callable(tool_name):
+            func = tool_name
+            tool_name = None
+            return decorator(func)
+
+        return decorator
+
+

asi_telemetry-0.2.0/src/asi_telemetry/models.py

@@ -0,0 +1,30 @@
+"""
+Data models, pricing tables, and schema constants for ASI Telemetry.
+"""
+
+from typing import Dict, Any, Optional
+
+# Price in USD per 1 million tokens
+PRICE_PER_MILLION: Dict[str, Dict[str, float]] = {
+    "asi1-mini": {"input": 0.10, "output": 0.40},
+    "asi-mini": {"input": 0.10, "output": 0.40},
+    "asi1": {"input": 0.50, "output": 1.50},
+    "gemini-3.8-flash": {"input": 0.075, "output": 0.30},
+    "gemini-2.5-flash": {"input": 0.075, "output": 0.30},
+    "gemini-3.5-flash": {"input": 0.075, "output": 0.30},
+    "gemini-3.5-flash-lite": {"input": 0.0375, "output": 0.15}
+}
+
+DEFAULT_PRICE: Dict[str, float] = {"input": 0.10, "output": 0.40}
+
+
+def calculate_cost(model: str, input_tokens: int, output_tokens: int) -> float:
+    """
+    Calculates estimated USD cost for a given model and token counts.
+    """
+    normalized_model = (model or "").replace("models/", "").lower()
+    price = PRICE_PER_MILLION.get(normalized_model, DEFAULT_PRICE)
+
+    input_cost = (input_tokens * price["input"]) / 1_000_000
+    output_cost = (output_tokens * price["output"]) / 1_000_000
+    return round(input_cost + output_cost, 6)

asi_telemetry-0.2.0/src/asi_telemetry/tracer.py

@@ -0,0 +1,250 @@
+import functools
+import inspect
+import json
+import os
+import threading
+import time
+import urllib.request
+import uuid
+from contextvars import ContextVar
+from typing import Any, Callable, Dict, Optional, Tuple
+
+from .instrumentation import save_token_usage
+
+sdk_config: Dict[str, Any] = {
+    "api_key": os.getenv("ASI_API_KEY") or os.getenv("ASI_TELEMETRY_API_KEY") or os.getenv("TELEMETRY_API_KEY"),
+}
+
+current_agent: Dict[str, Optional[str]] = {
+    "agent_name": os.getenv("AGENT_NAME", "assistant"),
+    "agent_address": os.getenv("AGENT_ADDRESS", None),
+}
+CURRENT_AGENT_INFO = current_agent
+
+active_span: ContextVar[Optional[Dict[str, Any]]] = ContextVar("active_span", default=None)
+current_span = active_span
+
+
+def set_api_key(api_key: str) -> None:
+    sdk_config["api_key"] = api_key
+    os.environ["ASI_API_KEY"] = api_key
+
+
+def get_api_key() -> Optional[str]:
+    return sdk_config.get("api_key") or os.getenv("ASI_API_KEY") or os.getenv("ASI_TELEMETRY_API_KEY") or os.getenv("TELEMETRY_API_KEY")
+
+
+def set_agent_info(agent_name: Optional[str] = None, agent_address: Optional[str] = None) -> None:
+    if agent_name:
+        current_agent["agent_name"] = agent_name
+    if agent_address:
+        current_agent["agent_address"] = agent_address
+
+
+def get_agent_info() -> Dict[str, Optional[str]]:
+    return dict(current_agent)
+
+
+def get_current_trace_id() -> Optional[str]:
+    span = active_span.get()
+    return span["trace_id"] if span else None
+
+
+def get_current_span_id() -> Optional[str]:
+    span = active_span.get()
+    return span["span_id"] if span else None
+
+
+def create_trace_context() -> Dict[str, Optional[str]]:
+    span = active_span.get()
+    if span:
+        return {"trace_id": span["trace_id"], "parent_id": span["span_id"]}
+    return {"trace_id": str(uuid.uuid4()), "parent_id": None}
+
+
+def _extract_trace_context(args: tuple, kwargs: dict, metadata: Optional[Dict[str, Any]]) -> Tuple[Optional[str], Optional[str]]:
+    candidates = [metadata] + list(args) + list(kwargs.values())
+    for item in candidates:
+        ctx = getattr(item, "trace_context", None) or (item.get("trace_context") if isinstance(item, dict) else item)
+        if isinstance(ctx, dict) and ctx.get("trace_id"):
+            return ctx["trace_id"], ctx.get("parent_id") or ctx.get("span_id")
+    return None, None
+
+
+def _dispatch_span(payload: Dict[str, Any]) -> None:
+    def _worker():
+        try:
+            url = os.getenv("TELEMETRY_TRACES_URL") or os.getenv("TELEMETRY_BACKEND_URL", "http://127.0.0.1:8080/api/llm/traces")
+            if "/api/metrics" in url:
+                url = url.replace("/api/metrics", "/api/llm/traces")
+
+            api_key = get_api_key()
+            headers = {"Content-Type": "application/json"}
+            if api_key:
+                headers["x-api-key"] = api_key
+                headers["Authorization"] = f"Bearer {api_key}"
+                payload["api_key"] = api_key
+
+            req = urllib.request.Request(
+                url,
+                data=json.dumps(payload, default=str).encode("utf-8"),
+                headers=headers,
+                method="POST",
+            )
+            with urllib.request.urlopen(req, timeout=2.0):
+                pass
+        except Exception:
+            pass
+
+    threading.Thread(target=_worker, daemon=True).start()
+
+
+def start_span(
+    function_name: str,
+    run_type: str,
+    metadata: Optional[Dict[str, Any]],
+    args: tuple,
+    kwargs: dict,
+    agent_address: Optional[str] = None,
+) -> Tuple[Dict[str, Any], Any]:
+    parent_span = active_span.get()
+    incoming_trace_id, incoming_parent_id = _extract_trace_context(args, kwargs, metadata)
+
+    if incoming_trace_id:
+        trace_id = incoming_trace_id
+        parent_id = incoming_parent_id or (parent_span["span_id"] if parent_span else None)
+    elif parent_span:
+        trace_id = parent_span["trace_id"]
+        parent_id = parent_span["span_id"]
+    else:
+        trace_id = str(uuid.uuid4())
+        parent_id = None
+
+    is_parent_root = (parent_span is None)
+    agent_name = current_agent.get("agent_name", "assistant")
+    meta = dict(metadata or {})
+    meta["is_agent_root"] = is_parent_root
+    meta["agent_name"] = agent_name
+
+    addr = agent_address or meta.get("agent_address") or (parent_span.get("agent_address") if parent_span else None) or current_agent.get("agent_address")
+    span_id = str(uuid.uuid4())
+    inputs = kwargs if kwargs else (args[0] if len(args) == 1 else args)
+
+    span = {
+        "id": span_id,
+        "span_id": span_id,
+        "trace_id": trace_id,
+        "parent_id": parent_id,
+        "name": function_name,
+        "run_type": run_type,
+        "start_time": time.time(),
+        "inputs": inputs,
+        "outputs": None,
+        "error": None,
+        "tokens": {"input": 0, "output": 0, "total": 0},
+        "cost": 0.0,
+        "agent_name": agent_name,
+        "is_agent_root": is_parent_root,
+        "agent_address": addr,
+        "metadata": meta,
+    }
+
+    reset_token = active_span.set(span)
+    return span, reset_token
+
+
+def end_span(
+    span: Dict[str, Any],
+    reset_token: Any,
+    result: Any = None,
+    error: Optional[Exception] = None,
+) -> None:
+    try:
+        span["end_time"] = time.time()
+        span["duration_ms"] = round((span["end_time"] - span["start_time"]) * 1000, 2)
+        if error is not None:
+            span["error"] = str(error)
+        else:
+            span["outputs"] = result
+            save_token_usage(result, span)
+    finally:
+        active_span.reset(reset_token)
+
+        in_val = span.get("inputs")
+        out_val = span.get("outputs")
+        meta = dict(span.get("metadata") or {})
+        addr = span.get("agent_address")
+        if addr:
+            meta["agent_address"] = addr
+        meta["agent_name"] = span.get("agent_name", "assistant")
+        meta["is_agent_root"] = span.get("is_agent_root", False)
+
+        payload = {
+            "id": span["span_id"],
+            "trace_id": span["trace_id"],
+            "span_id": span["span_id"],
+            "parent_id": span.get("parent_id"),
+            "name": span.get("name") or "agent_execution",
+            "run_type": span.get("run_type", "agent"),
+            "status": "error" if span.get("error") else "success",
+            "model": meta.get("model", "agent-tool"),
+            "input": json.dumps(in_val, default=str) if isinstance(in_val, (dict, list)) else str(in_val or ""),
+            "output": json.dumps(out_val, default=str) if isinstance(out_val, (dict, list)) else str(out_val or ""),
+            "error": str(span["error"]) if span.get("error") else None,
+            "latency_ms": span.get("duration_ms", 0.0),
+            "prompt_tokens": span.get("tokens", {}).get("input", 0),
+            "completion_tokens": span.get("tokens", {}).get("output", 0),
+            "total_tokens": span.get("tokens", {}).get("total", 0),
+            "cost_usd": span.get("cost", 0.0),
+            "agent_address": addr,
+            "agent_name": meta["agent_name"],
+            "is_agent_root": meta["is_agent_root"],
+            "metadata": meta,
+        }
+        _dispatch_span(payload)
+
+
+def traceable(
+    name: Optional[Any] = None,
+    run_type: str = "chain",
+    metadata: Optional[Dict[str, Any]] = None,
+    agent_address: Optional[str] = None,
+) -> Callable:
+    def decorator(func: Callable) -> Callable:
+        fn_name = (name if isinstance(name, str) else None) or func.__name__
+
+        if inspect.iscoroutinefunction(func):
+            @functools.wraps(func)
+            async def async_wrapper(*args, **kwargs):
+                span, token = start_span(fn_name, run_type, metadata, args, kwargs, agent_address)
+                result, error = None, None
+                try:
+                    result = await func(*args, **kwargs)
+                    return result
+                except Exception as e:
+                    error = e
+                    raise
+                finally:
+                    end_span(span, token, result=result, error=error)
+            return async_wrapper
+
+        @functools.wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            span, token = start_span(fn_name, run_type, metadata, args, kwargs, agent_address)
+            result, error = None, None
+            try:
+                result = func(*args, **kwargs)
+                return result
+            except Exception as e:
+                error = e
+                raise
+            finally:
+                end_span(span, token, result=result, error=error)
+        return sync_wrapper
+
+    if callable(name):
+        func = name
+        name = None
+        return decorator(func)
+
+    return decorator

asi_telemetry-0.2.0/src/asi_telemetry.egg-info/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: asi-telemetry
+Version: 0.2.0
+Summary: Observability and Distributed Tracing SDK for AI Agents and LLMs
+Author: Devrithm Labs
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Devrithm-Labs/ASI-Telemetry
+Project-URL: Repository, https://github.com/Devrithm-Labs/ASI-Telemetry
+Project-URL: Bug Tracker, https://github.com/Devrithm-Labs/ASI-Telemetry/issues
+Keywords: telemetry,tracing,observability,ai-agents,llm,metrics,gemini,openai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ASI Telemetry SDK
+
+The official lightweight observability, runtime metrics, and distributed tracing SDK for AI agents, LLMs (Google Gemini, OpenAI, ASI-1, DeepSeek), and tool execution pipelines.
+
+## Installation
+
+```bash
+pip install asi-telemetry
+```
+
+Zero external dependencies required (built using standard Python libraries).
+
+
+## Architecture & Features
+
+- **Agent & Tool Performance Tracking (`MetricsTracker`)**:
+  - Measures execution latency, request counts, and success/error status.
+  - Asynchronously dispatches metrics to the ASI Telemetry backend and ClickHouse.
+  - Zero performance overhead; non-blocking background workers.
+  - Clean real-time terminal telemetry reporting.
+
+- **Distributed LLM Tracing (`@traceable`)**:
+  - Trace multi-hop agent swarms and workflow chains with distributed context propagation (`trace_id`, `span_id`, `parent_id`).
+  - Supports both synchronous and asynchronous coroutine functions.
+  - Native auto-instrumentation for Google Gemini (`instrument_gemini`) and OpenAI/ASI (`instrument_openai` / `instrument_client`).
+  - Real-time token usage calculation and cost estimation per model.
+
+---
+
+## Quick Start
+
+### 1. Monitoring Agent Tools & Functions
+
+```python
+from asi_telemetry import MetricsTracker
+
+tracker = MetricsTracker(agent_name="assistant")
+
+@tracker.track(tool_name="weather_tool")
+async def get_weather(city: str):
+    return f"Weather in {city}: 72°F Sunny"
+```
+
+*(Note: `AgentMonitor` is retained as a backward-compatible alias for `MetricsTracker`)*
+
+### 2. Tracing LLMs and Multi-Agent Workflows
+
+```python
+from asi_telemetry import traceable, instrument_gemini
+from google import genai
+
+client = genai.Client(api_key="YOUR_API_KEY")
+instrument_gemini(client)
+
+@traceable(name="generate_summary", run_type="llm")
+def summarize(text: str):
+    response = client.models.generate_content(
+        model="gemini-2.5-flash",
+        contents=f"Summarize this: {text}"
+    )
+    return response.text
+```
+
+### 3. Distributed Context Propagation Across Swarms
+
+```python
+from asi_telemetry import traceable, create_trace_context
+
+@traceable(name="orchestrator", run_type="chain")
+async def orchestrate():
+    # Generate trace context to pass across network boundaries
+    context = create_trace_context()
+    # Pass context={"trace_id": ..., "parent_id": ...} to sub-agents
+```
+
+### 4. Direct Cost Estimation
+
+```python
+from asi_telemetry import calculate_cost
+
+# Approximate cost in USD for a model call
+cost = calculate_cost(model="gemini-3.8-flash", input_tokens=1200, output_tokens=350)
+print(f"Cost: ${cost}")
+```

asi_telemetry-0.2.0/src/asi_telemetry.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+setup.py
+src/asi_telemetry/__init__.py
+src/asi_telemetry/instrumentation.py
+src/asi_telemetry/metrics.py
+src/asi_telemetry/models.py
+src/asi_telemetry/tracer.py
+src/asi_telemetry.egg-info/PKG-INFO
+src/asi_telemetry.egg-info/SOURCES.txt
+src/asi_telemetry.egg-info/dependency_links.txt
+src/asi_telemetry.egg-info/top_level.txt

asi_telemetry-0.2.0/src/asi_telemetry.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

asi_telemetry-0.2.0/src/asi_telemetry.egg-info/top_level.txt

@@ -0,0 +1 @@
+asi_telemetry