traceAI-livekit 0.1.0__tar.gz

traceai_livekit-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.3
+Name: traceAI-livekit
+Version: 0.1.0
+Summary: OpenTelemetry instrumentation for LiveKit
+Author: Future AGI
+Author-email: no-reply@futureagi.com
+Requires-Python: >3.9,<3.14
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: fi-instrumentation-otel (>=0.1.14)
+Description-Content-Type: text/markdown
+
+# traceAI-livekit
+
+OpenTelemetry instrumentation for LiveKit agents integrated with Future AGI.
+
+This package provides automatic attribute mapping from LiveKit's native OpenTelemetry instrumentation to Future AGI's semantic conventions, ensuring rich and structured traces in your dashboard.
+
+## Installation
+
+```bash
+pip install traceai-livekit
+```
+
+## Quick Start
+
+To instrument your LiveKit agent, simply initialize `fi-instrumentation` and enable the attribute mapping **inside your agent's entrypoint**.
+
+```python
+from livekit.agents import AgentServer, JobContext
+from fi_instrumentation.otel import register, ProjectType
+from traceai_livekit import enable_http_attribute_mapping
+
+server = AgentServer()
+
+@server.rtc_session()
+async def entrypoint(ctx: JobContext):
+    # 1. Initialize TraceAI (inside entrypoint for multiprocessing safety)
+    register(
+        project_name="My LiveKit Agent",
+        project_type=ProjectType.OBSERVE,
+        set_global_tracer_provider=True,
+    )
+    
+    # 2. Enable LiveKit attribute mapping
+    # This automatically hooks into LiveKit's telemetry system
+    enable_http_attribute_mapping()
+    
+    # ... rest of your agent logic ...
+    await ctx.connect()
+
+if __name__ == "__main__":
+    server.run()
+```
+
+## Features
+
+*   **Automatic Attribute Mapping**: Converts LiveKit attributes (like `lk.user_input`, `gen_ai.usage.input_tokens`) to Future AGI standard attributes (`input.value`, `llm.tokenCount.prompt`).
+*   **Raw Data Preservation**: Keeps original LiveKit attributes and adds `raw.input` / `raw.output` for full debugging context.
+*   **Multiprocessing Support**: Designed to work with LiveKit's worker process model.
+*   **Event Parsing**: Extracts LLM outputs from `gen_ai.choice` events when available.
+
+## Examples
+
+Check the `examples/` directory for complete working agents:
+*   `simple_agent.py`: A basic voice assistant agent.
+*   `egress_agent.py`: An agent with call recording (Egress) enabled.
+

traceai_livekit-0.1.0/README.md

@@ -0,0 +1,55 @@
+# traceAI-livekit
+
+OpenTelemetry instrumentation for LiveKit agents integrated with Future AGI.
+
+This package provides automatic attribute mapping from LiveKit's native OpenTelemetry instrumentation to Future AGI's semantic conventions, ensuring rich and structured traces in your dashboard.
+
+## Installation
+
+```bash
+pip install traceai-livekit
+```
+
+## Quick Start
+
+To instrument your LiveKit agent, simply initialize `fi-instrumentation` and enable the attribute mapping **inside your agent's entrypoint**.
+
+```python
+from livekit.agents import AgentServer, JobContext
+from fi_instrumentation.otel import register, ProjectType
+from traceai_livekit import enable_http_attribute_mapping
+
+server = AgentServer()
+
+@server.rtc_session()
+async def entrypoint(ctx: JobContext):
+    # 1. Initialize TraceAI (inside entrypoint for multiprocessing safety)
+    register(
+        project_name="My LiveKit Agent",
+        project_type=ProjectType.OBSERVE,
+        set_global_tracer_provider=True,
+    )
+    
+    # 2. Enable LiveKit attribute mapping
+    # This automatically hooks into LiveKit's telemetry system
+    enable_http_attribute_mapping()
+    
+    # ... rest of your agent logic ...
+    await ctx.connect()
+
+if __name__ == "__main__":
+    server.run()
+```
+
+## Features
+
+*   **Automatic Attribute Mapping**: Converts LiveKit attributes (like `lk.user_input`, `gen_ai.usage.input_tokens`) to Future AGI standard attributes (`input.value`, `llm.tokenCount.prompt`).
+*   **Raw Data Preservation**: Keeps original LiveKit attributes and adds `raw.input` / `raw.output` for full debugging context.
+*   **Multiprocessing Support**: Designed to work with LiveKit's worker process model.
+*   **Event Parsing**: Extracts LLM outputs from `gen_ai.choice` events when available.
+
+## Examples
+
+Check the `examples/` directory for complete working agents:
+*   `simple_agent.py`: A basic voice assistant agent.
+*   `egress_agent.py`: An agent with call recording (Egress) enabled.

