parlot-core 0.1.0__tar.gz

parlot_core-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# OS
+.DS_Store
+Thumbs.db
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+.eggs/
+*.egg
+dist/
+build/
+wheels/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test & type checkers
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.pyright/
+.hypothesis/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+
+# Secrets — never commit (keep *.example templates)
+.env
+.env.*
+!.env.example
+!.env.*.example
+
+# IDE (keep shared VS Code settings)
+.idea/
+*.swp
+*.swo
+*~
+.vscode/*
+!.vscode/settings.json
+
+# Logs
+*.log
+logs/
+examples/**/compare/**
+
+# Node
+node_modules/
+
+# Docs site
+docs/build/
+docs/.docusaurus/
+docs/package-lock.json
+

parlot_core-0.1.0/LICENSE

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

parlot_core-0.1.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.5
+Name: parlot-core
+Version: 0.1.0
+Summary: Parlot core: semantic conventions, base span processor, and shared utilities
+Project-URL: Homepage, https://parlot.ai
+Project-URL: Documentation, https://parlot.ai/docs
+Project-URL: Repository, https://github.com/parlot-ai/sdk
+Author-email: Parlot AI <hi@parlot.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,observability,opentelemetry,parlot,telemetry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: opentelemetry-api>=1.27.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27.0
+Requires-Dist: opentelemetry-sdk>=1.27.0
+Requires-Dist: opentelemetry-semantic-conventions>=0.48b0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# parlot-core
+
+Shared semantic conventions, base span processor, and utilities for all Parlot instrumentation packages.
+
+## Contents
+
+- `parlot.core.attrs` — GenAI semconv v1.41 pin, Conversation Contract / GenAI / voice span names, `ATTR_*` constants; TypeScript mirror in `@parlot/core` (`packages/core-ts`, run `uv run python scripts/generate_attrs_ts.py` after edits). Pin surface: `packages/core/genai_semconv.lock.json` (bump lock with `GENAI_SEMCONV_VERSION`)
+- `parlot.core.export` — shared `ExportFilterSpanExporter` (contract ∪ GenAI ∪ voice allowlist)
+- `parlot.core.configure` — `ConfigureProtocol` (keyword-only shared kwargs)
+- `parlot.core.session` — `SessionState`, `get_active_session()` / `session_owned()` for cross-package coexistence
+- `parlot.core.provider` — shared endpoint/api_key resolve + TracerProvider/OTLP bootstrap helpers
+- `parlot.core.bootstrap` — `GET /v1/telemetry/bootstrap` → `ParlotRuntimeContext`
+- `parlot.core.genai_content_capture` — `should_capture_genai_content` (generative AI / tool bodies; see [Concepts](https://parlot.ai/docs/concepts#generative-ai-content-capture))
+- `parlot.core.processor` — `ParlotBaseProcessor(SpanProcessor)` with shared span-mutation helpers
+- `parlot.core.platform_refs` — generic `stamp_platform_refs()` for `platform.ref.*` triples
+
+## Not for direct use
+
+This package is a dependency of instrumentation packages (`parlot-instrumentation-livekit`, `parlot-instrumentation-langgraph`, etc.). Import from those packages in your agent code, not from here directly.

parlot_core-0.1.0/README.md

@@ -0,0 +1,19 @@
+# parlot-core
+
+Shared semantic conventions, base span processor, and utilities for all Parlot instrumentation packages.
+
+## Contents
+
+- `parlot.core.attrs` — GenAI semconv v1.41 pin, Conversation Contract / GenAI / voice span names, `ATTR_*` constants; TypeScript mirror in `@parlot/core` (`packages/core-ts`, run `uv run python scripts/generate_attrs_ts.py` after edits). Pin surface: `packages/core/genai_semconv.lock.json` (bump lock with `GENAI_SEMCONV_VERSION`)
+- `parlot.core.export` — shared `ExportFilterSpanExporter` (contract ∪ GenAI ∪ voice allowlist)
+- `parlot.core.configure` — `ConfigureProtocol` (keyword-only shared kwargs)
+- `parlot.core.session` — `SessionState`, `get_active_session()` / `session_owned()` for cross-package coexistence
+- `parlot.core.provider` — shared endpoint/api_key resolve + TracerProvider/OTLP bootstrap helpers
+- `parlot.core.bootstrap` — `GET /v1/telemetry/bootstrap` → `ParlotRuntimeContext`
+- `parlot.core.genai_content_capture` — `should_capture_genai_content` (generative AI / tool bodies; see [Concepts](https://parlot.ai/docs/concepts#generative-ai-content-capture))
+- `parlot.core.processor` — `ParlotBaseProcessor(SpanProcessor)` with shared span-mutation helpers
+- `parlot.core.platform_refs` — generic `stamp_platform_refs()` for `platform.ref.*` triples
+
+## Not for direct use
+
+This package is a dependency of instrumentation packages (`parlot-instrumentation-livekit`, `parlot-instrumentation-langgraph`, etc.). Import from those packages in your agent code, not from here directly.

parlot_core-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "parlot-core"
+version = "0.1.0"
+description = "Parlot core: semantic conventions, base span processor, and shared utilities"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Parlot AI", email = "hi@parlot.ai" },
+]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Monitoring",
+]
+keywords = ["opentelemetry", "telemetry", "ai", "agents", "observability", "parlot"]
+dependencies = [
+    "opentelemetry-api>=1.27.0",
+    "opentelemetry-sdk>=1.27.0",
+    "opentelemetry-exporter-otlp-proto-http>=1.27.0",
+    "opentelemetry-semantic-conventions>=0.48b0",
+    "httpx>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://parlot.ai"
+Documentation = "https://parlot.ai/docs"
+Repository = "https://github.com/parlot-ai/sdk"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/parlot"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/parlot",
+    "README.md",
+]
+
+[tool.pyright]
+pythonVersion = "3.11"
+venvPath = "."
+venv = ".venv"
+include = ["src", "tests"]

parlot_core-0.1.0/src/parlot/core/__init__.py

@@ -0,0 +1,81 @@
+"""parlot-core: shared semantic conventions, base processor, and utilities."""
+
+from .attrs import *  # noqa: F401, F403 — re-export all attribute constants
+from .diagnostics import (
+    diagnostics_enabled,
+    init_diagnostics,
+    record_diagnostic,
+    shutdown_diagnostics,
+)
+from .escalation import human_escalation, record_human_rep
+from .metadata import set_session_attribute, set_session_metadata
+from .platform_refs import add_platform_ref, stamp_platform_refs
+from .processor import ParlotBaseProcessor, assert_sync_span_processors
+from .provider import (
+    adopt_existing_tracer_provider,
+    build_otlp_http_exporter,
+    build_resource,
+    build_tracer_provider,
+    resolve_api_key,
+    resolve_capture_genai_content,
+    resolve_endpoint,
+)
+from .bootstrap import fetch_telemetry_bootstrap
+from .configure import BaseConfigureResult, ConfigureProtocol, base_configure, configure_parlot_logging
+from .genai_content_capture import should_capture_genai_content
+from .export import ExportFilterSpanExporter
+from .intent import derive_intent
+from .logs_capture import should_capture_logs
+from .sdk_version import resolve_parlot_sdk_version, stamp_session_sdk_version
+from .session import (
+    SessionState,
+    clear_active_session,
+    get_active_session,
+    get_active_session_span,
+    session_owned,
+    set_active_session,
+)
+from .session_logs import init_session_logs, shutdown_session_logs
+from .topology import SessionTopology
+
+__all__ = [
+    "BaseConfigureResult",
+    "ConfigureProtocol",
+    "base_configure",
+    "configure_parlot_logging",
+    "ExportFilterSpanExporter",
+    "ParlotBaseProcessor",
+    "assert_sync_span_processors",
+    "SessionState",
+    "SessionTopology",
+    "add_platform_ref",
+    "adopt_existing_tracer_provider",
+    "build_otlp_http_exporter",
+    "build_resource",
+    "build_tracer_provider",
+    "clear_active_session",
+    "derive_intent",
+    "diagnostics_enabled",
+    "fetch_telemetry_bootstrap",
+    "get_active_session",
+    "get_active_session_span",
+    "human_escalation",
+    "init_diagnostics",
+    "init_session_logs",
+    "record_diagnostic",
+    "record_human_rep",
+    "resolve_api_key",
+    "resolve_capture_genai_content",
+    "resolve_endpoint",
+    "resolve_parlot_sdk_version",
+    "session_owned",
+    "set_active_session",
+    "set_session_attribute",
+    "set_session_metadata",
+    "should_capture_genai_content",
+    "should_capture_logs",
+    "shutdown_diagnostics",
+    "shutdown_session_logs",
+    "stamp_platform_refs",
+    "stamp_session_sdk_version",
+]

parlot_core-0.1.0/src/parlot/core/attrs.py

@@ -0,0 +1,304 @@
+"""
+Semantic convention attribute name constants for Parlot instrumentation.
+
+TypeScript: ``@parlot/core`` (``packages/core-ts/src/attrs.gen.ts``), generated via
+``uv run python scripts/generate_attrs_ts.py``.
+
+LiveKit vendor keys: ``parlot.instrumentation.livekit.attrs`` → ``@parlot/core/livekit``.
+OTel-standard keys (e.g. ``exception.*``) live here, not in the LiveKit vendor module.
+
+Three-layer export vocabulary (do not collapse):
+  Contract — parlot.session / parlot.turn / close / handoff
+  GenAI    — OTel GenAI SemConv v1.41.0 (invoke_agent / chat / execute_tool / invoke_workflow)
+  Voice    — tts / stt / eou_detection / amd (no GenAI equivalent)
+
+Attribute layers:
+  Layer 1 — gen_ai.*          OTel GenAI SemConv (never deviate; pin version below)
+  Layer 2 — openinference.*   OpenInference semantic model
+  Layer 3 — Parlot extensions  agent.*, voice.*, session.*, turn.*, participant.*,
+                               conversation.*, platform.ref.*
+
+Bump ``GENAI_SEMCONV_VERSION`` only with ``packages/core/genai_semconv.lock.json``.
+"""
+
+from __future__ import annotations
+
+# Pin the OTel GenAI semantic conventions revision adapters target.
+# Conventions are Development-status; bump deliberately when remapping.
+GENAI_SEMCONV_VERSION = "1.41.0"
+
+# ---------------------------------------------------------------------------
+# Layer 1 — OTel GenAI SemConv (gen_ai.*)
+# ---------------------------------------------------------------------------
+
+ATTR_GEN_AI_SYSTEM          = "gen_ai.system"
+ATTR_GEN_AI_OP_NAME         = "gen_ai.operation.name"
+ATTR_GEN_AI_PROVIDER        = "gen_ai.provider.name"
+ATTR_GEN_AI_MODEL           = "gen_ai.request.model"
+ATTR_GEN_AI_RESPONSE_MODEL  = "gen_ai.response.model"
+ATTR_GEN_AI_IN_TOKENS       = "gen_ai.usage.input_tokens"
+ATTR_GEN_AI_OUT_TOKENS      = "gen_ai.usage.output_tokens"
+ATTR_GEN_AI_CACHED_TOKENS   = "gen_ai.usage.input_cached_tokens"
+ATTR_GEN_AI_AUDIO_IN        = "gen_ai.usage.input_audio_tokens"
+ATTR_GEN_AI_AUDIO_OUT       = "gen_ai.usage.output_audio_tokens"
+ATTR_GEN_AI_COST_USD        = "gen_ai.usage.cost_usd"
+ATTR_GEN_AI_CACHE_HIT_RATE  = "gen_ai.usage.cache_hit_rate"
+ATTR_GEN_AI_TOOL_NAME       = "gen_ai.tool.name"
+
+# OTel GenAI operation.name values (Development status, semconv v1.41.0)
+GEN_AI_OP_CHAT = "chat"
+GEN_AI_OP_EXECUTE_TOOL = "execute_tool"
+GEN_AI_OP_INVOKE_AGENT = "invoke_agent"
+GEN_AI_OP_INVOKE_WORKFLOW = "invoke_workflow"
+
+# OTel GenAI Agent Spans spec (Development status, May 2026)
+ATTR_GEN_AI_AGENT_ID        = "gen_ai.agent.id"
+ATTR_GEN_AI_AGENT_NAME      = "gen_ai.agent.name"
+ATTR_GEN_AI_AGENT_VERSION   = "gen_ai.agent.version"
+ATTR_GEN_AI_CONVERSATION_ID = "gen_ai.conversation.id"   # maps to parlot conversation_id
+
+# TTS extension (not yet in spec)
+ATTR_GEN_AI_TTS_TTFB_S      = "gen_ai.tts.ttfb_s"
+
+# Tool extensions
+ATTR_GEN_AI_TOOL_IS_HANDOFF  = "gen_ai.tool.is_handoff"
+ATTR_GEN_AI_TOOL_DURATION_MS = "gen_ai.tool.duration_ms"
+ATTR_TOOL_INPUT_PAYLOAD        = "tool.input.payload"
+ATTR_TOOL_INPUT_PAYLOAD_PREVIEW = "tool.input.payload_preview"
+ATTR_TOOL_OUTPUT_PAYLOAD_PREVIEW = "tool.output.payload_preview"
+
+# GenAI message events (OTel GenAI events, used for content capture)
+EVENT_GEN_AI_USER_MESSAGE       = "gen_ai.user.message"
+EVENT_GEN_AI_ASSISTANT_MESSAGE  = "gen_ai.assistant.message"
+EVENT_GEN_AI_TOOL_MESSAGE       = "gen_ai.tool.message"
+
+# GenAI span name bases (export vocabulary; use helpers for parameterized names)
+SPAN_GEN_AI_CHAT = "chat"
+SPAN_GEN_AI_EXECUTE_TOOL = "execute_tool"
+SPAN_GEN_AI_INVOKE_AGENT = "invoke_agent"
+SPAN_GEN_AI_INVOKE_WORKFLOW = "invoke_workflow"
+
+
+def span_name_chat(model: str | None = None) -> str:
+    """OTel GenAI chat span name: ``chat`` or ``chat {model}``."""
+    model_name = (model or "").strip()
+    if model_name:
+        return f"{SPAN_GEN_AI_CHAT} {model_name}"
+    return SPAN_GEN_AI_CHAT
+
+
+def span_name_execute_tool(tool_name: str) -> str:
+    """OTel GenAI execute_tool span name: ``execute_tool {tool}``."""
+    name = (tool_name or "").strip() or "unknown"
+    return f"{SPAN_GEN_AI_EXECUTE_TOOL} {name}"
+
+# ---------------------------------------------------------------------------
+# Layer 2 — OpenInference
+# ---------------------------------------------------------------------------
+
+ATTR_OI_SPAN_KIND = "openinference.span.kind"
+# Values: AGENT | CHAIN | TOOL | RETRIEVER | LLM | EMBEDDING | EVAL
+
+# ---------------------------------------------------------------------------
+# OTel exception recording (exception.* — all frameworks, not vendor-specific)
+# ---------------------------------------------------------------------------
+
+ATTR_EXCEPTION_TYPE     = "exception.type"
+ATTR_EXCEPTION_MESSAGE  = "exception.message"
+ATTR_EXCEPTION_TRACE    = "exception.stacktrace"
+
+# ---------------------------------------------------------------------------
+# Layer 3 — Parlot extensions
+# ---------------------------------------------------------------------------
+
+# -- Agent identity (gaps the OTel spec does not cover) --------------------
+ATTR_AGENT_ROLE      = "agent.role"       # pipeline/component role: stt | tts | llm | tool | amd | pipeline | handoff | guardrail (not agent id/name)
+ATTR_AGENT_STAGE     = "agent.stage"      # lifecycle stage within role: node | request | run | turn | eou | drain | call | transfer | classify
+ATTR_AGENT_FRAMEWORK = "agent.framework"  # livekit | crewai | langgraph | adk | custom
+ATTR_AGENT_INSTRUCTIONS_EXCERPT = "agent.instructions_excerpt"
+ATTR_AGENT_STATIC_INSTRUCTIONS_EXCERPT = "agent.static_instructions_excerpt"
+ATTR_AGENT_TOOL_NAMES = "agent.tool.names"  # JSON array of tool name strings
+ATTR_AGENT_TOOL_NAME = "agent.tool.name"
+ATTR_AGENT_TOOL_IS_ERROR = "agent.tool.is_error"
+
+# -- Agent coordination ----------------------------------------------------
+ATTR_AGENT_TRANSFER_FROM    = "agent.transfer.from_agent_id"
+ATTR_AGENT_TRANSFER_TO      = "agent.transfer.to_agent_id"
+ATTR_AGENT_TRANSFER_REASON  = "agent.transfer.reason"
+ATTR_AGENT_TRANSFER_BYTES   = "agent.transfer.context_payload_bytes"
+ATTR_AGENT_TRANSFER_SEQUENCE = "agent.transfer.sequence"
+ATTR_AGENT_TRANSFER_ITEM_ID = "agent.transfer.item_id"
+ATTR_AGENT_TRANSFER_CREATED_AT = "agent.transfer.created_at"
+ATTR_AGENT_TRANSFER_LATENCY_MS = "agent.transfer.transition_latency_ms"
+ATTR_AGENT_COORD_OVERHEAD   = "agent.coordination.overhead_ms"
+ATTR_AGENT_TOOL_CALL_INDEX  = "agent.tool_call.index"
+ATTR_AGENT_TOOL_TIMING_CORRECTED = "agent.tool.timing_corrected"
+
+# -- Session ---------------------------------------------------------------
+ATTR_SESSION_ID             = "session.id"
+ATTR_SESSION_CONVERSATION_ID = "session.conversation_id"
+ATTR_SESSION_MODALITY       = "session.modality"         # voice | text | multimodal
+ATTR_SESSION_PARTICIPANT_COUNT = "session.participant_count"
+ATTR_SESSION_INTENT_LABEL   = "session.intent_label"
+ATTR_SESSION_INTENT_SEQUENCE = "session.intent.sequence"
+ATTR_SESSION_AMD            = "session.amd"              # human | voicemail | ivr | unavailable | unknown
+ATTR_SESSION_TURN_COUNT     = "session.turn_count"
+ATTR_SESSION_TOOL_CALL_COUNT = "session.tool_call_count"
+ATTR_SESSION_HANDOFF_COUNT  = "session.handoff_count"
+ATTR_SESSION_TOTAL_INPUT_TOKENS = "session.total_input_tokens"
+ATTR_SESSION_TOTAL_OUTPUT_TOKENS = "session.total_output_tokens"
+ATTR_SESSION_TOTAL_COST_USD = "session.total_cost_usd"
+ATTR_SESSION_AGENT_ID = "session.agent_id"
+ATTR_SESSION_AGENT_FRAMEWORK = "session.agent_framework"
+ATTR_SESSION_AGENT_FRAMEWORK_RAW_ID = "session.agent_framework_raw_id"
+ATTR_PARLOT_SDK_VERSION = "parlot.sdk.version"
+
+# -- Session custom metadata (public user bag; prefix-passthrough at ingest) --
+ATTR_SESSION_METADATA_PREFIX = "session.metadata."
+
+# -- OTLP metric names (Parlot contract; framework adapters map vendor usage here) --
+METRIC_USAGE_LLM_INPUT_TOKENS = "usage.llm_input_tokens"
+METRIC_USAGE_LLM_OUTPUT_TOKENS = "usage.llm_output_tokens"
+METRIC_USAGE_STT_AUDIO_DURATION = "usage.stt_audio_duration"
+METRIC_USAGE_TTS_AUDIO_DURATION = "usage.tts_audio_duration"
+METRIC_USAGE_TTS_CHARACTERS = "usage.tts_characters"
+METRIC_SESSION_TURN_COUNT = "session.turn_count"
+METRIC_SESSION_TOTAL_INPUT_TOKENS = "session.total_input_tokens"
+METRIC_SESSION_TOTAL_OUTPUT_TOKENS = "session.total_output_tokens"
+ATTR_SESSION_AGENT_CHAIN    = "session.agent_chain"
+ATTR_SESSION_TOPOLOGY_AGENTS = "session.topology.agents"
+ATTR_SESSION_TOPOLOGY_TOOLS  = "session.topology.tools"
+ATTR_SESSION_TOPOLOGY_EDGES = "session.topology.edges"
+ATTR_SESSION_TOPOLOGY_BOOTSTRAP_INSTRUCTIONS = "session.topology.bootstrap_instructions"
+ATTR_SESSION_RECORDING_ANCHOR_WALL_MS = "session.recording.anchor_wall_ms"
+ATTR_SESSION_RECORDING_AUDIO_URI = "session.recording.audio_uri"
+ATTR_SESSION_RECORDING_EGRESS_ID = "session.recording.egress_id"
+ATTR_SESSION_RECORDING_WEBHOOK_ERROR = "session.recording.webhook_error"
+ATTR_SESSION_LANGUAGES = "session.languages"
+ATTR_SESSION_CLOSE_REASON = "session.close_reason"
+ATTR_SESSION_USER_ID = "session.user_id"
+ATTR_SESSION_CLOSE_ERROR = "session.close_error"
+
+# -- Framework-agnostic Parlot span names (Conversation Contract) -----------
+SPAN_CONVERSATION_SESSION = "parlot.session"
+SPAN_PARLOT_TURN = "parlot.turn"
+SPAN_PARLOT_SESSION_CLOSE = "parlot.session.close"
+SPAN_AGENT_HANDOFF = "parlot.agent.handoff"
+
+CONTRACT_SPAN_NAMES = frozenset({
+    SPAN_CONVERSATION_SESSION,
+    SPAN_PARLOT_TURN,
+    SPAN_PARLOT_SESSION_CLOSE,
+    SPAN_AGENT_HANDOFF,
+})
+
+# -- Voice operational span names (no GenAI equivalent) ---------------------
+SPAN_VOICE_TTS = "tts"
+SPAN_VOICE_STT = "stt"
+SPAN_VOICE_EOU = "eou_detection"
+SPAN_VOICE_AMD = "amd"
+
+VOICE_SPAN_NAMES = frozenset({
+    SPAN_VOICE_TTS,
+    SPAN_VOICE_STT,
+    SPAN_VOICE_EOU,
+    SPAN_VOICE_AMD,
+})
+
+GENAI_SPAN_NAME_BASES = frozenset({
+    SPAN_GEN_AI_CHAT,
+    SPAN_GEN_AI_EXECUTE_TOOL,
+    SPAN_GEN_AI_INVOKE_AGENT,
+    SPAN_GEN_AI_INVOKE_WORKFLOW,
+})
+
+
+def is_genai_span_name(name: str | None) -> bool:
+    """True for exact GenAI bases or parameterized ``chat {model}`` / ``execute_tool {name}``."""
+    if not name:
+        return False
+    if name in GENAI_SPAN_NAME_BASES:
+        return True
+    if name.startswith(f"{SPAN_GEN_AI_CHAT} "):
+        return True
+    if name.startswith(f"{SPAN_GEN_AI_EXECUTE_TOOL} "):
+        return True
+    return False
+
+
+def is_exportable_span_name(name: str | None) -> bool:
+    """Shared export allowlist: Conversation Contract ∪ GenAI ∪ voice."""
+    if not name:
+        return False
+    if name in CONTRACT_SPAN_NAMES or name in VOICE_SPAN_NAMES:
+        return True
+    return is_genai_span_name(name)
+
+# -- Conversation ----------------------------------------------------------
+ATTR_CONVERSATION_ID      = "conversation.id"
+ATTR_CONVERSATION_CHANNEL = "conversation.channel"  # voice | webchat | sms | whatsapp
+
+# -- Turn ------------------------------------------------------------------
+ATTR_TURN_PREV_TRACE_ID     = "turn.prev_trace_id"
+ATTR_TURN_INDEX             = "turn.index"
+ATTR_TURN_PARTICIPANT_ID    = "turn.participant_id"
+ATTR_TURN_PARTICIPANT_ROLE  = "turn.participant_role"
+ATTR_TURN_PARTICIPANT_LABEL = "turn.participant_label"
+ATTR_TURN_INPUT_MODALITY    = "turn.input_modality"      # voice | text (user turns)
+ATTR_TURN_MEDIA_START_MS    = "turn.media_segment_start_ms"
+ATTR_TURN_MEDIA_END_MS      = "turn.media_segment_end_ms"
+ATTR_TURN_SPEECH_WALL_START_MS = "turn.speech_wall_start_ms"
+ATTR_TURN_SPEECH_WALL_END_MS   = "turn.speech_wall_end_ms"
+ATTR_TURN_INTERRUPTED       = "turn.interrupted"
+ATTR_TURN_E2E_LATENCY_S     = "turn.e2e_latency_s"
+ATTR_TURN_LLM_TTFT_S        = "turn.llm_ttft_s"
+ATTR_TURN_TTS_TTFB_S        = "turn.tts_ttfb_s"
+ATTR_TURN_TRANSCRIPTION_DELAY_S = "turn.transcription_delay_s"
+ATTR_TURN_EOU_DELAY_S       = "turn.eou_delay_s"
+ATTR_TURN_LANGUAGE          = "turn.language"
+ATTR_TURN_LANGUAGE_SWITCH   = "turn.language_switch"
+ATTR_TURN_USER_TEXT         = "turn.user_text"
+ATTR_TURN_AGENT_TEXT        = "turn.agent_text"
+ATTR_TURN_INTENT_LABEL      = "turn.intent_label"
+ATTR_TURN_INTENT_KEY        = "turn.intent_key"
+ATTR_TURN_ACTIVE_AGENT_ID   = "turn.active_agent_id"
+
+# -- Participant / Diarization ---------------------------------------------
+ATTR_PARTICIPANT_ID           = "participant.id"
+ATTR_PARTICIPANT_ROLE         = "participant.role"
+ATTR_PARTICIPANT_LABEL        = "participant.label"
+ATTR_PARTICIPANT_FIRST_TURN   = "participant.first_turn_index"
+ATTR_PARTICIPANT_DIAR_SOURCE  = "participant.diarization_source"
+ATTR_PARTICIPANT_CHANNEL_IDENTITY = "participant.channel_identity"
+ATTR_STT_SPEAKER_ID           = "stt.speaker_id"
+
+# participant.diarization_source values (framework-agnostic; not LiveKit-specific)
+ATTR_DIAR_SOURCE_STT_SPEAKER_ID    = "stt_speaker_id"
+ATTR_DIAR_SOURCE_AGENT_ID          = "agent_id"
+ATTR_DIAR_SOURCE_POST_SESSION      = "post_session"
+ATTR_DIAR_SOURCE_CHANNEL_METADATA  = "channel_metadata"
+
+# Default turn.participant_id before STT speaker_id is known
+ATTR_TURN_PARTICIPANT_ID_CALLER    = "caller"
+
+# -- Voice -----------------------------------------------------------------
+ATTR_VOICE_STT_LATENCY_MS    = "voice.stt.latency_ms"
+ATTR_VOICE_STT_CONFIDENCE    = "voice.stt.confidence"
+ATTR_VOICE_TTS_LATENCY_MS    = "voice.tts.latency_ms"
+ATTR_VOICE_EOU_LANGUAGE      = "voice.eou.language"
+ATTR_VOICE_AMD_CATEGORY      = "voice.amd.category"
+ATTR_VOICE_AUDIO_PACKET_LOSS = "voice.audio.packet_loss"
+ATTR_VOICE_AUDIO_JITTER_MS   = "voice.audio.jitter_ms"
+ATTR_VOICE_DEAD_AIR_MS       = "voice.interaction.dead_air_ms"
+
+# -- Eval (OpenInference, adopted) ----------------------------------------
+ATTR_EVAL_NAME        = "eval.name"
+ATTR_EVAL_RESULT      = "eval.result"
+ATTR_EVAL_SCORE       = "eval.score"
+ATTR_EVAL_EXPLANATION = "eval.explanation"
+
+# -- Platform external references (session resolve / debug linking) --------
+ATTR_PLATFORM_REF_PREFIX = "platform.ref."  # append kind for flat ref keys
+ATTR_PLATFORM_FRAMEWORK = "platform.ref.framework"
+ATTR_PLATFORM_KIND      = "platform.ref.kind"
+ATTR_PLATFORM_VALUE     = "platform.ref.value"

parlot_core-0.1.0/src/parlot/core/bootstrap.py

@@ -0,0 +1,44 @@
+"""Fetch and cache Parlot telemetry bootstrap into ``ParlotRuntimeContext``."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+logger = logging.getLogger("parlot.core.bootstrap")
+
+
+def fetch_telemetry_bootstrap(
+    endpoint: str,
+    api_key: str,
+    *,
+    timeout: float = 15.0,
+) -> Optional[dict[str, Any]]:
+    """GET ``/v1/telemetry/bootstrap`` and return the JSON payload, or None."""
+    if not endpoint or not api_key:
+        return None
+
+    import httpx
+
+    from parlot.core.runtime import runtime_from_bootstrap, set_runtime
+
+    url = f"{endpoint.rstrip('/')}/v1/telemetry/bootstrap"
+    headers = {"Authorization": f"Bearer {api_key}"}
+    try:
+        with httpx.Client(timeout=timeout) as client:
+            resp = client.get(url, headers=headers)
+        if resp.status_code >= 400:
+            logger.error(
+                "parlot: telemetry bootstrap failed status=%s",
+                resp.status_code,
+            )
+            return None
+        payload = resp.json()
+        if not isinstance(payload, dict):
+            logger.error("parlot: telemetry bootstrap returned non-object JSON")
+            return None
+        set_runtime(runtime_from_bootstrap(endpoint, api_key, payload))
+        return payload
+    except Exception:
+        logger.exception("parlot: telemetry bootstrap request failed")
+        return None