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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. traceai_livekit-0.1.3/PKG-INFO +144 -0
  2. traceai_livekit-0.1.3/README.md +112 -0
  3. traceai_livekit-0.1.3/pyproject.toml +49 -0
  4. {traceai_livekit-0.1.1 → traceai_livekit-0.1.3}/traceai_livekit/__init__.py +3 -1
  5. {traceai_livekit-0.1.1 → traceai_livekit-0.1.3}/traceai_livekit/exporters/base_exporter.py +155 -71
  6. traceai_livekit-0.1.3/traceai_livekit/integration.py +434 -0
  7. traceai_livekit-0.1.1/PKG-INFO +0 -71
  8. traceai_livekit-0.1.1/README.md +0 -55
  9. traceai_livekit-0.1.1/pyproject.toml +0 -23
  10. traceai_livekit-0.1.1/traceai_livekit/integration.py +0 -198
  11. {traceai_livekit-0.1.1 → traceai_livekit-0.1.3}/traceai_livekit/exporters/__init__.py +0 -0
  12. {traceai_livekit-0.1.1 → traceai_livekit-0.1.3}/traceai_livekit/exporters/grpc_exporter.py +0 -0
  13. {traceai_livekit-0.1.1 → traceai_livekit-0.1.3}/traceai_livekit/exporters/http_exporter.py +0 -0
