yee88 0.3.0__py3-none-any.whl

yee88/telegram/types.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class TelegramVoice:
+    file_id: str
+    mime_type: str | None
+    file_size: int | None
+    duration: int | None
+    raw: dict[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class TelegramDocument:
+    file_id: str
+    file_name: str | None
+    mime_type: str | None
+    file_size: int | None
+    raw: dict[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class TelegramIncomingMessage:
+    transport: str
+    chat_id: int
+    message_id: int
+    text: str
+    reply_to_message_id: int | None
+    reply_to_text: str | None
+    sender_id: int | None
+    reply_to_is_bot: bool | None = None
+    reply_to_username: str | None = None
+    media_group_id: str | None = None
+    thread_id: int | None = None
+    is_topic_message: bool | None = None
+    chat_type: str | None = None
+    is_forum: bool | None = None
+    voice: TelegramVoice | None = None
+    document: TelegramDocument | None = None
+    raw: dict[str, Any] | None = None
+
+    @property
+    def is_private(self) -> bool:
+        if self.chat_type is not None:
+            return self.chat_type == "private"
+        return self.chat_id > 0
+
+
+@dataclass(frozen=True, slots=True)
+class TelegramCallbackQuery:
+    transport: str
+    chat_id: int
+    message_id: int
+    callback_query_id: str
+    data: str | None
+    sender_id: int | None
+    raw: dict[str, Any] | None = None
+
+
+TelegramIncomingUpdate = TelegramIncomingMessage | TelegramCallbackQuery

yee88/telegram/voice.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import io
+from collections.abc import Awaitable, Callable
+from typing import Protocol
+
+from ..logging import get_logger
+from openai import AsyncOpenAI, OpenAIError
+
+from .client import BotClient
+from .types import TelegramIncomingMessage
+
+logger = get_logger(__name__)
+
+__all__ = ["transcribe_voice"]
+
+VOICE_TRANSCRIPTION_DISABLED_HINT = (
+    "voice transcription is disabled. enable it in config:\n"
+    "```toml\n"
+    "[transports.telegram]\n"
+    "voice_transcription = true\n"
+    "```"
+)
+
+
+class VoiceTranscriber(Protocol):
+    async def transcribe(self, *, model: str, audio_bytes: bytes) -> str: ...
+
+
+class OpenAIVoiceTranscriber:
+    def __init__(
+        self,
+        *,
+        base_url: str | None = None,
+        api_key: str | None = None,
+    ) -> None:
+        self._base_url = base_url
+        self._api_key = api_key
+
+    async def transcribe(self, *, model: str, audio_bytes: bytes) -> str:
+        audio_file = io.BytesIO(audio_bytes)
+        audio_file.name = "voice.ogg"
+        async with AsyncOpenAI(
+            base_url=self._base_url,
+            api_key=self._api_key,
+            timeout=120,
+        ) as client:
+            response = await client.audio.transcriptions.create(
+                model=model,
+                file=audio_file,
+            )
+        return response.text
+
+
+async def transcribe_voice(
+    *,
+    bot: BotClient,
+    msg: TelegramIncomingMessage,
+    enabled: bool,
+    model: str,
+    max_bytes: int | None = None,
+    reply: Callable[..., Awaitable[None]],
+    transcriber: VoiceTranscriber | None = None,
+    base_url: str | None = None,
+    api_key: str | None = None,
+) -> str | None:
+    voice = msg.voice
+    if voice is None:
+        return msg.text
+    if not enabled:
+        await reply(text=VOICE_TRANSCRIPTION_DISABLED_HINT)
+        return None
+    if (
+        max_bytes is not None
+        and voice.file_size is not None
+        and voice.file_size > max_bytes
+    ):
+        await reply(text="voice message is too large to transcribe.")
+        return None
+    file_info = await bot.get_file(voice.file_id)
+    if file_info is None:
+        await reply(text="failed to fetch voice file.")
+        return None
+    audio_bytes = await bot.download_file(file_info.file_path)
+    if audio_bytes is None:
+        await reply(text="failed to download voice file.")
+        return None
+    if max_bytes is not None and len(audio_bytes) > max_bytes:
+        await reply(text="voice message is too large to transcribe.")
+        return None
+    if transcriber is None:
+        transcriber = OpenAIVoiceTranscriber(base_url=base_url, api_key=api_key)
+    try:
+        return await transcriber.transcribe(model=model, audio_bytes=audio_bytes)
+    except OpenAIError as exc:
+        logger.error(
+            "openai.transcribe.error",
+            error=str(exc),
+            error_type=exc.__class__.__name__,
+        )
+        await reply(text=str(exc).strip() or "voice transcription failed")
+        return None
+    except (RuntimeError, OSError, ValueError) as exc:
+        logger.error(
+            "voice.transcribe.error",
+            error=str(exc),
+            error_type=exc.__class__.__name__,
+        )
+        await reply(text=str(exc).strip() or "voice transcription failed")
+        return None

yee88/transport.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+type ChannelId = int | str
+type MessageId = int | str
+type ThreadId = int | str
+
+
+@dataclass(frozen=True, slots=True)
+class MessageRef:
+    channel_id: ChannelId
+    message_id: MessageId
+    raw: Any | None = field(default=None, compare=False, hash=False)
+    thread_id: ThreadId | None = field(default=None, compare=False, hash=False)
+    sender_id: int | None = field(default=None, compare=False, hash=False)
+
+
+@dataclass(frozen=True, slots=True)
+class RenderedMessage:
+    text: str
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class SendOptions:
+    reply_to: MessageRef | None = None
+    notify: bool = True
+    replace: MessageRef | None = None
+    thread_id: ThreadId | None = None
+
+
+class Transport(Protocol):
+    async def close(self) -> None: ...
+
+    async def send(
+        self,
+        *,
+        channel_id: ChannelId,
+        message: RenderedMessage,
+        options: SendOptions | None = None,
+    ) -> MessageRef | None: ...
+
+    async def edit(
+        self,
+        *,
+        ref: MessageRef,
+        message: RenderedMessage,
+        wait: bool = True,
+    ) -> MessageRef | None: ...
+
+    async def delete(self, *, ref: MessageRef) -> bool: ...

yee88/transport_runtime.py

@@ -0,0 +1,323 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+from .config import ConfigError, ProjectsConfig
+from .context import RunContext
+from .directives import (
+    ParsedDirectives,
+    format_context_line,
+    parse_context_line,
+    parse_directives,
+)
+from .model import EngineId, ResumeToken
+from .plugins import normalize_allowlist
+from .router import AutoRouter, EngineStatus
+from .runner import Runner
+from .worktrees import WorktreeError, resolve_run_cwd
+
+type ContextSource = Literal[
+    "reply_ctx",
+    "directives",
+    "ambient",
+    "default_project",
+    "none",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedMessage:
+    prompt: str
+    resume_token: ResumeToken | None
+    engine_override: EngineId | None
+    context: RunContext | None
+    context_source: ContextSource = "none"
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedRunner:
+    engine: EngineId
+    runner: Runner
+    available: bool
+    issue: str | None = None
+
+
+class TransportRuntime:
+    __slots__ = (
+        "_router",
+        "_projects",
+        "_allowlist",
+        "_config_path",
+        "_plugin_configs",
+        "_watch_config",
+    )
+
+    def __init__(
+        self,
+        *,
+        router: AutoRouter,
+        projects: ProjectsConfig,
+        allowlist: Iterable[str] | None = None,
+        config_path: Path | None = None,
+        plugin_configs: Mapping[str, Any] | None = None,
+        watch_config: bool = False,
+    ) -> None:
+        self._apply(
+            router=router,
+            projects=projects,
+            allowlist=allowlist,
+            config_path=config_path,
+            plugin_configs=plugin_configs,
+            watch_config=watch_config,
+        )
+
+    def update(
+        self,
+        *,
+        router: AutoRouter,
+        projects: ProjectsConfig,
+        allowlist: Iterable[str] | None = None,
+        config_path: Path | None = None,
+        plugin_configs: Mapping[str, Any] | None = None,
+        watch_config: bool = False,
+    ) -> None:
+        self._apply(
+            router=router,
+            projects=projects,
+            allowlist=allowlist,
+            config_path=config_path,
+            plugin_configs=plugin_configs,
+            watch_config=watch_config,
+        )
+
+    def _apply(
+        self,
+        *,
+        router: AutoRouter,
+        projects: ProjectsConfig,
+        allowlist: Iterable[str] | None,
+        config_path: Path | None,
+        plugin_configs: Mapping[str, Any] | None,
+        watch_config: bool,
+    ) -> None:
+        self._router = router
+        self._projects = projects
+        self._allowlist = normalize_allowlist(allowlist)
+        self._config_path = config_path
+        self._plugin_configs = dict(plugin_configs or {})
+        self._watch_config = watch_config
+
+    @property
+    def default_engine(self) -> EngineId:
+        return self._router.default_engine
+
+    def resolve_engine(
+        self,
+        *,
+        engine_override: EngineId | None,
+        context: RunContext | None,
+    ) -> EngineId:
+        if engine_override is not None:
+            return engine_override
+        if context is None or context.project is None:
+            return self._router.default_engine
+        project = self._projects.projects.get(context.project)
+        if project is None:
+            return self._router.default_engine
+        return project.default_engine or self._router.default_engine
+
+    @property
+    def engine_ids(self) -> tuple[EngineId, ...]:
+        return self._router.engine_ids
+
+    def available_engine_ids(self) -> tuple[EngineId, ...]:
+        return tuple(entry.engine for entry in self._router.available_entries)
+
+    def engine_ids_with_status(self, status: EngineStatus) -> tuple[EngineId, ...]:
+        return tuple(
+            entry.engine for entry in self._router.entries if entry.status == status
+        )
+
+    def missing_engine_ids(self) -> tuple[EngineId, ...]:
+        return self.engine_ids_with_status("missing_cli")
+
+    def project_aliases(self) -> tuple[str, ...]:
+        return tuple(project.alias for project in self._projects.projects.values())
+
+    @property
+    def allowlist(self) -> set[str] | None:
+        return self._allowlist
+
+    @property
+    def config_path(self) -> Path | None:
+        return self._config_path
+
+    @property
+    def watch_config(self) -> bool:
+        return self._watch_config
+
+    def plugin_config(self, plugin_id: str) -> dict[str, Any]:
+        if not self._plugin_configs:
+            return {}
+        raw = self._plugin_configs.get(plugin_id)
+        if raw is None:
+            return {}
+        if not isinstance(raw, dict):
+            path = self._config_path or Path("<config>")
+            raise ConfigError(
+                f"Invalid `plugins.{plugin_id}` in {path}; expected a table."
+            )
+        return dict(raw)
+
+    def resolve_message(
+        self,
+        *,
+        text: str,
+        reply_text: str | None,
+        ambient_context: RunContext | None = None,
+        chat_id: int | None = None,
+    ) -> ResolvedMessage:
+        directives = parse_directives(
+            text,
+            engine_ids=self._router.engine_ids,
+            projects=self._projects,
+        )
+        reply_ctx = parse_context_line(reply_text, projects=self._projects)
+        resume_token = self._router.resolve_resume(directives.prompt, reply_text)
+        chat_project = self._projects.project_for_chat(chat_id)
+        default_project = chat_project or self._projects.default_project
+
+        context, context_source = self._resolve_context(
+            directives=directives,
+            reply_ctx=reply_ctx,
+            ambient_context=ambient_context,
+            default_project=default_project,
+        )
+        engine_override = self._resolve_engine_override(
+            directives_engine=directives.engine,
+        )
+
+        return ResolvedMessage(
+            prompt=directives.prompt,
+            resume_token=resume_token,
+            engine_override=engine_override,
+            context=context,
+            context_source=context_source,
+        )
+
+    def project_default_engine(self, context: RunContext | None) -> EngineId | None:
+        if context is None or context.project is None:
+            return None
+        project = self._projects.projects.get(context.project)
+        if project is None:
+            return None
+        return project.default_engine
+
+    def _resolve_context(
+        self,
+        *,
+        directives: ParsedDirectives,
+        reply_ctx: RunContext | None,
+        ambient_context: RunContext | None,
+        default_project: str | None,
+    ) -> tuple[RunContext | None, ContextSource]:
+        if reply_ctx is not None:
+            return reply_ctx, "reply_ctx"
+
+        project_key = directives.project
+        branch = directives.branch
+        if project_key is None:
+            if ambient_context is not None and ambient_context.project is not None:
+                project_key = ambient_context.project
+            else:
+                project_key = default_project
+        if (
+            branch is None
+            and ambient_context is not None
+            and ambient_context.branch is not None
+            and project_key == ambient_context.project
+        ):
+            branch = ambient_context.branch
+        context: RunContext | None = None
+        if project_key is not None or branch is not None:
+            context = RunContext(project=project_key, branch=branch)
+
+        if directives.project is not None or directives.branch is not None:
+            context_source: ContextSource = "directives"
+        elif ambient_context is not None and ambient_context.project is not None:
+            context_source = "ambient"
+        elif default_project is not None:
+            context_source = "default_project"
+        else:
+            context_source = "none"
+
+        return context, context_source
+
+    def _resolve_engine_override(
+        self,
+        *,
+        directives_engine: EngineId | None,
+    ) -> EngineId | None:
+        if directives_engine is not None:
+            return directives_engine
+        return None
+
+    @property
+    def default_project(self) -> str | None:
+        return self._projects.default_project
+
+    def normalize_project_key(self, value: str) -> str | None:
+        key = value.strip().lower()
+        if key in self._projects.projects:
+            return key
+        return None
+
+    def project_alias_for_key(self, key: str) -> str:
+        project = self._projects.projects.get(key)
+        return project.alias if project is not None else key
+
+    def default_context_for_chat(self, chat_id: int | None) -> RunContext | None:
+        project_key = self._projects.project_for_chat(chat_id)
+        if project_key is None:
+            return None
+        return RunContext(project=project_key, branch=None)
+
+    def resolve_system_prompt(self, context: RunContext | None) -> str | None:
+        project_key = context.project if context is not None else None
+        return self._projects.resolve_system_prompt(project_key)
+
+    def project_chat_ids(self) -> tuple[int, ...]:
+        return self._projects.project_chat_ids()
+
+    def resolve_runner(
+        self,
+        *,
+        resume_token: ResumeToken | None,
+        engine_override: EngineId | None,
+    ) -> ResolvedRunner:
+        entry = (
+            self._router.entry_for_engine(engine_override)
+            if resume_token is None
+            else self._router.entry_for(resume_token)
+        )
+        return ResolvedRunner(
+            engine=entry.engine,
+            runner=entry.runner,
+            available=entry.available,
+            issue=entry.issue,
+        )
+
+    def is_resume_line(self, line: str) -> bool:
+        return self._router.is_resume_line(line)
+
+    def resolve_run_cwd(self, context: RunContext | None) -> Path | None:
+        try:
+            return resolve_run_cwd(context, projects=self._projects)
+        except WorktreeError as exc:
+            raise ConfigError(str(exc)) from exc
+
+    def format_context_line(self, context: RunContext | None) -> str | None:
+        return format_context_line(context, projects=self._projects)

yee88/transports.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+from collections.abc import Iterable
+
+from .backends import EngineBackend, SetupIssue
+from .plugins import TRANSPORT_GROUP, list_ids, load_plugin_backend
+from .transport_runtime import TransportRuntime
+
+
+@dataclass(frozen=True, slots=True)
+class SetupResult:
+    issues: list[SetupIssue]
+    config_path: Path
+
+    @property
+    def ok(self) -> bool:
+        return not self.issues
+
+
+@runtime_checkable
+class TransportBackend(Protocol):
+    id: str
+    description: str
+
+    def check_setup(
+        self,
+        engine_backend: EngineBackend,
+        *,
+        transport_override: str | None = None,
+    ) -> SetupResult: ...
+
+    async def interactive_setup(self, *, force: bool) -> bool: ...
+
+    def lock_token(
+        self, *, transport_config: object, _config_path: Path
+    ) -> str | None: ...
+
+    def build_and_run(
+        self,
+        *,
+        transport_config: object,
+        config_path: Path,
+        runtime: TransportRuntime,
+        final_notify: bool,
+        default_engine_override: str | None,
+    ) -> None: ...
+
+
+def _validate_transport_backend(backend: object, ep) -> None:
+    if not isinstance(backend, TransportBackend):
+        raise TypeError(f"{ep.value} is not a TransportBackend")
+    if backend.id != ep.name:
+        raise ValueError(
+            f"{ep.value} transport id {backend.id!r} does not match entrypoint {ep.name!r}"
+        )
+
+
+def get_transport(
+    transport_id: str, *, allowlist: Iterable[str] | None = None
+) -> TransportBackend:
+    backend = load_plugin_backend(
+        TRANSPORT_GROUP,
+        transport_id,
+        allowlist=allowlist,
+        validator=_validate_transport_backend,
+        kind_label="transport",
+    )
+    assert backend is not None
+    return backend
+
+
+def list_transports(*, allowlist: Iterable[str] | None = None) -> list[str]:
+    return list_ids(TRANSPORT_GROUP, allowlist=allowlist)

yee88/utils/__init__.py

@@ -0,0 +1 @@
+"""Utility helpers for Takopi."""