codex-autorunner 0.1.0__py3-none-any.whl

codex_autorunner/voice/capture.py

@@ -0,0 +1,349 @@
+from __future__ import annotations
+
+import dataclasses
+import logging
+import time
+import uuid
+from enum import Enum
+from typing import Callable, Iterable, Optional, Protocol
+
+from .config import VoiceConfig
+from .provider import (
+    AudioChunk,
+    SpeechProvider,
+    SpeechSessionMetadata,
+    TranscriptionEvent,
+    TranscriptionStream,
+)
+
+
+class CaptureState(str, Enum):
+    IDLE = "idle"
+    AWAITING_PERMISSION = "awaiting_permission"
+    RECORDING = "recording"
+    STREAMING = "streaming"
+    FINALIZING = "finalizing"
+    ERROR = "error"
+
+
+@dataclasses.dataclass
+class CaptureCallbacks:
+    on_state: Optional[Callable[[CaptureState], None]] = None
+    on_partial: Optional[Callable[[str], None]] = None
+    on_final: Optional[Callable[[str], None]] = None
+    on_error: Optional[Callable[[str], None]] = None
+    on_warning: Optional[Callable[[str], None]] = None
+
+
+class VoiceCaptureSession(Protocol):
+    """
+    Push-to-talk lifecycle contract shared by web and TUI surfaces.
+
+    Implementations should be thin wrappers around platform-specific recorders.
+    """
+
+    def request_permission(self) -> None:
+        """Prompt for microphone permission if needed."""
+        ...
+
+    def begin_capture(self) -> None:
+        """Transition to recording and prepare buffers."""
+        ...
+
+    def handle_chunk(self, data: bytes) -> None:
+        """Accept raw PCM/encoded chunk and forward to the provider stream."""
+        ...
+
+    def end_capture(self, reason: Optional[str] = None) -> None:
+        """Stop recording and flush final transcription."""
+        ...
+
+    def fail(self, reason: str) -> None:
+        """Force-fail the session and surface the reason to the UI."""
+        ...
+
+
+class PushToTalkCapture(VoiceCaptureSession):
+    """
+    Cross-platform push-to-talk controller that sits between UI recorders and a SpeechProvider.
+
+    This keeps raw audio in-memory only and exposes explicit states so both TUI and web can
+    render consistent UX.
+    """
+
+    def __init__(
+        self,
+        provider: SpeechProvider,
+        config: VoiceConfig,
+        callbacks: Optional[CaptureCallbacks] = None,
+        permission_requester: Optional[Callable[[], bool]] = None,
+        client: Optional[str] = None,
+        logger: Optional[logging.Logger] = None,
+        now_fn: Callable[[], float] = time.monotonic,
+        max_retries: int = 1,
+        session_builder: Optional[Callable[[], SpeechSessionMetadata]] = None,
+    ) -> None:
+        self._provider = provider
+        self._config = config
+        self._callbacks = callbacks or CaptureCallbacks()
+        self._permission_requester = permission_requester or (lambda: True)
+        self._client = client
+        self._logger = logger or logging.getLogger(__name__)
+        self._now = now_fn
+        self._max_retries = max_retries
+        self._session_builder = session_builder
+
+        self._state: CaptureState = CaptureState.IDLE
+        self._permission_granted = False
+        self._stream: Optional[TranscriptionStream] = None
+        self._retry_attempts = 0
+        self._chunks: list[AudioChunk] = []
+        self._sequence = 0
+        self._started_at: Optional[float] = None
+        self._last_chunk_at: Optional[float] = None
+
+    @property
+    def state(self) -> CaptureState:
+        return self._state
+
+    def request_permission(self) -> None:
+        if self._state not in (CaptureState.IDLE, CaptureState.ERROR):
+            return
+        self._emit_state(CaptureState.AWAITING_PERMISSION)
+        try:
+            granted = bool(self._permission_requester())
+        except Exception as exc:
+            self.fail("permission_error")
+            self._logger.error(
+                "Microphone permission request failed: %s", exc, exc_info=False
+            )
+            return
+
+        if not granted:
+            self.fail("permission_denied")
+            return
+
+        self._permission_granted = True
+        self._emit_state(CaptureState.IDLE)
+
+    def begin_capture(self) -> None:
+        if not self._permission_granted:
+            self.request_permission()
+            if not self._permission_granted:
+                return
+
+        if self._state in (
+            CaptureState.RECORDING,
+            CaptureState.STREAMING,
+            CaptureState.FINALIZING,
+        ):
+            self.fail("already_recording")
+            return
+
+        try:
+            stream = self._provider.start_stream(self._build_session_metadata())
+            self._stream = stream
+        except Exception as exc:
+            self.fail("provider_error")
+            self._logger.error(
+                "Failed to start transcription stream: %s", exc, exc_info=False
+            )
+            return
+
+        now = self._now()
+        self._started_at = now
+        self._last_chunk_at = now
+        self._sequence = 0
+        self._retry_attempts = 0
+        self._chunks = []
+        self._emit_state(CaptureState.RECORDING)
+
+    def handle_chunk(self, data: bytes) -> None:
+        if self._stream is None:
+            self.fail("not_started")
+            return
+        if self._state not in (CaptureState.RECORDING, CaptureState.STREAMING):
+            return
+
+        chunk = AudioChunk(
+            data=data,
+            sample_rate=self._config.sample_rate,
+            start_ms=self._sequence * self._config.chunk_ms,
+            end_ms=(self._sequence + 1) * self._config.chunk_ms,
+            sequence=self._sequence,
+        )
+        self._chunks.append(chunk)
+        self._sequence += 1
+        self._last_chunk_at = self._now()
+
+        try:
+            events = self._stream.send_chunk(chunk)
+            self._emit_state(CaptureState.STREAMING)
+            self._handle_events(events)
+        except Exception as exc:
+            self._logger.warning(
+                "Transcription chunk failed; will retry if allowed: %s",
+                exc,
+                exc_info=False,
+            )
+            if not self._fail_with_retry("provider_error"):
+                return
+
+        self._check_timeouts()
+
+    def tick(self) -> None:
+        """
+        Allows hosts to poll for silence/timeout without spawning timers.
+        Call from UI loops to auto-stop after silence or max duration.
+        """
+        self._check_timeouts()
+
+    def end_capture(self, reason: Optional[str] = None) -> None:
+        if self._stream is None:
+            self._emit_state(CaptureState.IDLE)
+            return
+
+        while True:
+            self._emit_state(CaptureState.FINALIZING)
+            prior_retries = self._retry_attempts
+            try:
+                events = self._stream.flush_final()
+                self._handle_events(events)
+            except Exception as exc:
+                self._logger.error(
+                    "Final transcription flush failed: %s", exc, exc_info=False
+                )
+                if self._fail_with_retry("provider_error"):
+                    continue
+                return
+
+            # If _handle_events triggered a retry due to an error event, we restarted the
+            # stream and replayed chunks. We must attempt the final flush again on the
+            # restarted stream, otherwise transcription will never be produced.
+            if self._state == CaptureState.ERROR:
+                return
+            if self._retry_attempts > prior_retries:
+                continue
+            break
+
+        self._reset()
+        self._emit_state(CaptureState.IDLE)
+
+    def fail(self, reason: str) -> None:
+        if self._stream is not None:
+            try:
+                self._stream.abort(reason)
+            except Exception:
+                # Abort failures should not mask the root cause.
+                pass
+        self._reset()
+        self._emit_error(reason)
+        self._emit_state(CaptureState.ERROR)
+
+    def _build_session_metadata(self) -> SpeechSessionMetadata:
+        if self._session_builder:
+            return self._session_builder()
+        return SpeechSessionMetadata(
+            session_id=str(uuid.uuid4()),
+            provider=self._provider.name,
+            latency_mode=self._config.latency_mode,
+            client=self._client,
+        )
+
+    def _handle_events(self, events: Iterable[TranscriptionEvent]) -> None:
+        for event in events:
+            if event.error:
+                if not self._fail_with_retry(event.error):
+                    return
+                continue
+            if event.is_final:
+                if event.text:
+                    self._emit_final(event.text)
+            else:
+                if event.text:
+                    self._emit_partial(event.text)
+
+    def _emit_state(self, state: CaptureState) -> None:
+        if state == self._state:
+            return
+        self._state = state
+        if self._callbacks.on_state:
+            self._callbacks.on_state(state)
+
+    def _emit_partial(self, text: str) -> None:
+        if self._callbacks.on_partial:
+            self._callbacks.on_partial(text)
+
+    def _emit_final(self, text: str) -> None:
+        if self._callbacks.on_final:
+            self._callbacks.on_final(text)
+
+    def _emit_error(self, reason: str) -> None:
+        if self._callbacks.on_error:
+            self._callbacks.on_error(reason)
+
+    def _emit_warning(self, message: str) -> None:
+        if self._callbacks.on_warning:
+            self._callbacks.on_warning(message)
+
+    def _check_timeouts(self) -> None:
+        if self._state not in (CaptureState.RECORDING, CaptureState.STREAMING):
+            return
+        now = self._now()
+        if (
+            self._started_at is not None
+            and (now - self._started_at) * 1000 >= self._config.push_to_talk.max_ms
+        ):
+            self.end_capture("max_duration")
+            return
+        if (
+            self._last_chunk_at is not None
+            and (now - self._last_chunk_at) * 1000
+            >= self._config.push_to_talk.silence_auto_stop_ms
+        ):
+            self.end_capture("silence")
+
+    def _fail_with_retry(self, reason: str) -> bool:
+        if reason in (
+            "unauthorized",
+            "forbidden",
+            "invalid_audio",
+            "audio_too_large",
+            "rate_limited",
+        ):
+            self.fail(reason)
+            return False
+        if self._retry_attempts >= self._max_retries:
+            self.fail(reason)
+            return False
+
+        self._retry_attempts += 1
+        self._emit_warning(f"{reason}_retry")
+        try:
+            self._restart_stream()
+            return True
+        except Exception as exc:
+            self._logger.error(
+                "Retrying transcription stream failed: %s", exc, exc_info=False
+            )
+            self.fail(reason)
+            return False
+
+    def _restart_stream(self) -> None:
+        stream = self._provider.start_stream(self._build_session_metadata())
+        self._stream = stream
+        replayed_state = (
+            CaptureState.RECORDING if not self._chunks else CaptureState.STREAMING
+        )
+        for chunk in self._chunks:
+            events = stream.send_chunk(chunk)
+            self._handle_events(events)
+        self._emit_state(replayed_state)
+        self._last_chunk_at = self._now()
+
+    def _reset(self) -> None:
+        self._stream = None
+        self._chunks = []
+        self._sequence = 0
+        self._started_at = None
+        self._last_chunk_at = None

