devcopilot 0.2.0__py3-none-any.whl

messaging/workflow.py

@@ -0,0 +1,200 @@
+"""Messaging workflow coordinator for Discord and Telegram prompts."""
+
+from __future__ import annotations
+
+from loguru import logger
+
+from core.trace import trace_event
+
+from .models import IncomingMessage
+from .node_runner import MessagingNodeRunner
+from .platforms.base import ManagedClaudeSessionManagerProtocol, MessagingPlatform
+from .rendering.profiles import build_rendering_profile
+from .safe_diagnostics import format_exception_for_log
+from .session import SessionStore
+from .transcript import RenderCtx
+from .trees import MessageNode, MessageState, MessageTree, TreeQueueManager
+from .turn_intake import MessagingTurnIntake
+
+
+class MessagingWorkflow:
+    """
+    Platform-agnostic messaging workflow.
+
+    It coordinates dependencies and owns stop/clear side effects. Inbound turn
+    intake and queued node execution live in dedicated collaborators.
+    """
+
+    def __init__(
+        self,
+        platform: MessagingPlatform,
+        cli_manager: ManagedClaudeSessionManagerProtocol,
+        session_store: SessionStore,
+        *,
+        debug_platform_edits: bool = False,
+        debug_subagent_stack: bool = False,
+        log_raw_messaging_content: bool = False,
+        log_raw_cli_diagnostics: bool = False,
+        log_messaging_error_details: bool = False,
+    ):
+        self.platform = platform
+        self.cli_manager = cli_manager
+        self.session_store = session_store
+        self._log_messaging_error_details = log_messaging_error_details
+        self._tree_queue = TreeQueueManager()
+        self._rendering_profile = build_rendering_profile(platform.name)
+
+        self.node_runner = MessagingNodeRunner(
+            platform=platform,
+            cli_manager=cli_manager,
+            session_store=session_store,
+            get_tree_queue=lambda: self._tree_queue,
+            format_status=self.format_status,
+            get_parse_mode=self._parse_mode,
+            get_render_ctx=self.get_render_ctx,
+            get_limit_chars=self._get_limit_chars,
+            debug_platform_edits=debug_platform_edits,
+            debug_subagent_stack=debug_subagent_stack,
+            log_raw_cli_diagnostics=log_raw_cli_diagnostics,
+            log_messaging_error_details=log_messaging_error_details,
+        )
+        self.turn_intake = MessagingTurnIntake(
+            platform=platform,
+            session_store=session_store,
+            command_context=self,
+            get_tree_queue=lambda: self._tree_queue,
+            process_node=self.node_runner.process_node,
+            format_status=self.format_status,
+            get_parse_mode=self._parse_mode,
+            record_outgoing_message=self.record_outgoing_message,
+            log_messaging_error_details=log_messaging_error_details,
+        )
+        self._wire_tree_callbacks()
+
+    def _wire_tree_callbacks(self) -> None:
+        self._tree_queue.set_queue_update_callback(
+            self.turn_intake.update_queue_positions
+        )
+        self._tree_queue.set_node_started_callback(
+            self.turn_intake.mark_node_processing
+        )
+
+    def format_status(self, emoji: str, label: str, suffix: str | None = None) -> str:
+        return self._rendering_profile.format_status(emoji, label, suffix)
+
+    def _parse_mode(self) -> str | None:
+        return self._rendering_profile.parse_mode
+
+    def get_render_ctx(self) -> RenderCtx:
+        return self._rendering_profile.render_ctx
+
+    def _get_limit_chars(self) -> int:
+        return self._rendering_profile.limit_chars
+
+    @property
+    def tree_queue(self) -> TreeQueueManager:
+        """Accessor for the current tree queue manager."""
+        return self._tree_queue
+
+    def replace_tree_queue(self, tree_queue: TreeQueueManager) -> None:
+        """Replace tree queue manager via explicit API."""
+        self._tree_queue = tree_queue
+        self._wire_tree_callbacks()
+
+    async def handle_message(self, incoming: IncomingMessage) -> None:
+        """
+        Main entry point for handling an incoming platform message.
+        """
+        platform_name = getattr(self.platform, "name", "messaging")
+        trace_event(
+            stage="ingress",
+            event="turn.received",
+            source=platform_name,
+            chat_id=incoming.chat_id,
+            platform_message_id=incoming.message_id,
+            reply_to_message_id=incoming.reply_to_message_id,
+            thread_id=getattr(incoming, "message_thread_id", None),
+            message_text=incoming.text or "",
+        )
+
+        with logger.contextualize(
+            chat_id=incoming.chat_id, node_id=incoming.message_id
+        ):
+            await self.turn_intake.handle_message(incoming)
+
+    async def update_queue_positions(self, tree: MessageTree) -> None:
+        """Refresh queued status messages after a dequeue."""
+        await self.turn_intake.update_queue_positions(tree)
+
+    async def mark_node_processing(self, tree: MessageTree, node_id: str) -> None:
+        """Update the dequeued node's status to processing immediately."""
+        await self.turn_intake.mark_node_processing(tree, node_id)
+
+    async def stop_all_tasks(self) -> int:
+        """
+        Stop all pending and in-progress messaging tasks.
+        """
+        logger.info("Cancelling tree queue tasks...")
+        cancelled_nodes = await self.tree_queue.cancel_all()
+        logger.info(f"Cancelled {len(cancelled_nodes)} nodes")
+
+        logger.info("Stopping all CLI sessions...")
+        await self.cli_manager.stop_all()
+
+        self.update_cancelled_nodes_ui(cancelled_nodes)
+        return len(cancelled_nodes)
+
+    async def stop_task(self, node_id: str) -> int:
+        """Stop a single queued or in-progress task node."""
+        tree = self.tree_queue.get_tree_for_node(node_id)
+        if tree:
+            node = tree.get_node(node_id)
+            if node and node.state not in (MessageState.COMPLETED, MessageState.ERROR):
+                node.set_context({"cancel_reason": "stop"})
+
+        cancelled_nodes = await self.tree_queue.cancel_node(node_id)
+        self.update_cancelled_nodes_ui(cancelled_nodes)
+        return len(cancelled_nodes)
+
+    def record_outgoing_message(
+        self,
+        platform: str,
+        chat_id: str,
+        msg_id: str | None,
+        kind: str,
+    ) -> None:
+        """Record outgoing message ID for /clear. Best-effort, never raises."""
+        if not msg_id:
+            return
+        try:
+            self.session_store.record_message_id(
+                platform, chat_id, str(msg_id), direction="out", kind=kind
+            )
+        except Exception as e:
+            logger.debug(
+                "Failed to record message_id: {}",
+                format_exception_for_log(
+                    e, log_full_message=self._log_messaging_error_details
+                ),
+            )
+
+    def update_cancelled_nodes_ui(self, nodes: list[MessageNode]) -> None:
+        """Update status messages and persist tree state for cancelled nodes."""
+        trees_to_save: dict[str, MessageTree] = {}
+        for node in nodes:
+            self.platform.fire_and_forget(
+                self.platform.queue_edit_message(
+                    node.incoming.chat_id,
+                    node.status_message_id,
+                    self.format_status("⏹", "Stopped."),
+                    parse_mode=self._parse_mode(),
+                )
+            )
+            tree = self.tree_queue.get_tree_for_node(node.node_id)
+            if tree:
+                trees_to_save[tree.root_id] = tree
+        for root_id, tree in trees_to_save.items():
+            self.session_store.save_tree(root_id, tree.to_dict())
+
+
+__all__ = ["MessagingWorkflow"]