traceai_livekit-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[tool.poetry]
+name = "traceAI-livekit"
+version = "0.1.0"
+description = "OpenTelemetry instrumentation for LiveKit"
+authors = ["Future AGI <no-reply@futureagi.com>"]
+readme = "README.md"
+packages = [
+    { include = "traceai_livekit" }
+]
+
+[tool.poetry.dependencies]
+python = ">3.9,<3.14"
+fi-instrumentation-otel = ">=0.1.14"
+
+[tool.poetry.group.dev.dependencies]
+livekit-agents = "*"
+livekit-plugins-openai = "*"
+livekit-plugins-silero = "*"
+python-dotenv = "*"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

traceai_livekit-0.1.0/traceai_livekit/__init__.py

@@ -0,0 +1,33 @@
+"""
+TraceAI LiveKit integration.
+
+This package provides integration between LiveKit and Future AGI's tracing system,
+allowing LiveKit applications to send telemetry data with proper attribute mapping.
+"""
+
+from .exporters import (
+    BaseMappedSpanExporter,
+    MappedGRPCSpanExporter,
+    MappedHTTPSpanExporter,
+)
+from .integration import (
+    create_mapped_grpc_exporter,
+    create_mapped_http_exporter,
+    enable_fi_attribute_mapping,
+    enable_grpc_attribute_mapping,
+    enable_http_attribute_mapping,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "enable_fi_attribute_mapping",
+    "enable_http_attribute_mapping",
+    "enable_grpc_attribute_mapping",
+    "create_mapped_http_exporter",
+    "create_mapped_grpc_exporter",
+    # Exporters
+    "MappedHTTPSpanExporter",
+    "MappedGRPCSpanExporter",
+    "BaseMappedSpanExporter",
+]

traceai_livekit-0.1.0/traceai_livekit/exporters/__init__.py

@@ -0,0 +1,14 @@
+"""
+Exporters for LiveKit integration with Future AGI.
+"""
+
+from .base_exporter import BaseMappedSpanExporter
+from .grpc_exporter import MappedGRPCSpanExporter
+from .http_exporter import MappedHTTPSpanExporter
+
+__all__ = [
+    "MappedHTTPSpanExporter",
+    "MappedGRPCSpanExporter",
+    "BaseMappedSpanExporter",
+]
+

traceai_livekit-0.1.0/traceai_livekit/exporters/base_exporter.py

