aip-agents-binary 0.0.0__py3-none-any.whl

aip_agents/audio_interface/audio_agent_adapter.py

@@ -0,0 +1,254 @@
+"""Adapter that routes transcripts into an AIP agent."""
+
+from __future__ import annotations
+
+import inspect
+import json
+import os
+import uuid
+from collections.abc import Awaitable, Callable
+from typing import Any, cast
+
+from aip_agents.schema.a2a import A2AStreamEventType
+
+
+class AIPAudioAgentAdapter:
+    """Adapter that turns transcript text into agent replies.
+
+    This wrapper:
+    - calls the agent's `arun(...)` method
+    - injects a stable thread id via `configurable` for conversation persistence
+    - optionally prints internal LangGraph step events when `AIP_AUDIO_DEBUG=1`
+    """
+
+    def __init__(self, agent: Any) -> None:
+        """Create an adapter around an async-capable agent."""
+        self._agent = agent
+        self._thread_id = str(uuid.uuid4())
+        self._debug = os.environ.get("AIP_AUDIO_DEBUG") == "1"
+
+    async def generate_reply(
+        self,
+        text: str,
+        *,
+        on_a2a_event: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
+        prefer_a2a_stream: bool = False,
+        **kwargs: Any,
+    ) -> str:
+        """Generate an agent reply for a single user transcript.
+
+        Args:
+            text: Final transcript text.
+            on_a2a_event: Optional async callback invoked for each A2A stream event.
+            prefer_a2a_stream: When True, uses `arun_a2a_stream(...)` if available even
+                when debug mode is disabled.
+            **kwargs: Passed through to the underlying agent call.
+        """
+        self._ensure_thread_id(kwargs)
+
+        arun_a2a_stream = getattr(self._agent, "arun_a2a_stream", None)
+        if callable(arun_a2a_stream) and (prefer_a2a_stream or self._debug):
+            return await self._arun_via_a2a_stream(
+                text,
+                arun_a2a_stream=arun_a2a_stream,
+                on_a2a_event=on_a2a_event,
+                debug=self._debug,
+                **kwargs,
+            )
+
+        if not self._debug:
+            return await self._arun_basic(text, **kwargs)
+
+        # Debug fallback for agents without A2A streaming support.
+        if not hasattr(self._agent, "_compiled_graph"):
+            return await self._arun_basic(text, **kwargs)
+
+        create_cfg = getattr(self._agent, "_create_graph_config", None)
+        get_tid = getattr(self._agent, "_get_thread_id_from_config", None)
+        prep_input = getattr(self._agent, "_prepare_graph_input", None)
+        fmt_output = getattr(self._agent, "_format_graph_output", None)
+        if not (callable(create_cfg) and callable(get_tid) and callable(prep_input) and callable(fmt_output)):
+            return await self._arun_basic(text, **kwargs)
+
+        return await self._arun_with_compiled_graph_steps(text, **kwargs)
+
+    def _ensure_thread_id(self, kwargs: dict[str, Any]) -> None:
+        """Ensure a stable thread_id is injected into kwargs for persistence."""
+        configurable = kwargs.get("configurable")
+        if not isinstance(configurable, dict):
+            configurable = {}
+            kwargs["configurable"] = configurable
+
+        thread_id_key = getattr(self._agent, "thread_id_key", "thread_id") or "thread_id"
+        configurable.setdefault(thread_id_key, self._thread_id)
+
+    async def _arun_basic(self, text: str, **kwargs: Any) -> str:
+        arun = getattr(self._agent, "arun", None)
+        if not callable(arun):
+            raise TypeError(f"Agent does not support arun(): {type(self._agent).__name__}")
+
+        maybe = arun(text, **kwargs)
+        if inspect.isawaitable(maybe):
+            result = await cast(Awaitable[Any], maybe)
+        else:
+            result = maybe
+
+        if isinstance(result, dict) and isinstance(result.get("output"), str):
+            return result["output"]
+        return str(result)
+
+    async def _arun_with_steps(self, text: str, **kwargs: Any) -> str:
+        """Backwards-compatible alias for debug mode."""
+        return await self.generate_reply(text, prefer_a2a_stream=True, **kwargs)
+
+    async def _arun_with_compiled_graph_steps(self, text: str, **kwargs: Any) -> str:
+        """Fallback debug streaming for agents without A2A streaming support."""
+        # Create config and get thread_id using agent's internal logic.
+        config = self._agent._create_graph_config(**kwargs)
+        thread_id = self._agent._get_thread_id_from_config(config)
+        graph_input = self._agent._prepare_graph_input(text, thread_id=thread_id, **kwargs)
+
+        final_state: Any | None = None
+        async for event in self._agent._compiled_graph.astream_events(graph_input, config=config, version="v2"):
+            final_state = self._process_compiled_graph_event(event, final_state)
+
+        if final_state is None:
+            return await self._arun_basic(text, **kwargs)
+
+        # We must use the agent's internal formatter to preserve consistent output formatting.
+        return self._agent._format_graph_output(final_state)
+
+    def _process_compiled_graph_event(self, event: dict[str, Any], final_state: Any | None) -> Any | None:
+        """Print step events and return updated final state when it becomes available."""
+        kind = event.get("event")
+        name = event.get("name")
+        data = event.get("data", {}) or {}
+
+        if kind == "on_chat_model_start":
+            print("[aip-step] agent: Thinking...")
+            return final_state
+
+        if kind == "on_tool_start":
+            inputs = data.get("input", {})
+            try:
+                inputs_str = json.dumps(inputs)
+            except (TypeError, ValueError):
+                inputs_str = str(inputs)
+            print(f"[aip-step] tool: Using '{name}' with inputs: {inputs_str}")
+            return final_state
+
+        if kind == "on_tool_end":
+            print(f"[aip-step] tool: '{name}' finished")
+            return final_state
+
+        if kind == "on_chain_end" and not event.get("parent_id"):
+            return data.get("output")
+
+        return final_state
+
+    async def _arun_via_a2a_stream(
+        self,
+        text: str,
+        *,
+        arun_a2a_stream: Any,
+        on_a2a_event: Callable[[dict[str, Any]], Awaitable[None]] | None,
+        debug: bool,
+        **kwargs: Any,
+    ) -> str:
+        """Run the agent using the public A2A event stream.
+
+        This method intentionally drains the full stream (even after FINAL_RESPONSE)
+        so LangGraph checkpointing can complete.
+        """
+        output_chunks: list[str] = []
+        final_reply: str | None = None
+
+        handlers = self._build_a2a_handlers(output_chunks) if debug else {}
+
+        async for event in arun_a2a_stream(text, **kwargs):
+            if on_a2a_event is not None and isinstance(event, dict):
+                await on_a2a_event(event)
+
+            self._check_stream_error(event)
+            self._handle_stream_event(event, output_chunks, handlers)
+
+            # Capture final response but continue draining
+            if self._is_final_response(event):
+                content = str(event.get("content") or "")
+                final_reply = content if content else "".join(output_chunks)
+
+        if final_reply is not None:
+            return final_reply
+
+        return await self._arun_basic(text, **kwargs)
+
+    def _check_stream_error(self, event: dict[str, Any]) -> None:
+        """Raise RuntimeError if the event indicates an error."""
+        raw_type = event.get("event_type")
+        event_type = raw_type.value if hasattr(raw_type, "value") else str(raw_type)
+        if event_type in (A2AStreamEventType.ERROR.value, A2AStreamEventType.STEP_LIMIT_EXCEEDED.value):
+            content = str(event.get("content") or "")
+            raise RuntimeError(content or "Streaming failed")
+
+    def _is_final_response(self, event: dict[str, Any]) -> bool:
+        """Check if event is a final response."""
+        raw_type = event.get("event_type")
+        event_type = raw_type.value if hasattr(raw_type, "value") else str(raw_type)
+        return event_type == A2AStreamEventType.FINAL_RESPONSE.value
+
+    def _handle_stream_event(
+        self,
+        event: dict[str, Any],
+        output_chunks: list[str],
+        handlers: dict[str, Callable[[str, dict[str, Any]], None]],
+    ) -> None:
+        """Process a single stream event: update chunks and invoke debug handlers."""
+        raw_type = event.get("event_type")
+        event_type = raw_type.value if hasattr(raw_type, "value") else str(raw_type)
+        content = str(event.get("content") or "")
+        tool_info = event.get("tool_info")
+        tool_info_dict = tool_info if isinstance(tool_info, dict) else {}
+
+        if event_type == A2AStreamEventType.CONTENT_CHUNK.value and content:
+            output_chunks.append(content)
+
+        handler = handlers.get(event_type)
+        if handler is not None:
+            handler(content, tool_info_dict)
+
+    def _build_a2a_handlers(self, _output_chunks: list[str]) -> dict[str, Callable[[str, dict[str, Any]], None]]:
+        """Return event handlers for debug A2A streaming."""
+
+        def _status_update(content: str, _tool_info: dict[str, Any]) -> None:
+            msg = content.strip()
+            if msg:
+                print(f"[aip-step] agent: {msg}")
+            return None
+
+        def _tool_call(_content: str, tool_info: dict[str, Any]) -> None:
+            calls = tool_info.get("tool_calls")
+            if not isinstance(calls, list):
+                return None
+            for call in calls:
+                if not isinstance(call, dict):
+                    continue
+                name = call.get("name")
+                args = call.get("args")
+                args_dict = args if isinstance(args, dict) else {}
+                try:
+                    inputs_str = json.dumps(args_dict)
+                except (TypeError, ValueError):
+                    inputs_str = str(args_dict)
+                print(f"[aip-step] tool: Using '{name}' with inputs: {inputs_str}")
+            return None
+
+        def _tool_result(_content: str, tool_info: dict[str, Any]) -> None:
+            name = tool_info.get("name")
+            print(f"[aip-step] tool: '{name}' finished")
+            return None
+
+        return {
+            A2AStreamEventType.STATUS_UPDATE.value: _status_update,
+            A2AStreamEventType.TOOL_CALL.value: _tool_call,
+            A2AStreamEventType.TOOL_RESULT.value: _tool_result,
+        }