codex_autorunner/voice/config.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+import dataclasses
+import os
+from typing import Any, Dict, Mapping, MutableMapping, Optional
+
+LatencyMode = str  # Alias to keep config typed without importing Literal everywhere
+
+
+DEFAULT_PROVIDER_CONFIG: Dict[str, Dict[str, Any]] = {
+    "openai_whisper": {
+        "api_key_env": "OPENAI_API_KEY",
+        "model": "whisper-1",
+        "base_url": None,
+        "temperature": 0,
+        "language": None,
+        "redact_request": True,
+    }
+}
+
+
+@dataclasses.dataclass
+class PushToTalkConfig:
+    max_ms: int = 15_000
+    silence_auto_stop_ms: int = 1_200
+    min_hold_ms: int = 150
+
+
+@dataclasses.dataclass
+class VoiceConfig:
+    enabled: bool
+    provider: Optional[str]
+    latency_mode: LatencyMode
+    chunk_ms: int
+    sample_rate: int
+    warn_on_remote_api: bool
+    push_to_talk: PushToTalkConfig
+    providers: Dict[str, Dict[str, Any]]
+
+    @classmethod
+    def from_raw(
+        cls,
+        raw: Optional[Mapping[str, Any]],
+        env: Optional[Mapping[str, str]] = None,
+    ) -> "VoiceConfig":
+        """
+        Build a normalized VoiceConfig from config.yml voice section and env overrides.
+        This does not touch global config to keep voice optional until integrated.
+        """
+        env = env or os.environ
+        merged: MutableMapping[str, Any] = {
+            "enabled": False,
+            "provider": "openai_whisper",
+            "latency_mode": "balanced",
+            "chunk_ms": 600,
+            "sample_rate": 16_000,
+            "warn_on_remote_api": False,
+            "push_to_talk": {
+                "max_ms": 15_000,
+                "silence_auto_stop_ms": 1_200,
+                "min_hold_ms": 150,
+            },
+            "providers": dict(DEFAULT_PROVIDER_CONFIG),
+        }
+        if isinstance(raw, Mapping):
+            merged.update(raw)
+            base_pt = merged.get("push_to_talk")
+            pt_defaults: dict[str, Any] = (
+                dict(base_pt) if isinstance(base_pt, Mapping) else {}
+            )
+            pt_overrides_raw = raw.get("push_to_talk")
+            pt_overrides: dict[str, Any] = (
+                dict(pt_overrides_raw) if isinstance(pt_overrides_raw, Mapping) else {}
+            )
+            merged["push_to_talk"] = {**pt_defaults, **pt_overrides}
+
+            providers = merged.get("providers", {})
+            merged["providers"] = dict(DEFAULT_PROVIDER_CONFIG)
+            if isinstance(providers, Mapping):
+                for key, value in providers.items():
+                    if isinstance(value, Mapping):
+                        merged["providers"][key] = {
+                            **merged["providers"].get(key, {}),
+                            **dict(value),
+                        }
+
+        # Auto-enable voice if API key is available (unless explicitly disabled via env/config)
+        explicit_enabled = env.get("CODEX_AUTORUNNER_VOICE_ENABLED")
+        if explicit_enabled is not None:
+            merged["enabled"] = _env_bool(explicit_enabled, merged["enabled"])
+        elif not merged.get("enabled"):
+            # Auto-enable if the provider's API key is available
+            provider_name = env.get(
+                "CODEX_AUTORUNNER_VOICE_PROVIDER",
+                merged.get("provider", "openai_whisper"),
+            )
+            provider_cfg = merged.get("providers", {}).get(provider_name, {})
+            api_key_env = provider_cfg.get("api_key_env", "OPENAI_API_KEY")
+            if env.get(api_key_env):
+                merged["enabled"] = True
+        merged["provider"] = env.get(
+            "CODEX_AUTORUNNER_VOICE_PROVIDER", merged.get("provider")
+        )
+        merged["latency_mode"] = env.get(
+            "CODEX_AUTORUNNER_VOICE_LATENCY", merged.get("latency_mode", "balanced")
+        )
+        merged["chunk_ms"] = _env_int(
+            env.get("CODEX_AUTORUNNER_VOICE_CHUNK_MS"), merged["chunk_ms"]
+        )
+        merged["sample_rate"] = _env_int(
+            env.get("CODEX_AUTORUNNER_VOICE_SAMPLE_RATE"), merged["sample_rate"]
+        )
+        # If API key is already set, don't show the warning popup (user has already configured it)
+        explicit_warn = env.get("CODEX_AUTORUNNER_VOICE_WARN_REMOTE")
+        if explicit_warn is not None:
+            merged["warn_on_remote_api"] = _env_bool(explicit_warn, True)
+        else:
+            # Auto-disable warning if API key is present (user has intentionally configured it)
+            provider_name = merged.get("provider", "openai_whisper")
+            provider_cfg = merged.get("providers", {}).get(provider_name, {})
+            api_key_env = provider_cfg.get("api_key_env", "OPENAI_API_KEY")
+            if env.get(api_key_env):
+                merged["warn_on_remote_api"] = False
+            else:
+                merged["warn_on_remote_api"] = merged.get("warn_on_remote_api", True)
+
+        pt = merged.get("push_to_talk", {}) or {}
+        push_to_talk = PushToTalkConfig(
+            max_ms=_env_int(
+                env.get("CODEX_AUTORUNNER_VOICE_MAX_MS"), pt.get("max_ms", 15_000)
+            ),
+            silence_auto_stop_ms=_env_int(
+                env.get("CODEX_AUTORUNNER_VOICE_SILENCE_MS"),
+                pt.get("silence_auto_stop_ms", 1_200),
+            ),
+            min_hold_ms=_env_int(
+                env.get("CODEX_AUTORUNNER_VOICE_MIN_HOLD_MS"),
+                pt.get("min_hold_ms", 150),
+            ),
+        )
+
+        providers = dict(merged.get("providers") or {})
+        return cls(
+            enabled=bool(merged.get("enabled")),
+            provider=merged.get("provider"),
+            latency_mode=str(merged.get("latency_mode", "balanced")),
+            chunk_ms=int(merged.get("chunk_ms", 600)),
+            sample_rate=int(merged.get("sample_rate", 16_000)),
+            warn_on_remote_api=bool(merged.get("warn_on_remote_api", True)),
+            push_to_talk=push_to_talk,
+            providers=providers,
+        )
+
+
+def _env_bool(raw: Optional[str], default: bool) -> bool:
+    if raw is None:
+        return default
+    return raw.strip().lower() in ("1", "true", "yes", "on")
+
+
+def _env_int(raw: Optional[str], default: int) -> int:
+    if raw is None:
+        return default
+    try:
+        return int(raw.strip())
+    except (TypeError, ValueError):
+        return default