@@ -0,0 +1,325 @@
+"""
+Base exporter for LiveKit integration with Future AGI.
+
+This module provides the base class for mapped span exporters that convert
+LiveKit attributes to Future AGI conventions.
+"""
+
+import json
+from typing import Any, Dict
+
+from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
+
+# Import Future AGI span attribute keys
+from fi_instrumentation.fi_types import SpanAttributes
+
+
+def _ensure_json_string(value: Any) -> str:
+    """Ensure a value is a valid JSON string."""
+    try:
+        if isinstance(value, str):
+            # Validate if string is already JSON
+            json.loads(value)
+            return value
+        return json.dumps(value)
+    except Exception:
+        return json.dumps(str(value))
+
+
+def _detect_mime_type(value: Any) -> str:
+    """Detect the MIME type of a value."""
+    if isinstance(value, (dict, list)):
+        return "application/json"
+    if isinstance(value, str):
+        stripped = value.strip()
+        if (stripped.startswith("{") and stripped.endswith("}")) or (
+            stripped.startswith("[") and stripped.endswith("]")
+        ):
+            return "application/json"
+    return "text/plain"
+
+
+def _map_attributes_to_fi_conventions(attributes: Dict[str, Any]) -> Dict[str, Any]:
+    """Map LiveKit attributes to Future AGI conventions."""
+    if not attributes:
+        return {}
+
+    mapped: Dict[str, Any] = dict(attributes)  # start by preserving originals
+
+    # --- LiveKit Constant Keys (from livekit-agents/telemetry/trace_types.py) ---
+    
+    # Common Keys
+    LK_SPEECH_ID = "lk.speech_id"
+    LK_AGENT_LABEL = "lk.agent_label"
+    LK_START_TIME = "lk.start_time"
+    LK_END_TIME = "lk.end_time"
+    LK_RETRY_COUNT = "lk.retry_count"
+
+    LK_PARTICIPANT_ID = "lk.participant_id"
+    LK_PARTICIPANT_IDENTITY = "lk.participant_identity"
+    LK_PARTICIPANT_KIND = "lk.participant_kind"
+    
+    # Session Start
+    LK_JOB_ID = "lk.job_id"
+    LK_AGENT_NAME = "lk.agent_name"
+    LK_ROOM_NAME = "lk.room_name"
+    LK_SESSION_OPTIONS = "lk.session_options"
+
+    # Assistant Turn
+    LK_USER_INPUT = "lk.user_input"
+    LK_INSTRUCTIONS = "lk.instructions"
+    LK_SPEECH_INTERRUPTED = "lk.interrupted"
+
+    # LLM Node
+    LK_CHAT_CTX = "lk.chat_ctx"
+    LK_FUNCTION_TOOLS = "lk.function_tools"
+    LK_RESPONSE_TEXT = "lk.response.text"
+    LK_RESPONSE_FUNCTION_CALLS = "lk.response.function_calls"
+
+    # Function Tool
+    LK_FUNCTION_TOOL_NAME = "lk.function_tool.name"
+    LK_FUNCTION_TOOL_ARGS = "lk.function_tool.arguments"
+    LK_FUNCTION_TOOL_IS_ERROR = "lk.function_tool.is_error"
+    LK_FUNCTION_TOOL_OUTPUT = "lk.function_tool.output"
+
+    # TTS Node
+    LK_TTS_INPUT_TEXT = "lk.input_text"
+    LK_TTS_STREAMING = "lk.tts.streaming"
+    LK_TTS_LABEL = "lk.tts.label"
+
+    # EOU Detection & Metrics (used for Metadata)
+    LK_EOU_DELAY = "lk.eou.endpointing_delay"
+    LK_EOU_LANGUAGE = "lk.eou.language"
+    LK_USER_TRANSCRIPT = "lk.user_transcript"
+    LK_TRANSCRIPT_CONFIDENCE = "lk.transcript_confidence"
+    LK_TRANSCRIPTION_DELAY = "lk.transcription_delay"
+    LK_END_OF_TURN_DELAY = "lk.end_of_turn_delay"
+
+    # Standard OTel GenAI
+    ATTR_GEN_AI_OPERATION_NAME = "gen_ai.operation.name"
+    ATTR_GEN_AI_REQUEST_MODEL = "gen_ai.request.model"
+    ATTR_GEN_AI_USAGE_INPUT_TOKENS = "gen_ai.usage.input_tokens"
+    ATTR_GEN_AI_USAGE_OUTPUT_TOKENS = "gen_ai.usage.output_tokens"
+    
+    # --- MAPPING LOGIC ---
+
+    # 1. LLM & Model Info
+    if ATTR_GEN_AI_REQUEST_MODEL in attributes:
+        mapped[SpanAttributes.LLM_MODEL_NAME] = attributes.get(ATTR_GEN_AI_REQUEST_MODEL)
+
+    # 2. Inputs & Outputs
+    # LiveKit separates User Input (in Assistant Turn) vs LLM Response vs TTS Input
+    
+    input_val = None
+    output_val = None
+    raw_input_val = None
+    raw_output_val = None
+
+    # Case A: Assistant Turn (Top-level chain)
+    # Input: User speech/text (LK_USER_INPUT)
+    # Output: often not directly on this span, but might be aggregated or absent
+    if LK_USER_INPUT in attributes:
+        input_val = attributes.get(LK_USER_INPUT)
+        raw_input_val = attributes.get(LK_USER_INPUT)
+
+    # Case B: LLM Node
+    # Input: Chat Context (LK_CHAT_CTX) - usually a list of messages
+    # Output: Generated Text (LK_RESPONSE_TEXT) or Function Calls (LK_RESPONSE_FUNCTION_CALLS)
+    if LK_CHAT_CTX in attributes:
+
+        chat_ctx = attributes.get(LK_CHAT_CTX)
+        input_val = _ensure_json_string(chat_ctx)
+        raw_input_val = chat_ctx
+
+    if LK_RESPONSE_TEXT in attributes:
+        output_val = attributes.get(LK_RESPONSE_TEXT)
+        raw_output_val = output_val
+    
+    if LK_RESPONSE_FUNCTION_CALLS in attributes:
+        # If there are function calls, this is also an output
+        func_calls = attributes.get(LK_RESPONSE_FUNCTION_CALLS)
+        if output_val:
+             # If we already have text, append function calls
+             output_val = f"{output_val}\nFunction Calls: {_ensure_json_string(func_calls)}"
+             raw_output_val = {"text": raw_output_val, "function_calls": func_calls}
+        else:
+             output_val = _ensure_json_string(func_calls)
+             raw_output_val = func_calls
+
+    # Case C: TTS Node
+    # Input: Text to speak (LK_TTS_INPUT_TEXT)
+    # Output: Audio (not usually in attributes, maybe just success)
+    if LK_TTS_INPUT_TEXT in attributes:
+        input_val = attributes.get(LK_TTS_INPUT_TEXT)
+        raw_input_val = attributes.get(LK_TTS_INPUT_TEXT)
+        # TTS output is audio, we don't have the bytes here usually.
+
+    # Case D: Function Tool Execution
+    # Input: Arguments (LK_FUNCTION_TOOL_ARGS)
+    # Output: Tool Output (LK_FUNCTION_TOOL_OUTPUT)
+    if LK_FUNCTION_TOOL_ARGS in attributes:
+         input_val = attributes.get(LK_FUNCTION_TOOL_ARGS)
+         raw_input_val = attributes.get(LK_FUNCTION_TOOL_ARGS)
+    
+    if LK_FUNCTION_TOOL_OUTPUT in attributes:
+         output_val = attributes.get(LK_FUNCTION_TOOL_OUTPUT)
+         raw_output_val = attributes.get(LK_FUNCTION_TOOL_OUTPUT)
+
+    # Case E: Session Start
+    if LK_SESSION_OPTIONS in attributes and raw_input_val is None:
+         raw_input_val = attributes.get(LK_SESSION_OPTIONS)
+
+    # --- Set Input/Output Attributes ---
+    if raw_input_val is not None:
+        mapped[SpanAttributes.RAW_INPUT] = _ensure_json_string(raw_input_val)
+
+    if raw_output_val is not None:
+        mapped[SpanAttributes.RAW_OUTPUT] = _ensure_json_string(raw_output_val)
+
+    if input_val is not None and SpanAttributes.INPUT_VALUE not in mapped:
+        mime_type = _detect_mime_type(input_val)
+        mapped[SpanAttributes.INPUT_VALUE] = (
+            _ensure_json_string(input_val) if mime_type == "application/json" else input_val
+        )
+        mapped[SpanAttributes.INPUT_MIME_TYPE] = mime_type
+
+    if output_val is not None and SpanAttributes.OUTPUT_VALUE not in mapped:
+        mime_type = _detect_mime_type(output_val)
+        mapped[SpanAttributes.OUTPUT_VALUE] = (
+             _ensure_json_string(output_val) if mime_type == "application/json" else output_val
+        )
+        mapped[SpanAttributes.OUTPUT_MIME_TYPE] = mime_type
+
+
+    # 3. Token Usage
+    if ATTR_GEN_AI_USAGE_INPUT_TOKENS in attributes:
+        mapped[SpanAttributes.LLM_TOKEN_COUNT_PROMPT] = attributes.get(ATTR_GEN_AI_USAGE_INPUT_TOKENS)
+    if ATTR_GEN_AI_USAGE_OUTPUT_TOKENS in attributes:
+        mapped[SpanAttributes.LLM_TOKEN_COUNT_COMPLETION] = attributes.get(ATTR_GEN_AI_USAGE_OUTPUT_TOKENS)
+    
+    # Calculate total if not present
+    try:
+        prompt_tokens = mapped.get(SpanAttributes.LLM_TOKEN_COUNT_PROMPT)
+        completion_tokens = mapped.get(SpanAttributes.LLM_TOKEN_COUNT_COMPLETION)
+        if isinstance(prompt_tokens, (int, float)) and isinstance(completion_tokens, (int, float)):
+            mapped[SpanAttributes.LLM_TOKEN_COUNT_TOTAL] = int(prompt_tokens) + int(completion_tokens)
+    except Exception:
+        pass
+
+    # 4. Tools
+    if LK_FUNCTION_TOOL_NAME in attributes:
+        mapped[SpanAttributes.TOOL_NAME] = attributes.get(LK_FUNCTION_TOOL_NAME)
+        mapped["tool_call.function.name"] = attributes.get(LK_FUNCTION_TOOL_NAME) # Standardize
+
+    if LK_FUNCTION_TOOLS in attributes:
+        # List of available tools provided to LLM
+        mapped[SpanAttributes.LLM_TOOLS] = _ensure_json_string(attributes.get(LK_FUNCTION_TOOLS))
+
+    # 5. Session & User Info
+    if LK_ROOM_NAME in attributes:
+        mapped[SpanAttributes.SESSION_ID] = attributes.get(LK_ROOM_NAME)
+    
+    if LK_PARTICIPANT_IDENTITY in attributes:
+        mapped[SpanAttributes.USER_ID] = attributes.get(LK_PARTICIPANT_IDENTITY)
+
+    # 6. Metadata Aggregation
+    metadata: Dict[str, Any] = {}
+    
+    # Collect all LiveKit specific keys into metadata
+    metadata_keys = [
+        LK_SPEECH_ID, LK_AGENT_LABEL, LK_JOB_ID, LK_AGENT_NAME, LK_SESSION_OPTIONS,
+        LK_PARTICIPANT_ID, LK_PARTICIPANT_KIND,
+        LK_INSTRUCTIONS, LK_SPEECH_INTERRUPTED,
+        LK_TTS_STREAMING, LK_TTS_LABEL,
+        LK_EOU_DELAY, LK_EOU_LANGUAGE, LK_TRANSCRIPT_CONFIDENCE, LK_TRANSCRIPTION_DELAY, LK_END_OF_TURN_DELAY,
+        LK_USER_TRANSCRIPT, # Might be redundant with input, but good context
+        LK_FUNCTION_TOOL_IS_ERROR
+    ]
+
+    for key in metadata_keys:
+        if key in attributes:
+            metadata[key] = attributes[key]
+
+    # Also include any "metrics" attributes if they exist
+    for key in attributes:
+         if "metrics" in key or "lk.eou" in key:
+              metadata[key] = attributes[key]
+
+    # Merge with existing metadata
+    if metadata:
+        existing = attributes.get(SpanAttributes.METADATA)
+        try:
+            if isinstance(existing, str):
+                existing = json.loads(existing)
+            if isinstance(existing, dict):
+                metadata = {**existing, **metadata}
+        except Exception:
+            pass
+        mapped[SpanAttributes.METADATA] = _ensure_json_string(metadata)
+
+    # 7. Span Kind Determination (fi.span.kind)
+    if SpanAttributes.FI_SPAN_KIND not in mapped:
+        span_kind = "UNKNOWN"
+        
+        # Check based on attribute presence or span name (if available in attributes? No, span name is on the Span object)
+        # We infer from unique attributes.
+        
+        if LK_FUNCTION_TOOL_NAME in attributes:
+            span_kind = "TOOL"
+        elif LK_CHAT_CTX in attributes or ATTR_GEN_AI_REQUEST_MODEL in attributes:
+            span_kind = "LLM"
+        elif LK_TTS_INPUT_TEXT in attributes:
+             # TTS is technically model inference, map to LLM for now or generic
+             span_kind = "LLM" 
+        elif LK_USER_INPUT in attributes or LK_SPEECH_ID in attributes:
+             # Assistant Turn -> CHAIN
+             span_kind = "CHAIN"
+        elif LK_JOB_ID in attributes and LK_ROOM_NAME in attributes and LK_SESSION_OPTIONS in attributes:
+             # Session Start -> AGENT
+             span_kind = "AGENT"
+
+        mapped[SpanAttributes.FI_SPAN_KIND] = span_kind
+
+    return mapped
+
+
+class BaseMappedSpanExporter(SpanExporter):
+    """Base class for span exporters that map LiveKit attributes to Future AGI conventions."""
+
+    def _convert_attributes(self, attributes):
+        """Convert attributes by mapping them to Future AGI conventions."""
+        if attributes is None:
+            base = {}
+        elif not isinstance(attributes, dict):
+            base = dict(attributes)
+        else:
+            base = attributes
+        try:
+            return _map_attributes_to_fi_conventions(base)
+        except Exception:
+            return base
+
+    def export(self, spans) -> SpanExportResult:
+        for span in spans:
+            try:
+                if (
+                    hasattr(span, "_attributes")
+                    and getattr(span, "_attributes") is not None
+                ):
+                    original_attributes = getattr(span, "_attributes")
+
+                    base_attributes = dict(original_attributes)
+                    
+                    # Include span name in mapping logic if needed, though _convert_attributes currently only takes dict
+                    # We could pass span name to _map_attributes_to_fi_conventions if we refactored, 
+                    # but attribute-based detection is usually robust enough for LiveKit.
+                    
+                    mapped_attributes = self._convert_attributes(base_attributes)
+
+                    setattr(span, "_attributes", mapped_attributes)
+
+            except Exception:
+                continue
+
+        return super().export(spans)
+

