traceAI-livekit 0.1.1__tar.gz → 0.1.2__tar.gz

traceai_livekit-0.1.2/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.3
+Name: traceAI-livekit
+Version: 0.1.2
+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 (>=1.1.0)
+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()
+```
+
+`enable_http_attribute_mapping()` (or `enable_grpc_attribute_mapping()`) hands the provider to LiveKit for you. If you call
+LiveKit's `set_tracer_provider` yourself on the provider `register()` returned, call it after `enable_*`: before it, the call
+drops the Future AGI exporter. LiveKit installs its privacy filter once per provider, so an `allow_pii` passed in a later call is
+ignored. To keep conversation content out of your traces, set `LIVEKIT_TELEMETRY_ALLOW_PII=false` before calling `enable_*`
+(livekit-agents 1.8 and later).
+
+### Flushing at the end of a job
+
+On Linux a LiveKit job process ends without running `atexit`, and LiveKit flushes only its own processors, so the spans
+still queued when a job ends, such as the root `agent_session` span, used to never reach Future AGI. `enable_*` now sends
+them twice over:
+
+- **When the job shuts down**, if `enable_*` runs inside a job (the usual place, the entrypoint): this sends the voice
+  trace, `agent_session` included, as soon as the call ends.
+- **When the process exits**, just before it stops: this sends what LiveKit ends after the shutdown callbacks, its own
+  `job_shutdown` span, and the job's root `job_entrypoint` span when tracing is set up before the job starts. With
+  set-up inside the entrypoint, LiveKit starts `job_entrypoint` before tracing is on, so it is never recorded and the
+  job trace arrives rooted at `job_shutdown`.
+
+Each waits at most 3 seconds for the collector, well inside the 10 seconds LiveKit gives a job process to exit, so its own
+clean-up still runs when the collector is slow.
+
+If you set tracing up outside a job (for example at import time, in the job process), only the process-exit flush runs.
+To also send each call's trace as soon as the call ends, call `flush_on_job_shutdown()` in each job entrypoint:
+
+```python
+from traceai_livekit import flush_on_job_shutdown
+
+@server.rtc_session()
+async def entrypoint(ctx: JobContext):
+    flush_on_job_shutdown()
+    ...
+```
+
+Do not pass `provider.force_flush` to `ctx.add_shutdown_callback`: LiveKit calls it with the shutdown reason, which
+`force_flush` takes as its timeout, so it fails and nothing is flushed.
+
+Limits:
+- A process LiveKit kills (for example when a worker drains and the job overruns its exit time) sends nothing more.
+- Before livekit-agents 1.3, LiveKit closes the session at the same time as the job-shutdown flush, so that flush can miss
+  `agent_session`; the process-exit flush still sends it.
+- A second `AgentSession` in one job that is still closing when the shutdown callbacks run is sent by the process-exit
+  flush, not the job-shutdown one.
+- In LiveKit Cloud observability mode the session's parent span is recorded on LiveKit's own provider and never reaches
+  Future AGI, so the trace has no stored root there.
+
+## Compatibility
+
+*   **livekit-agents**: 1.x. 1.8 is the tested version (it needs Python 3.10 or later). Since 1.7, LiveKit names its content
+    attributes `lk.pii.*` (for example `lk.pii.user_input`); both those names and the earlier ones are mapped to `input.value`
+    and `output.value`.
+*   **fi-instrumentation-otel**: 1.1.0 or later (1.0.0 fails inside `register()` with OpenTelemetry 1.45, which livekit-agents
+    1.8.7 and later require). 1.0 moved span attributes from the `llm.*` names to the OpenTelemetry GenAI `gen_ai.*` names, and
+    renamed the `SpanAttributes` constants with them. Code that only calls `register()` is unaffected; if your code sets or reads
+    those attributes directly, see the
+    [mapping from the old names](https://github.com/future-agi/traceAI/blob/main/docs/OTEL_GENAI_SEMANTIC_CONVENTIONS.md#migration-from-openinference-llm).
+
+## 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.2/README.md

@@ -0,0 +1,112 @@
+# 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()
+```
+
+`enable_http_attribute_mapping()` (or `enable_grpc_attribute_mapping()`) hands the provider to LiveKit for you. If you call
+LiveKit's `set_tracer_provider` yourself on the provider `register()` returned, call it after `enable_*`: before it, the call
+drops the Future AGI exporter. LiveKit installs its privacy filter once per provider, so an `allow_pii` passed in a later call is
+ignored. To keep conversation content out of your traces, set `LIVEKIT_TELEMETRY_ALLOW_PII=false` before calling `enable_*`
+(livekit-agents 1.8 and later).
+
+### Flushing at the end of a job
+
+On Linux a LiveKit job process ends without running `atexit`, and LiveKit flushes only its own processors, so the spans
+still queued when a job ends, such as the root `agent_session` span, used to never reach Future AGI. `enable_*` now sends
+them twice over:
+
+- **When the job shuts down**, if `enable_*` runs inside a job (the usual place, the entrypoint): this sends the voice
+  trace, `agent_session` included, as soon as the call ends.
+- **When the process exits**, just before it stops: this sends what LiveKit ends after the shutdown callbacks, its own
+  `job_shutdown` span, and the job's root `job_entrypoint` span when tracing is set up before the job starts. With
+  set-up inside the entrypoint, LiveKit starts `job_entrypoint` before tracing is on, so it is never recorded and the
+  job trace arrives rooted at `job_shutdown`.
+
+Each waits at most 3 seconds for the collector, well inside the 10 seconds LiveKit gives a job process to exit, so its own
+clean-up still runs when the collector is slow.
+
+If you set tracing up outside a job (for example at import time, in the job process), only the process-exit flush runs.
+To also send each call's trace as soon as the call ends, call `flush_on_job_shutdown()` in each job entrypoint:
+
+```python
+from traceai_livekit import flush_on_job_shutdown
+
+@server.rtc_session()
+async def entrypoint(ctx: JobContext):
+    flush_on_job_shutdown()
+    ...
+```
+
+Do not pass `provider.force_flush` to `ctx.add_shutdown_callback`: LiveKit calls it with the shutdown reason, which
+`force_flush` takes as its timeout, so it fails and nothing is flushed.
+
+Limits:
+- A process LiveKit kills (for example when a worker drains and the job overruns its exit time) sends nothing more.
+- Before livekit-agents 1.3, LiveKit closes the session at the same time as the job-shutdown flush, so that flush can miss
+  `agent_session`; the process-exit flush still sends it.
+- A second `AgentSession` in one job that is still closing when the shutdown callbacks run is sent by the process-exit
+  flush, not the job-shutdown one.
+- In LiveKit Cloud observability mode the session's parent span is recorded on LiveKit's own provider and never reaches
+  Future AGI, so the trace has no stored root there.
+
+## Compatibility
+
+*   **livekit-agents**: 1.x. 1.8 is the tested version (it needs Python 3.10 or later). Since 1.7, LiveKit names its content
+    attributes `lk.pii.*` (for example `lk.pii.user_input`); both those names and the earlier ones are mapped to `input.value`
+    and `output.value`.
+*   **fi-instrumentation-otel**: 1.1.0 or later (1.0.0 fails inside `register()` with OpenTelemetry 1.45, which livekit-agents
+    1.8.7 and later require). 1.0 moved span attributes from the `llm.*` names to the OpenTelemetry GenAI `gen_ai.*` names, and
+    renamed the `SpanAttributes` constants with them. Code that only calls `register()` is unaffected; if your code sets or reads
+    those attributes directly, see the
+    [mapping from the old names](https://github.com/future-agi/traceAI/blob/main/docs/OTEL_GENAI_SEMANTIC_CONVENTIONS.md#migration-from-openinference-llm).
+
+## 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.1 → traceai_livekit-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "traceAI-livekit"
-version = "0.1.1"
+version = "0.1.2"
 description = "OpenTelemetry instrumentation for LiveKit"
 authors = ["Future AGI <no-reply@futureagi.com>"]
 readme = "README.md"
@@ -10,13 +10,15 @@ packages = [
 
 [tool.poetry.dependencies]
 python = ">3.9,<3.14"
-fi-instrumentation-otel = ">=0.1.14"
+fi-instrumentation-otel = ">=1.1.0"
 
 [tool.poetry.group.dev.dependencies]
-livekit-agents = "*"
-livekit-plugins-openai = "*"
-livekit-plugins-silero = "*"
+# livekit-agents 1.8 is the version whose privacy filter the tests cover; it needs Python 3.10+.
+livekit-agents = { version = "~1.8", python = ">=3.10" }
+livekit-plugins-openai = { version = "~1.8", python = ">=3.10" }
+livekit-plugins-silero = { version = "~1.8", python = ">=3.10" }
 python-dotenv = "*"
+pytest = ">=7.0"
 
 [build-system]
 requires = ["poetry-core"]

{traceai_livekit-0.1.1 → traceai_livekit-0.1.2}/traceai_livekit/__init__.py

@@ -16,9 +16,10 @@ from .integration import (
     enable_fi_attribute_mapping,
     enable_grpc_attribute_mapping,
     enable_http_attribute_mapping,
+    flush_on_job_shutdown,
 )
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"
 
 __all__ = [
     "enable_fi_attribute_mapping",
@@ -26,6 +27,7 @@ __all__ = [
     "enable_grpc_attribute_mapping",
     "create_mapped_http_exporter",
     "create_mapped_grpc_exporter",
+    "flush_on_job_shutdown",
     # Exporters
     "MappedHTTPSpanExporter",
     "MappedGRPCSpanExporter",

{traceai_livekit-0.1.1 → traceai_livekit-0.1.2}/traceai_livekit/exporters/base_exporter.py

@@ -6,13 +6,62 @@ LiveKit attributes to Future AGI conventions.
 """
 
 import json
-from typing import Any, Dict
+import logging
+import threading
+from typing import Any, Dict, Iterable, Tuple
 
+from opentelemetry.sdk.trace import ReadableSpan
 from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
 
 # Import Future AGI span attribute keys
 from fi_instrumentation.fi_types import SpanAttributes
 
+logger = logging.getLogger(__name__)
+
+# The mapping failure is reported once per process: a broken install fails on every span.
+_mapping_failure_logged = False
+_mapping_failure_lock = threading.Lock()
+
+
+def _warn_mapping_failed_once(exc: BaseException) -> None:
+    """Log, once per process, that the Future AGI mapping failed. Never logs attribute values."""
+    global _mapping_failure_logged
+    with _mapping_failure_lock:
+        if _mapping_failure_logged:
+            return
+        _mapping_failure_logged = True
+    logger.warning(
+        "traceai-livekit could not map LiveKit span attributes to Future AGI conventions "
+        "(%s); spans are exported without the Future AGI mapping. "
+        "Check that fi-instrumentation-otel >= 1.1.0 is installed.",
+        type(exc).__name__,
+    )
+
+
+def _first(attributes: Dict[str, Any], keys: Iterable[str]) -> Tuple[bool, Any]:
+    """Return (found, value) for the first of `keys` present in `attributes`.
+
+    LiveKit 1.7 renamed its content attributes (`lk.user_input` -> `lk.pii.user_input`, and so
+    on). Callers pass the new name first and the earlier name after it; the new name wins when
+    both are present.
+    """
+    for key in keys:
+        if key in attributes:
+            return True, attributes[key]
+    return False, None
+
+
+def _has(attributes: Dict[str, Any], keys: Iterable[str]) -> bool:
+    return _first(attributes, keys)[0]
+
+
+def _present(value: Any) -> bool:
+    """Whether a content value holds something: not None and not an empty string.
+
+    `_ensure_json_string("")` would turn an empty value into the JSON text `'""'`.
+    """
+    return value is not None and value != ""
+
 
 def _ensure_json_string(value: Any) -> str:
     """Ensure a value is a valid JSON string."""
@@ -39,6 +88,17 @@ def _detect_mime_type(value: Any) -> str:
     return "text/plain"
 
 
+def _is_empty_function_calls(value: Any) -> bool:
+    """Whether a function-calls attribute holds no call: absent, empty, or an empty JSON list."""
+    if value is None:
+        return True
+    if isinstance(value, (list, tuple)):
+        return len(value) == 0
+    if isinstance(value, str):
+        return value.strip() in ("", "[]", "null")
+    return False
+
+
 def _map_attributes_to_fi_conventions(attributes: Dict[str, Any]) -> Dict[str, Any]:
     """Map LiveKit attributes to Future AGI conventions."""
     if not attributes:
@@ -51,56 +111,52 @@ def _map_attributes_to_fi_conventions(attributes: Dict[str, Any]) -> Dict[str, A
     # 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_IDENTITY = ("lk.pii.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_ROOM_NAME = ("lk.pii.room_name", "lk.room_name")
     LK_SESSION_OPTIONS = "lk.session_options"
 
     # Assistant Turn
-    LK_USER_INPUT = "lk.user_input"
-    LK_INSTRUCTIONS = "lk.instructions"
+    LK_USER_INPUT = ("lk.pii.user_input", "lk.user_input")
+    LK_INSTRUCTIONS = ("lk.pii.instructions", "lk.instructions")
     LK_SPEECH_INTERRUPTED = "lk.interrupted"
 
     # LLM Node
-    LK_CHAT_CTX = "lk.chat_ctx"
+    LK_CHAT_CTX = ("lk.pii.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"
+    LK_RESPONSE_TEXT = ("lk.pii.response.text", "lk.response.text")
+    LK_RESPONSE_FUNCTION_CALLS = ("lk.pii.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_ARGS = ("lk.pii.function_tool.arguments", "lk.function_tool.arguments")
     LK_FUNCTION_TOOL_IS_ERROR = "lk.function_tool.is_error"
-    LK_FUNCTION_TOOL_OUTPUT = "lk.function_tool.output"
+    LK_FUNCTION_TOOL_OUTPUT = ("lk.pii.function_tool.output", "lk.function_tool.output")
 
     # TTS Node
-    LK_TTS_INPUT_TEXT = "lk.input_text"
+    LK_TTS_INPUT_TEXT = ("lk.pii.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_USER_TRANSCRIPT = ("lk.pii.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
@@ -118,26 +174,29 @@ def _map_attributes_to_fi_conventions(attributes: Dict[str, Any]) -> Dict[str, A
     # 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)
+    found, user_input = _first(attributes, LK_USER_INPUT)
+    if found and _present(user_input):
+        input_val = user_input
+        raw_input_val = 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)
+    found, chat_ctx = _first(attributes, LK_CHAT_CTX)
+    if found:
         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)
+    found, response_text = _first(attributes, LK_RESPONSE_TEXT)
+    if found and _present(response_text):
+        output_val = response_text
         raw_output_val = output_val
-    
-    if LK_RESPONSE_FUNCTION_CALLS in attributes:
+
+    found, func_calls = _first(attributes, LK_RESPONSE_FUNCTION_CALLS)
+    # LiveKit 1.8 sets the function calls on every LLM node, as "[]" when there were none; an empty
+    # list is no output, so the reply alone stays the output.
+    if found and not _is_empty_function_calls(func_calls):
         # 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)}"
@@ -149,21 +208,24 @@ def _map_attributes_to_fi_conventions(attributes: Dict[str, Any]) -> Dict[str, A
     # 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)
+    found, tts_input = _first(attributes, LK_TTS_INPUT_TEXT)
+    if found and _present(tts_input):
+        input_val = tts_input
+        raw_input_val = tts_input
         # 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)
+    found, tool_args = _first(attributes, LK_FUNCTION_TOOL_ARGS)
+    if found and _present(tool_args):
+         input_val = tool_args
+         raw_input_val = tool_args
+
+    found, tool_output = _first(attributes, LK_FUNCTION_TOOL_OUTPUT)
+    if found and _present(tool_output):
+         output_val = tool_output
+         raw_output_val = tool_output
 
     # Case E: Session Start
     if LK_SESSION_OPTIONS in attributes and raw_input_val is None:
@@ -216,11 +278,13 @@ def _map_attributes_to_fi_conventions(attributes: Dict[str, Any]) -> Dict[str, A
         mapped[SpanAttributes.GEN_AI_TOOL_DEFINITIONS] = _ensure_json_string(attributes.get(LK_FUNCTION_TOOLS))
 
     # 5. Session & User Info
-    if LK_ROOM_NAME in attributes:
-        mapped[SpanAttributes.GEN_AI_CONVERSATION_ID] = attributes.get(LK_ROOM_NAME)
-    
-    if LK_PARTICIPANT_IDENTITY in attributes:
-        mapped[SpanAttributes.USER_ID] = attributes.get(LK_PARTICIPANT_IDENTITY)
+    found, room_name = _first(attributes, LK_ROOM_NAME)
+    if found:
+        mapped[SpanAttributes.GEN_AI_CONVERSATION_ID] = room_name
+
+    found, participant_identity = _first(attributes, LK_PARTICIPANT_IDENTITY)
+    if found:
+        mapped[SpanAttributes.USER_ID] = participant_identity
 
     # 6. Metadata Aggregation
     metadata: Dict[str, Any] = {}
@@ -237,8 +301,10 @@ def _map_attributes_to_fi_conventions(attributes: Dict[str, Any]) -> Dict[str, A
     ]
 
     for key in metadata_keys:
-        if key in attributes:
-            metadata[key] = attributes[key]
+        # A renamed key is a (new name, earlier name) tuple; each name present is recorded as is.
+        for name in (key if isinstance(key, tuple) else (key,)):
+            if name in attributes:
+                metadata[name] = attributes[name]
 
     # Also include any "metrics" attributes if they exist
     for key in attributes:
@@ -266,15 +332,15 @@ def _map_attributes_to_fi_conventions(attributes: Dict[str, Any]) -> Dict[str, A
         
         if LK_FUNCTION_TOOL_NAME in attributes:
             span_kind = "TOOL"
-        elif LK_CHAT_CTX in attributes or ATTR_GEN_AI_REQUEST_MODEL in attributes:
+        elif _has(attributes, LK_CHAT_CTX) or ATTR_GEN_AI_REQUEST_MODEL in attributes:
             span_kind = "LLM"
-        elif LK_TTS_INPUT_TEXT in attributes:
+        elif _has(attributes, LK_TTS_INPUT_TEXT):
              # 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:
+        elif _has(attributes, LK_USER_INPUT) 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:
+        elif LK_JOB_ID in attributes and _has(attributes, LK_ROOM_NAME) and LK_SESSION_OPTIONS in attributes:
              # Session Start -> AGENT
              span_kind = "AGENT"
 
@@ -296,30 +362,48 @@ class BaseMappedSpanExporter(SpanExporter):
             base = attributes
         try:
             return _map_attributes_to_fi_conventions(base)
-        except Exception:
+        except Exception as exc:
+            # The span is still exported, without the Future AGI mapping.
+            _warn_mapping_failed_once(exc)
             return base
 
     def export(self, spans) -> SpanExportResult:
+        # The spans handed in are shared with every other processor on the provider (LiveKit
+        # Cloud's exporter among them), and LiveKit redacts by attribute name. The mapping copies
+        # conversation content under names with no "pii" segment (input.value, output.value, the
+        # metadata JSON, gen_ai.conversation.id, user.id), so it must never be written back onto
+        # a span we were handed: it goes on a copy, as LiveKit's own pii.redact() builds one.
+        exported = []
         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)
-
+                exported.append(self._mapped_copy(span))
+            except Exception as exc:
+                # The span is still exported, as it is, without the Future AGI mapping.
+                _warn_mapping_failed_once(exc)
+                exported.append(span)
+
+        return super().export(exported)
+
+    def _mapped_copy(self, span):
+        """A copy of `span` carrying the mapped attributes; `span` itself when there is nothing to map."""
+        attributes = span.attributes
+        if not attributes:
+            return span
+        original = dict(attributes)
+        mapped = self._convert_attributes(dict(original))
+        if mapped == original:
+            return span
+        return ReadableSpan(
+            name=span.name,
+            context=span.context,
+            parent=span.parent,
+            resource=span.resource,
+            attributes=mapped,
+            events=span.events,
+            links=span.links,
+            kind=span.kind,
+            status=span.status,
+            start_time=span.start_time,
+            end_time=span.end_time,
+            instrumentation_scope=span.instrumentation_scope,
+        )