codex_autorunner/voice/provider.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import dataclasses
+from typing import Iterable, Optional, Protocol
+
+
+@dataclasses.dataclass
+class SpeechSessionMetadata:
+    """Context passed to providers to keep sessions auditable without leaking audio."""
+
+    session_id: str
+    provider: str
+    latency_mode: str
+    language: Optional[str] = None
+    client: Optional[str] = None  # e.g., "web", "tui"
+    user_agent: Optional[str] = None
+    filename: Optional[str] = None
+    content_type: Optional[str] = None
+
+
+@dataclasses.dataclass
+class AudioChunk:
+    """
+    Representation of an audio chunk pushed into the provider.
+
+    Only lightweight metadata is stored to avoid persisting raw audio outside memory.
+    """
+
+    data: bytes
+    sample_rate: int
+    start_ms: int
+    end_ms: int
+    sequence: int
+
+
+@dataclasses.dataclass
+class TranscriptionEvent:
+    text: str
+    is_final: bool
+    latency_ms: Optional[int] = None
+    error: Optional[str] = None
+
+
+class TranscriptionStream(Protocol):
+    """Streaming handle for a single push-to-talk session."""
+
+    def send_chunk(self, chunk: AudioChunk) -> Iterable[TranscriptionEvent]: ...
+
+    def flush_final(self) -> Iterable[TranscriptionEvent]:
+        """Send end-of-input and return any remaining events."""
+        ...
+
+    def abort(self, reason: Optional[str] = None) -> None:
+        """Abort the stream; providers should clean up remote resources."""
+        ...
+
+
+class SpeechProvider(Protocol):
+    """Provider abstraction so TUI and web can share the same transcription backend."""
+
+    name: str
+    supports_streaming: bool
+
+    def start_stream(self, session: SpeechSessionMetadata) -> TranscriptionStream:
+        """Begin a streaming session for a given request."""
+        ...

codex_autorunner/voice/providers/__init__.py

@@ -0,0 +1,7 @@
+from .openai_whisper import (
+    OpenAIWhisperProvider,
+    OpenAIWhisperSettings,
+    build_speech_provider,
+)
+
+__all__ = ["OpenAIWhisperProvider", "OpenAIWhisperSettings", "build_speech_provider"]