providers/__init__.py

@@ -0,0 +1,31 @@
+"""Providers package - implement your own provider by extending BaseProvider.
+
+Concrete adapters (e.g. ``NvidiaNimProvider``) live in subpackages; import them
+from ``providers.nvidia_nim`` etc. to avoid loading every adapter when the
+``providers`` package is imported.
+"""
+
+from .base import BaseProvider, ProviderConfig
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    InvalidRequestError,
+    ModelListResponseError,
+    OverloadedError,
+    ProviderError,
+    RateLimitError,
+    UnknownProviderTypeError,
+)
+
+__all__ = [
+    "APIError",
+    "AuthenticationError",
+    "BaseProvider",
+    "InvalidRequestError",
+    "ModelListResponseError",
+    "OverloadedError",
+    "ProviderConfig",
+    "ProviderError",
+    "RateLimitError",
+    "UnknownProviderTypeError",
+]

providers/base.py

@@ -0,0 +1,152 @@
+"""Base provider interface - extend this to implement your own provider."""
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+from typing import Any
+
+from pydantic import BaseModel
+
+from config.constants import HTTP_CONNECT_TIMEOUT_DEFAULT
+from providers.model_listing import ProviderModelInfo, model_infos_from_ids
+
+
+class ProviderConfig(BaseModel):
+    """Configuration for a provider.
+
+    Base fields apply to all providers. Provider-specific parameters
+    (e.g. NIM temperature, top_p) are passed by the provider constructor.
+    """
+
+    api_key: str
+    base_url: str | None = None
+    rate_limit: int | None = None
+    rate_window: int = 60
+    max_concurrency: int = 5
+    http_read_timeout: float = 300.0
+    http_write_timeout: float = 10.0
+    http_connect_timeout: float = HTTP_CONNECT_TIMEOUT_DEFAULT
+    enable_thinking: bool = True
+    proxy: str = ""
+    log_raw_sse_events: bool = False
+    log_api_error_tracebacks: bool = False
+
+
+class BaseProvider(ABC):
+    """Base class for all providers. Extend this to add your own."""
+
+    def __init__(self, config: ProviderConfig):
+        self._config = config
+
+    def _is_thinking_enabled(
+        self, request: Any, thinking_enabled: bool | None = None
+    ) -> bool:
+        """Return whether thinking should be enabled for this request."""
+        thinking = getattr(request, "thinking", None)
+        config_enabled = (
+            self._config.enable_thinking
+            if thinking_enabled is None
+            else thinking_enabled
+        )
+        request_enabled = True
+        if thinking is not None:
+            thinking_type = (
+                thinking.get("type")
+                if isinstance(thinking, dict)
+                else getattr(thinking, "type", None)
+            )
+            if isinstance(thinking, dict):
+                enabled = thinking.get("enabled")
+                enabled_supplied = "enabled" in thinking
+            else:
+                enabled = getattr(thinking, "enabled", None)
+                fields_set = getattr(thinking, "model_fields_set", None)
+                enabled_supplied = (
+                    "enabled" in fields_set
+                    if isinstance(fields_set, set | frozenset)
+                    else enabled is not None
+                )
+            if enabled_supplied and enabled is not None:
+                request_enabled = bool(enabled)
+            if thinking_type == "disabled":
+                request_enabled = False
+        return config_enabled and request_enabled
+
+    def preflight_stream(
+        self, request: Any, *, thinking_enabled: bool | None = None
+    ) -> None:
+        """Eagerly validate/build the upstream request before opening an SSE stream.
+
+        Subclasses with ``_build_request_body`` (OpenAI and native) raise
+        :class:`providers.exceptions.InvalidRequestError` on conversion failures.
+        """
+        build = getattr(self, "_build_request_body", None)
+        if build is None:
+            return
+        build(request, thinking_enabled=thinking_enabled)
+
+    def _log_stream_transport_error(
+        self,
+        tag: str,
+        req_tag: str,
+        error: Exception,
+        *,
+        request_id: str | None = None,
+    ) -> None:
+        """Log streaming transport failures (metadata-only unless verbose is enabled)."""
+        from loguru import logger
+
+        from core.trace import trace_event
+
+        response = getattr(error, "response", None)
+        http_status = (
+            getattr(response, "status_code", None) if response is not None else None
+        )
+        trace_event(
+            stage="provider",
+            event="provider.response.transport_error",
+            source="provider",
+            provider=tag,
+            request_id=request_id,
+            exc_type=type(error).__name__,
+            http_status=http_status,
+        )
+
+        if self._config.log_api_error_tracebacks:
+            logger.error(
+                "{}_ERROR:{} {}: {}", tag, req_tag, type(error).__name__, error
+            )
+            return
+        logger.error(
+            "{}_ERROR:{} exc_type={} http_status={}",
+            tag,
+            req_tag,
+            type(error).__name__,
+            http_status,
+        )
+
+    @abstractmethod
+    async def cleanup(self) -> None:
+        """Release any resources held by this provider."""
+
+    @abstractmethod
+    async def list_model_ids(self) -> frozenset[str]:
+        """Return the model ids currently advertised by this provider."""
+
+    async def list_model_infos(self) -> frozenset[ProviderModelInfo]:
+        """Return advertised model ids with optional provider capability metadata."""
+        return model_infos_from_ids(await self.list_model_ids())
+
+    @abstractmethod
+    async def stream_response(
+        self,
+        request: Any,
+        input_tokens: int = 0,
+        *,
+        request_id: str | None = None,
+        thinking_enabled: bool | None = None,
+    ) -> AsyncIterator[str]:
+        """Stream response in Anthropic SSE format."""
+        # Typing: abstract async generators need a yield for AsyncIterator[str]
+        # inference; this branch is never executed.
+        if False:
+            yield ""