traceai_livekit-0.1.0/traceai_livekit/exporters/grpc_exporter.py

@@ -0,0 +1,33 @@
+"""
+gRPC exporter for LiveKit integration with Future AGI.
+
+This module provides a gRPC span exporter that maps LiveKit attributes
+to Future AGI conventions.
+"""
+
+from typing import Any
+
+from .base_exporter import BaseMappedSpanExporter
+
+try:
+    # Use FI's gRPC exporter as base
+    from fi_instrumentation.otel import GRPCSpanExporter as _FIGRPCSpanExporter
+except ImportError:
+    _FIGRPCSpanExporter = None
+
+
+class MappedGRPCSpanExporter(BaseMappedSpanExporter, _FIGRPCSpanExporter):
+    """gRPC exporter that maps LiveKit attributes to Future AGI conventions."""
+
+    def __init__(self, *args: Any, **kwargs: Any):
+        """Initialize the mapped gRPC exporter."""
+        if _FIGRPCSpanExporter is None:
+            raise ImportError(
+                "fi_instrumentation is not installed. "
+                'Please install the fi_instrumentation with: pip install "fi-instrumentation-otel[grpc]"'
+            )
+        super().__init__(*args, **kwargs)
+
+    def _convert_attributes(self, attributes):
+        """Override to use the base class mapping."""
+        return super()._convert_attributes(attributes)