traceai_livekit-0.1.3/PKG-INFO ADDED
@@ -0,0 +1,144 @@
1
+ Metadata-Version: 2.4
2
+ Name: traceAI-livekit
3
+ Version: 0.1.3
4
+ Summary: OpenTelemetry instrumentation for LiveKit
5
+ License: Apache-2.0
6
+ Keywords: traceai,futureagi,opentelemetry,tracing,observability,llm,livekit
7
+ Author: Future AGI
8
+ Author-email: no-reply@futureagi.com
9
+ Requires-Python: >3.9,<3.14
10
+ Classifier: Framework :: OpenTelemetry
11
+ Classifier: Framework :: OpenTelemetry :: Instrumentations
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: License :: OSI Approved :: Apache Software License
14
+ Classifier: Programming Language :: Python
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Programming Language :: Python :: 3 :: Only
21
+ Classifier: Programming Language :: Python :: 3.9
22
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
23
+ Classifier: Topic :: System :: Monitoring
24
+ Requires-Dist: fi-instrumentation-otel (>=1.1.0)
25
+ Project-URL: Changelog, https://github.com/future-agi/traceAI/blob/dev/python/frameworks/livekit/CHANGELOG.md
26
+ Project-URL: Documentation, https://docs.futureagi.com/docs/integrations/traceai/livekit
27
+ Project-URL: Homepage, https://futureagi.com
28
+ Project-URL: Issues, https://github.com/future-agi/traceAI/issues
29
+ Project-URL: Repository, https://github.com/future-agi/traceAI/tree/dev/python/frameworks/livekit
30
+ Description-Content-Type: text/markdown
31
+
32
+ # traceAI-livekit
33
+
34
+ OpenTelemetry instrumentation for LiveKit agents integrated with Future AGI.
35
+
36
+ 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.
37
+
38
+ ## Installation
39
+
40
+ ```bash
41
+ pip install traceai-livekit
42
+ ```
43
+
44
+ ## Quick Start
45
+
46
+ To instrument your LiveKit agent, simply initialize `fi-instrumentation` and enable the attribute mapping **inside your agent's entrypoint**.
47
+
48
+ ```python
49
+ from livekit.agents import AgentServer, JobContext
50
+ from fi_instrumentation.otel import register, ProjectType
51
+ from traceai_livekit import enable_http_attribute_mapping
52
+
53
+ server = AgentServer()
54
+
55
+ @server.rtc_session()
56
+ async def entrypoint(ctx: JobContext):
57
+ # 1. Initialize TraceAI (inside entrypoint for multiprocessing safety)
58
+ register(
59
+ project_name="My LiveKit Agent",
60
+ project_type=ProjectType.OBSERVE,
61
+ set_global_tracer_provider=True,
62
+ )
63
+
64
+ # 2. Enable LiveKit attribute mapping
65
+ # This automatically hooks into LiveKit's telemetry system
66
+ enable_http_attribute_mapping()
67
+
68
+ # ... rest of your agent logic ...
69
+ await ctx.connect()
70
+
71
+ if __name__ == "__main__":
72
+ server.run()
73
+ ```
74
+
75
+ `enable_http_attribute_mapping()` (or `enable_grpc_attribute_mapping()`) hands the provider to LiveKit for you. If you call
76
+ LiveKit's `set_tracer_provider` yourself on the provider `register()` returned, call it after `enable_*`: before it, the call
77
+ drops the Future AGI exporter. LiveKit installs its privacy filter once per provider, so an `allow_pii` passed in a later call is
78
+ ignored. To keep conversation content out of your traces, set `LIVEKIT_TELEMETRY_ALLOW_PII=false` before calling `enable_*`
79
+ (livekit-agents 1.8 and later).
80
+
81
+ ### Flushing at the end of a job
82
+
83
+ On Linux a LiveKit job process ends without running `atexit`, and LiveKit flushes only its own processors, so the spans
84
+ still queued when a job ends, such as the root `agent_session` span, used to never reach Future AGI. `enable_*` now sends
85
+ them twice over:
86
+
87
+ - **When the job shuts down**, if `enable_*` runs inside a job (the usual place, the entrypoint): this sends the voice
88
+ trace, `agent_session` included, as soon as the call ends.
89
+ - **When the process exits**, just before it stops: this sends what LiveKit ends after the shutdown callbacks, its own
90
+ `job_shutdown` span, and the job's root `job_entrypoint` span when tracing is set up before the job starts. With
91
+ set-up inside the entrypoint, LiveKit starts `job_entrypoint` before tracing is on, so it is never recorded and the
92
+ job trace arrives rooted at `job_shutdown`.
93
+
94
+ Each waits at most 3 seconds for the collector, well inside the 10 seconds LiveKit gives a job process to exit, so its own
95
+ clean-up still runs when the collector is slow.
96
+
97
+ If you set tracing up outside a job (for example at import time, in the job process), only the process-exit flush runs.
98
+ To also send each call's trace as soon as the call ends, call `flush_on_job_shutdown()` in each job entrypoint:
99
+
100
+ ```python
101
+ from traceai_livekit import flush_on_job_shutdown
102
+
103
+ @server.rtc_session()
104
+ async def entrypoint(ctx: JobContext):
105
+ flush_on_job_shutdown()
106
+ ...
107
+ ```
108
+
109
+ Do not pass `provider.force_flush` to `ctx.add_shutdown_callback`: LiveKit calls it with the shutdown reason, which
110
+ `force_flush` takes as its timeout, so it fails and nothing is flushed.
111
+
112
+ Limits:
113
+ - A process LiveKit kills (for example when a worker drains and the job overruns its exit time) sends nothing more.
114
+ - Before livekit-agents 1.3, LiveKit closes the session at the same time as the job-shutdown flush, so that flush can miss
115
+ `agent_session`; the process-exit flush still sends it.
116
+ - A second `AgentSession` in one job that is still closing when the shutdown callbacks run is sent by the process-exit
117
+ flush, not the job-shutdown one.
118
+ - In LiveKit Cloud observability mode the session's parent span is recorded on LiveKit's own provider and never reaches
119
+ Future AGI, so the trace has no stored root there.
120
+
121
+ ## Compatibility
122
+
123
+ * **livekit-agents**: 1.x. 1.8 is the tested version (it needs Python 3.10 or later). Since 1.7, LiveKit names its content
124
+ attributes `lk.pii.*` (for example `lk.pii.user_input`); both those names and the earlier ones are mapped to `input.value`
125
+ and `output.value`.
126
+ * **fi-instrumentation-otel**: 1.1.0 or later (1.0.0 fails inside `register()` with OpenTelemetry 1.45, which livekit-agents
127
+ 1.8.7 and later require). 1.0 moved span attributes from the `llm.*` names to the OpenTelemetry GenAI `gen_ai.*` names, and
128
+ renamed the `SpanAttributes` constants with them. Code that only calls `register()` is unaffected; if your code sets or reads
129
+ those attributes directly, see the
130
+ [mapping from the old names](https://github.com/future-agi/traceAI/blob/main/docs/OTEL_GENAI_SEMANTIC_CONVENTIONS.md#migration-from-openinference-llm).
131
+
132
+ ## Features
133
+
134
+ * **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`).
135
+ * **Raw Data Preservation**: Keeps original LiveKit attributes and adds `raw.input` / `raw.output` for full debugging context.
136
+ * **Multiprocessing Support**: Designed to work with LiveKit's worker process model.
137
+ * **Event Parsing**: Extracts LLM outputs from `gen_ai.choice` events when available.
138
+
139
+ ## Examples
140
+
141
+ Check the `examples/` directory for complete working agents:
142
+ * `simple_agent.py`: A basic voice assistant agent.
143
+ * `egress_agent.py`: An agent with call recording (Egress) enabled.
144
+
traceai_livekit-0.1.3/README.md ADDED
@@ -0,0 +1,112 @@
1
+ # traceAI-livekit
2
+
3
+ OpenTelemetry instrumentation for LiveKit agents integrated with Future AGI.
4
+
5
+ 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.
6
+
7
+ ## Installation
8
+
9
+ ```bash
10
+ pip install traceai-livekit
11
+ ```
12
+
13
+ ## Quick Start
14
+
15
+ To instrument your LiveKit agent, simply initialize `fi-instrumentation` and enable the attribute mapping **inside your agent's entrypoint**.
16
+
17
+ ```python
18
+ from livekit.agents import AgentServer, JobContext
19
+ from fi_instrumentation.otel import register, ProjectType
20
+ from traceai_livekit import enable_http_attribute_mapping
21
+
22
+ server = AgentServer()
23
+
24
+ @server.rtc_session()
25
+ async def entrypoint(ctx: JobContext):
26
+ # 1. Initialize TraceAI (inside entrypoint for multiprocessing safety)
27
+ register(
28
+ project_name="My LiveKit Agent",
29
+ project_type=ProjectType.OBSERVE,
30
+ set_global_tracer_provider=True,
31
+ )
32
+
33
+ # 2. Enable LiveKit attribute mapping
34
+ # This automatically hooks into LiveKit's telemetry system
35
+ enable_http_attribute_mapping()
36
+
37
+ # ... rest of your agent logic ...
38
+ await ctx.connect()
39
+
40
+ if __name__ == "__main__":
41
+ server.run()
42
+ ```
43
+
44
+ `enable_http_attribute_mapping()` (or `enable_grpc_attribute_mapping()`) hands the provider to LiveKit for you. If you call
45
+ LiveKit's `set_tracer_provider` yourself on the provider `register()` returned, call it after `enable_*`: before it, the call
46
+ drops the Future AGI exporter. LiveKit installs its privacy filter once per provider, so an `allow_pii` passed in a later call is
47
+ ignored. To keep conversation content out of your traces, set `LIVEKIT_TELEMETRY_ALLOW_PII=false` before calling `enable_*`
48
+ (livekit-agents 1.8 and later).
49
+
50
+ ### Flushing at the end of a job
51
+
52
+ On Linux a LiveKit job process ends without running `atexit`, and LiveKit flushes only its own processors, so the spans
53
+ still queued when a job ends, such as the root `agent_session` span, used to never reach Future AGI. `enable_*` now sends
54
+ them twice over:
55
+
56
+ - **When the job shuts down**, if `enable_*` runs inside a job (the usual place, the entrypoint): this sends the voice
57
+ trace, `agent_session` included, as soon as the call ends.
58
+ - **When the process exits**, just before it stops: this sends what LiveKit ends after the shutdown callbacks, its own
59
+ `job_shutdown` span, and the job's root `job_entrypoint` span when tracing is set up before the job starts. With
60
+ set-up inside the entrypoint, LiveKit starts `job_entrypoint` before tracing is on, so it is never recorded and the
61
+ job trace arrives rooted at `job_shutdown`.
62
+
63
+ Each waits at most 3 seconds for the collector, well inside the 10 seconds LiveKit gives a job process to exit, so its own
64
+ clean-up still runs when the collector is slow.
65
+
66
+ If you set tracing up outside a job (for example at import time, in the job process), only the process-exit flush runs.
67
+ To also send each call's trace as soon as the call ends, call `flush_on_job_shutdown()` in each job entrypoint:
68
+
69
+ ```python
70
+ from traceai_livekit import flush_on_job_shutdown
71
+
72
+ @server.rtc_session()
73
+ async def entrypoint(ctx: JobContext):
74
+ flush_on_job_shutdown()
75
+ ...
76
+ ```
77
+
78
+ Do not pass `provider.force_flush` to `ctx.add_shutdown_callback`: LiveKit calls it with the shutdown reason, which
79
+ `force_flush` takes as its timeout, so it fails and nothing is flushed.
80
+
81
+ Limits:
82
+ - A process LiveKit kills (for example when a worker drains and the job overruns its exit time) sends nothing more.
83
+ - Before livekit-agents 1.3, LiveKit closes the session at the same time as the job-shutdown flush, so that flush can miss
84
+ `agent_session`; the process-exit flush still sends it.
85
+ - A second `AgentSession` in one job that is still closing when the shutdown callbacks run is sent by the process-exit
86
+ flush, not the job-shutdown one.
87
+ - In LiveKit Cloud observability mode the session's parent span is recorded on LiveKit's own provider and never reaches
88
+ Future AGI, so the trace has no stored root there.
89
+
90
+ ## Compatibility
91
+
92
+ * **livekit-agents**: 1.x. 1.8 is the tested version (it needs Python 3.10 or later). Since 1.7, LiveKit names its content
93
+ attributes `lk.pii.*` (for example `lk.pii.user_input`); both those names and the earlier ones are mapped to `input.value`
94
+ and `output.value`.
95
+ * **fi-instrumentation-otel**: 1.1.0 or later (1.0.0 fails inside `register()` with OpenTelemetry 1.45, which livekit-agents
96
+ 1.8.7 and later require). 1.0 moved span attributes from the `llm.*` names to the OpenTelemetry GenAI `gen_ai.*` names, and
97
+ renamed the `SpanAttributes` constants with them. Code that only calls `register()` is unaffected; if your code sets or reads
98
+ those attributes directly, see the
99
+ [mapping from the old names](https://github.com/future-agi/traceAI/blob/main/docs/OTEL_GENAI_SEMANTIC_CONVENTIONS.md#migration-from-openinference-llm).
100
+
101
+ ## Features
102
+
103
+ * **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`).
104
+ * **Raw Data Preservation**: Keeps original LiveKit attributes and adds `raw.input` / `raw.output` for full debugging context.
105
+ * **Multiprocessing Support**: Designed to work with LiveKit's worker process model.
106
+ * **Event Parsing**: Extracts LLM outputs from `gen_ai.choice` events when available.
107
+
108
+ ## Examples
109
+
110
+ Check the `examples/` directory for complete working agents:
111
+ * `simple_agent.py`: A basic voice assistant agent.
112
+ * `egress_agent.py`: An agent with call recording (Egress) enabled.
traceai_livekit-0.1.3/pyproject.toml ADDED
@@ -0,0 +1,49 @@
1
+ [tool.poetry]
2
+ name = "traceAI-livekit"
3
+ version = "0.1.3"
4
+ description = "OpenTelemetry instrumentation for LiveKit"
5
+ authors = ["Future AGI <no-reply@futureagi.com>"]
6
+ readme = "README.md"
7
+ packages = [
8
+ { include = "traceai_livekit" }
9
+ ]
10
+ license = "Apache-2.0"
11
+ keywords = ["traceai", "futureagi", "opentelemetry", "tracing", "observability", "llm", "livekit"]
12
+ classifiers = [
13
+ "Intended Audience :: Developers",
14
+ "License :: OSI Approved :: Apache Software License",
15
+ "Programming Language :: Python",
16
+ "Programming Language :: Python :: 3",
17
+ "Programming Language :: Python :: 3 :: Only",
18
+ "Programming Language :: Python :: 3.9",
19
+ "Programming Language :: Python :: 3.10",
20
+ "Programming Language :: Python :: 3.11",
21
+ "Programming Language :: Python :: 3.12",
22
+ "Programming Language :: Python :: 3.13",
23
+ "Framework :: OpenTelemetry",
24
+ "Framework :: OpenTelemetry :: Instrumentations",
25
+ "Topic :: Software Development :: Libraries :: Python Modules",
26
+ "Topic :: System :: Monitoring",
27
+ ]
28
+
29
+ [tool.poetry.dependencies]
30
+ python = ">3.9,<3.14"
31
+ fi-instrumentation-otel = ">=1.1.0"
32
+
33
+ [tool.poetry.group.dev.dependencies]
34
+ # livekit-agents 1.8 is the version whose privacy filter the tests cover; it needs Python 3.10+.
35
+ livekit-agents = { version = "~1.8", python = ">=3.10" }
36
+ livekit-plugins-openai = { version = "~1.8", python = ">=3.10" }
37
+ livekit-plugins-silero = { version = "~1.8", python = ">=3.10" }
38
+ python-dotenv = "*"
39
+ pytest = ">=7.0"
40
+
41
+ [tool.poetry.urls]
42
+ Homepage = "https://futureagi.com"
43
+ Documentation = "https://docs.futureagi.com/docs/integrations/traceai/livekit"
44
+ Repository = "https://github.com/future-agi/traceAI/tree/dev/python/frameworks/livekit"
45
+ Changelog = "https://github.com/future-agi/traceAI/blob/dev/python/frameworks/livekit/CHANGELOG.md"
46
+ Issues = "https://github.com/future-agi/traceAI/issues"
47
+ [build-system]
48
+ requires = ["poetry-core"]
49
+ build-backend = "poetry.core.masonry.api"
{traceai_livekit-0.1.1 → traceai_livekit-0.1.3}/traceai_livekit/__init__.py RENAMED
@@ -16,9 +16,10 @@ from .integration import (
16
16
  enable_fi_attribute_mapping,
17
17
  enable_grpc_attribute_mapping,
18
18
  enable_http_attribute_mapping,
19
+ flush_on_job_shutdown,
19
20
  )
20
21
 
21
- __version__ = "0.1.0"
22
+ __version__ = "0.1.3" # x-release-please-version
22
23
 
23
24
  __all__ = [
24
25
  "enable_fi_attribute_mapping",
@@ -26,6 +27,7 @@ __all__ = [
26
27
  "enable_grpc_attribute_mapping",
27
28
  "create_mapped_http_exporter",
28
29
  "create_mapped_grpc_exporter",
30
+ "flush_on_job_shutdown",
29
31
  # Exporters
30
32
  "MappedHTTPSpanExporter",
31
33
  "MappedGRPCSpanExporter",