providers/cerebras/__init__.py

@@ -0,0 +1,7 @@
+"""Cerebras Inference (OpenAI-compatible) adapter."""
+
+from providers.defaults import CEREBRAS_DEFAULT_BASE
+
+from .client import CerebrasProvider
+
+__all__ = ["CEREBRAS_DEFAULT_BASE", "CerebrasProvider"]

providers/cerebras/client.py

@@ -0,0 +1,31 @@
+"""Cerebras Inference provider (OpenAI-compatible chat completions)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from providers.base import ProviderConfig
+from providers.defaults import CEREBRAS_DEFAULT_BASE
+from providers.transports.openai_chat import OpenAIChatTransport
+
+from .request import build_request_body
+
+
+class CerebrasProvider(OpenAIChatTransport):
+    """Cerebras API at ``https://api.cerebras.ai/v1/chat/completions``."""
+
+    def __init__(self, config: ProviderConfig):
+        super().__init__(
+            config,
+            provider_name="CEREBRAS",
+            base_url=config.base_url or CEREBRAS_DEFAULT_BASE,
+            api_key=config.api_key,
+        )
+
+    def _build_request_body(
+        self, request: Any, thinking_enabled: bool | None = None
+    ) -> dict:
+        return build_request_body(
+            request,
+            thinking_enabled=self._is_thinking_enabled(request, thinking_enabled),
+        )