traceai_livekit-0.1.0/traceai_livekit/exporters/http_exporter.py

@@ -0,0 +1,33 @@
+"""
+HTTP exporter for LiveKit integration with Future AGI.
+
+This module provides an HTTP span exporter that maps LiveKit attributes
+to Future AGI conventions.
+"""
+
+from typing import Any
+
+from .base_exporter import BaseMappedSpanExporter
+
+try:
+    # Use FI's HTTP exporter as base
+    from fi_instrumentation.otel import HTTPSpanExporter as _FIHTTPSpanExporter
+except ImportError:
+    _FIHTTPSpanExporter = None
+
+
+class MappedHTTPSpanExporter(BaseMappedSpanExporter, _FIHTTPSpanExporter):
+    """HTTP exporter that maps LiveKit attributes to Future AGI conventions."""
+
+    def __init__(self, *args: Any, **kwargs: Any):
+        """Initialize the mapped HTTP exporter."""
+        if _FIHTTPSpanExporter is None:
+            raise ImportError(
+                "fi_instrumentation is not installed. "
+                'Please install the fi_instrumentation with: pip install "fi-instrumentation-otel"'
+            )
+        super().__init__(*args, **kwargs)
+
+    def _convert_attributes(self, attributes):
+        """Override to use the base class mapping."""
+        return super()._convert_attributes(attributes)