aip_agents/audio_interface/config.py

@@ -0,0 +1,146 @@
+"""Typed config objects for audio sessions."""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from aip_agents.audio_interface.errors import AudioConfigError
+
+_ENV_REF_RE = re.compile(r"^\$\{([A-Z0-9_]+)\}$")
+
+
+def _resolve_env_ref(value: str | None) -> str | None:
+    if value is None:
+        return None
+    m = _ENV_REF_RE.match(value.strip())
+    if not m:
+        return value
+    return os.environ.get(m.group(1))
+
+
+@dataclass(frozen=True, slots=True)
+class AudioIOConfig:
+    """I/O toggles and device hints for an audio session."""
+
+    input_enabled: bool = True
+    output_enabled: bool = True
+    input_device: str | None = None
+    output_device: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class AudioModelConfig:
+    """Model selection for provider-specific audio components.
+
+    For OpenAI STT/TTS wiring in the LiveKit provider:
+      provider="openai", voice="echo"
+    """
+
+    provider: str | None = None
+    model: str | None = None
+    voice: str | None = None
+    credentials: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class LiveKitConfig:
+    """Connection and provider configuration for LiveKit audio sessions."""
+
+    url: str
+    api_key: str | None = None
+    api_secret: str | None = None
+    room_name: str | None = None
+    identity: str | None = None
+
+    # Optional: OpenAI STT/TTS via livekit-plugins-openai
+    openai_stt_model: str | None = None
+    openai_tts_model: str | None = None
+    openai_voice: str | None = None
+    openai_use_realtime_stt: bool = True
+    openai_api_key: str | None = None
+    openai_base_url: str | None = None
+
+    def resolve_api_key(self) -> str:
+        """Resolve the LiveKit API key from config/env."""
+        val = _resolve_env_ref(self.api_key) or os.environ.get("LIVEKIT_API_KEY")
+        if not val:
+            raise AudioConfigError("LIVEKIT_API_KEY missing")
+        return val
+
+    def resolve_api_secret(self) -> str:
+        """Resolve the LiveKit API secret from config/env."""
+        val = _resolve_env_ref(self.api_secret) or os.environ.get("LIVEKIT_API_SECRET")
+        if not val:
+            raise AudioConfigError("LIVEKIT_API_SECRET missing")
+        return val
+
+    def resolve_openai_api_key(self) -> str:
+        """Resolve OpenAI API key used by livekit-plugins-openai."""
+        val = _resolve_env_ref(self.openai_api_key) or os.environ.get("OPENAI_API_KEY")
+        if not val:
+            raise AudioConfigError("OPENAI_API_KEY missing (required for OpenAI STT/TTS)")
+        return val
+
+
+@dataclass(frozen=True, slots=True)
+class AudioSessionConfig:
+    """Top-level audio session config as used by the audio interface."""
+
+    provider: str = "livekit"
+    io: AudioIOConfig = AudioIOConfig()
+    model: AudioModelConfig | None = None
+    provider_config: LiveKitConfig | dict[str, Any] | None = None
+
+    @staticmethod
+    def from_agent_config_audio(raw: dict[str, Any]) -> AudioSessionConfig:
+        """Parse the `agent_config.audio` section into a typed config."""
+        if not isinstance(raw, dict):
+            raise AudioConfigError("agent_config.audio must be a dict")
+
+        provider = raw.get("provider") or "livekit"
+        io_raw = raw.get("io") or {}
+        io = AudioIOConfig(
+            input_enabled=bool(io_raw.get("input_enabled", True)),
+            output_enabled=bool(io_raw.get("output_enabled", True)),
+            input_device=io_raw.get("input_device"),
+            output_device=io_raw.get("output_device"),
+        )
+
+        model_raw = raw.get("model")
+        model: AudioModelConfig | None = None
+        if isinstance(model_raw, dict):
+            model = AudioModelConfig(
+                provider=model_raw.get("provider"),
+                model=model_raw.get("model"),
+                voice=model_raw.get("voice"),
+                credentials=model_raw.get("credentials"),
+            )
+
+        provider_cfg: LiveKitConfig | dict[str, Any] | None = None
+        if provider in {"livekit", "livekit_realtime"}:
+            lk = raw.get(provider) or raw.get("livekit")
+            if not isinstance(lk, dict):
+                raise AudioConfigError(f"{provider}.url is required")
+            url = lk.get("url")
+            if not url:
+                raise AudioConfigError(f"{provider}.url is required")
+            provider_cfg = LiveKitConfig(
+                url=str(url),
+                api_key=lk.get("api_key"),
+                api_secret=lk.get("api_secret"),
+                room_name=lk.get("room_name"),
+                identity=lk.get("identity"),
+                openai_stt_model=lk.get("openai_stt_model"),
+                openai_tts_model=lk.get("openai_tts_model"),
+                openai_voice=lk.get("openai_voice"),
+                openai_use_realtime_stt=bool(lk.get("openai_use_realtime_stt", True)),
+                openai_api_key=lk.get("openai_api_key"),
+                openai_base_url=lk.get("openai_base_url"),
+            )
+        elif isinstance(raw.get(provider), dict):
+            provider_cfg = dict(raw[provider])
+
+        return AudioSessionConfig(provider=provider, io=io, model=model, provider_config=provider_cfg)

aip_agents/audio_interface/errors.py

@@ -0,0 +1,15 @@
+"""Audio interface errors (local-only, optional deps)."""
+
+from __future__ import annotations
+
+
+class AudioInterfaceError(RuntimeError):
+    """Base error for audio interface."""
+
+
+class AudioSessionUnavailableError(AudioInterfaceError):
+    """Provider deps are missing or incompatible."""
+
+
+class AudioConfigError(AudioInterfaceError, ValueError):
+    """Audio config is missing or invalid."""