providers/cerebras/request.py

@@ -0,0 +1,55 @@
+"""Request builder for Cerebras Inference (OpenAI-compatible chat completions).
+
+Docs: https://inference-docs.cerebras.ai/resources/openai — use ``max_completion_tokens``
+in API examples; non-standard fields via ``extra_body`` with the OpenAI client.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from loguru import logger
+
+from core.anthropic import ReasoningReplayMode, build_base_request_body
+from core.anthropic.conversion import OpenAIConversionError
+from providers.exceptions import InvalidRequestError
+
+
+def _normalize_max_completion_tokens(body: dict[str, Any]) -> None:
+    if "max_completion_tokens" in body:
+        body.pop("max_tokens", None)
+        return
+    if "max_tokens" in body and body["max_tokens"] is not None:
+        body["max_completion_tokens"] = body.pop("max_tokens")
+
+
+def build_request_body(request_data: Any, *, thinking_enabled: bool) -> dict:
+    """Build OpenAI-format request body from an Anthropic request for Cerebras."""
+    logger.debug(
+        "CEREBRAS_REQUEST: conversion start model={} msgs={}",
+        getattr(request_data, "model", "?"),
+        len(getattr(request_data, "messages", [])),
+    )
+    try:
+        body = build_base_request_body(
+            request_data,
+            reasoning_replay=ReasoningReplayMode.REASONING_CONTENT
+            if thinking_enabled
+            else ReasoningReplayMode.DISABLED,
+        )
+    except OpenAIConversionError as exc:
+        raise InvalidRequestError(str(exc)) from exc
+
+    request_extra = getattr(request_data, "extra_body", None)
+    if isinstance(request_extra, dict) and request_extra:
+        body["extra_body"] = dict(request_extra)
+
+    _normalize_max_completion_tokens(body)
+
+    logger.debug(
+        "CEREBRAS_REQUEST: conversion done model={} msgs={} tools={}",
+        body.get("model"),
+        len(body.get("messages", [])),
+        len(body.get("tools", [])),
+    )
+    return body

providers/codestral/__init__.py

@@ -0,0 +1,7 @@
+"""Mistral Codestral provider (codestral.mistral.ai) exports."""
+
+from providers.defaults import CODESTRAL_DEFAULT_BASE
+
+from .client import CodestralProvider
+
+__all__ = ["CODESTRAL_DEFAULT_BASE", "CodestralProvider"]

providers/codestral/client.py

@@ -0,0 +1,34 @@
+"""Mistral Codestral provider (OpenAI-compatible chat on codestral.mistral.ai)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from providers.base import ProviderConfig
+from providers.defaults import CODESTRAL_DEFAULT_BASE
+from providers.mistral.request import build_request_body
+from providers.transports.openai_chat import OpenAIChatTransport
+
+
+class CodestralProvider(OpenAIChatTransport):
+    """Codestral host using ``https://codestral.mistral.ai/v1/chat/completions``.
+
+    Uses a separate Codestral API key from La Plateforme (``MISTRAL_API_KEY``).
+    Request shaping matches Mistral La Plateforme (shared ``build_request_body``).
+    """
+
+    def __init__(self, config: ProviderConfig):
+        super().__init__(
+            config,
+            provider_name="CODESTRAL",
+            base_url=config.base_url or CODESTRAL_DEFAULT_BASE,
+            api_key=config.api_key,
+        )
+
+    def _build_request_body(
+        self, request: Any, thinking_enabled: bool | None = None
+    ) -> dict:
+        return build_request_body(
+            request,
+            thinking_enabled=self._is_thinking_enabled(request, thinking_enabled),
+        )