traceai_livekit-0.1.0/traceai_livekit/integration.py

@@ -0,0 +1,198 @@
+"""
+Integration functions for LiveKit with Future AGI.
+
+This module provides functions to install attribute mapping for LiveKit applications
+by updating existing span exporters in the tracer provider.
+"""
+
+import logging
+from typing import Optional
+
+from fi_instrumentation.otel import Transport
+from opentelemetry import trace as trace_api
+
+from .exporters import MappedGRPCSpanExporter, MappedHTTPSpanExporter
+
+logger = logging.getLogger(__name__)
+
+
+def enable_fi_attribute_mapping(transport: Transport = Transport.HTTP) -> bool:
+    """
+    Install the mapping exporter by swapping FI's exporter instances.
+
+    This function:
+    1. Finds existing span exporters in the global tracer provider
+    2. Replaces them with mapped exporters that convert LiveKit attributes to Future AGI conventions.
+    3. Automatically registers the global tracer provider with `livekit.agents.telemetry`.
+
+    Args:
+        transport: The transport protocol to match existing exporters (Transport enum)
+
+    Returns:
+        True if at least one exporter was swapped; False otherwise.
+    """
+    provider = trace_api.get_tracer_provider()
+    swapped_any = False
+
+    active = getattr(provider, "_active_span_processor", None)
+    if not active:
+        logger.warning("No active span processor found")
+        return False
+
+    # Handle both single processor and MultiSpanProcessor cases
+    processors = []
+    if hasattr(active, "_span_processors"):
+        processors = list(active._span_processors)
+    else:
+        processors = [active]
+
+    for proc in processors:
+        # Look for exporter in standard places
+        exporter = getattr(proc, "span_exporter", None)
+        if exporter is None:
+            exporter = getattr(proc, "_exporter", None)
+            
+        if exporter is None:
+            continue
+
+        try:
+            if transport == Transport.HTTP:
+                from fi_instrumentation.otel import (
+                    HTTPSpanExporter as _FIHTTPSpanExporter,
+                )
+
+                if isinstance(exporter, _FIHTTPSpanExporter):
+                    endpoint = getattr(exporter, "_endpoint", None)
+                    headers = getattr(exporter, "_headers", None)
+                    new_exporter = MappedHTTPSpanExporter(
+                        endpoint=endpoint, headers=headers
+                    )
+
+                    # Replace exporter in the processor
+                    if hasattr(proc, "_batch_processor"):
+                         # Some batch processor implementations wrap logic
+                         setattr(proc._batch_processor, "_exporter", new_exporter)
+                    elif hasattr(proc, "span_exporter"):
+                        try:
+                             setattr(proc, "span_exporter", new_exporter)
+                        except AttributeError:
+                             # Fallback for read-only property, try internal
+                             if hasattr(proc, "_exporter"):
+                                  setattr(proc, "_exporter", new_exporter)
+                    elif hasattr(proc, "_exporter"):
+                        setattr(proc, "_exporter", new_exporter)
+
+                    swapped_any = True
+                    logger.info("Replaced HTTP exporter with mapped LiveKit HTTP exporter")
+
+            elif transport == Transport.GRPC:
+                from fi_instrumentation.otel import (
+                    GRPCSpanExporter as _FIGRPCSpanExporter,
+                )
+
+                if isinstance(exporter, _FIGRPCSpanExporter):
+                    endpoint = getattr(exporter, "_endpoint", None)
+                    headers = getattr(exporter, "_headers", None)
+                    new_exporter = MappedGRPCSpanExporter(
+                        endpoint=endpoint, headers=headers
+                    )
+
+                    if hasattr(proc, "_batch_processor"):
+                         setattr(proc._batch_processor, "_exporter", new_exporter)
+                    elif hasattr(proc, "span_exporter"):
+                        try:
+                             setattr(proc, "span_exporter", new_exporter)
+                        except AttributeError:
+                             if hasattr(proc, "_exporter"):
+                                  setattr(proc, "_exporter", new_exporter)
+                    elif hasattr(proc, "_exporter"):
+                        setattr(proc, "_exporter", new_exporter)
+
+                    swapped_any = True
+                    logger.info("Replaced gRPC exporter with mapped LiveKit gRPC exporter")
+
+        except ImportError as e:
+            logger.warning(f"Failed to import required exporter: {e}")
+            continue
+        except Exception as e:
+            logger.warning(f"Failed to replace exporter: {e}")
+            continue
+
+    if not swapped_any:
+        logger.warning(f"No {transport.value} exporters found to replace")
+    
+    # Automatically set the tracer provider for LiveKit agents
+    try:
+        from livekit.agents.telemetry import set_tracer_provider
+        set_tracer_provider(provider)
+        logger.info("Automatically configured LiveKit agents tracer provider")
+    except ImportError:
+        logger.warning("livekit.agents.telemetry not found. Skipping set_tracer_provider.")
+    except Exception as e:
+        logger.warning(f"Failed to set LiveKit tracer provider: {e}")
+
+    return swapped_any
+
+
+def enable_http_attribute_mapping() -> bool:
+    """
+    Install HTTP attribute mapping for LiveKit and configure the LiveKit tracer provider.
+
+    Convenience function that calls enable_fi_attribute_mapping with HTTP transport.
+
+    Returns:
+        True if at least one exporter was swapped; False otherwise.
+    """
+    return enable_fi_attribute_mapping(transport=Transport.HTTP)
+
+
+def enable_grpc_attribute_mapping() -> bool:
+    """
+    Install gRPC attribute mapping for LiveKit and configure the LiveKit tracer provider.
+
+    Convenience function that calls enable_fi_attribute_mapping with gRPC transport.
+
+    Returns:
+        True if at least one exporter was swapped; False otherwise.
+    """
+    return enable_fi_attribute_mapping(transport=Transport.GRPC)
+
+
+def create_mapped_http_exporter(
+    endpoint: Optional[str] = None, headers: Optional[dict] = None
+):
+    """
+    Create a mapped HTTP exporter for LiveKit.
+
+    This function creates a new HTTP exporter that maps LiveKit attributes
+    to Future AGI conventions. It can be used independently without
+    modifying existing exporters.
+
+    Args:
+        endpoint: The collector endpoint (optional, will use environment defaults)
+        headers: Optional headers to include in requests (optional, will use environment defaults)
+
+    Returns:
+        A configured MappedHTTPSpanExporter instance
+    """
+    return MappedHTTPSpanExporter(endpoint=endpoint, headers=headers)
+
+
+def create_mapped_grpc_exporter(
+    endpoint: Optional[str] = None, headers: Optional[dict] = None
+):
+    """
+    Create a mapped gRPC exporter for LiveKit.
+
+    This function creates a new gRPC exporter that maps LiveKit attributes
+    to Future AGI conventions. It can be used independently without
+    modifying existing exporters.
+
+    Args:
+        endpoint: The collector endpoint (optional, will use environment defaults)
+        headers: Optional headers to include in requests (optional, will use environment defaults)
+
+    Returns:
+        A configured MappedGRPCSpanExporter instance
+    """
+    return MappedGRPCSpanExporter(endpoint=endpoint, headers=headers)