providers/deepseek/__init__.py

@@ -0,0 +1,11 @@
+"""DeepSeek provider exports."""
+
+from providers.defaults import DEEPSEEK_ANTHROPIC_DEFAULT_BASE, DEEPSEEK_DEFAULT_BASE
+
+from .client import DeepSeekProvider
+
+__all__ = [
+    "DEEPSEEK_ANTHROPIC_DEFAULT_BASE",
+    "DEEPSEEK_DEFAULT_BASE",
+    "DeepSeekProvider",
+]

providers/deepseek/client.py

@@ -0,0 +1,51 @@
+"""DeepSeek provider implementation (native Anthropic-compatible Messages)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from providers.base import ProviderConfig
+from providers.defaults import DEEPSEEK_ANTHROPIC_DEFAULT_BASE
+from providers.transports.anthropic_messages import AnthropicMessagesTransport
+
+from .request import build_request_body
+
+
+class DeepSeekProvider(AnthropicMessagesTransport):
+    """DeepSeek using ``https://api.deepseek.com/anthropic`` (Anthropic Messages API)."""
+
+    def __init__(self, config: ProviderConfig):
+        super().__init__(
+            config,
+            provider_name="DEEPSEEK",
+            default_base_url=DEEPSEEK_ANTHROPIC_DEFAULT_BASE,
+        )
+
+    def _build_request_body(
+        self, request: Any, thinking_enabled: bool | None = None
+    ) -> dict:
+        return build_request_body(
+            request,
+            thinking_enabled=self._is_thinking_enabled(request, thinking_enabled),
+        )
+
+    def _request_headers(self) -> dict[str, str]:
+        return {
+            "Accept": "text/event-stream",
+            "Content-Type": "application/json",
+            "x-api-key": self._api_key,
+        }
+
+    async def _send_model_list_request(self) -> httpx.Response:
+        """DeepSeek lists models from the OpenAI-format root, not /anthropic."""
+        url = str(
+            httpx.URL(self._base_url).copy_with(
+                path="/models", query=None, fragment=None
+            )
+        )
+        return await self._client.get(url, headers=self._model_list_headers())
+
+    def _model_list_headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self._api_key}"}