Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

refactor to reduce coupling

Alishahryar13b037932d7bd
diff --git a/api/dependencies.py b/api/dependencies.py
index 2d5acdf7..5ae85d90 100644
--- a/api/dependencies.py
+++ b/api/dependencies.py
@@ -1,14 +1,20 @@
"""Dependency injection for FastAPI."""
from typing import Optional
+from config.settings import Settings, get_settings as _get_settings, NVIDIA_NIM_BASE_URL
from providers.base import ProviderConfig
from providers.nvidia_nim import NvidiaNimProvider
-from config.settings import get_settings, NVIDIA_NIM_BASE_URL
+
# Global provider instance (singleton)
_provider: Optional[NvidiaNimProvider] = None
+def get_settings() -> Settings:
+ """Get application settings via dependency injection."""
+ return _get_settings()
+
+
def get_provider() -> NvidiaNimProvider:
"""Get or create the NvidiaNimProvider instance."""
global _provider
diff --git a/api/models.py b/api/models.py
index e8c4c4e0..5e4a3e88 100644
--- a/api/models.py
+++ b/api/models.py
@@ -6,6 +6,7 @@ from typing import List, Dict, Any, Optional, Union, Literal
from pydantic import BaseModel, field_validator, model_validator
from config.settings import get_settings
+from providers.model_utils import normalize_model_name
logger = logging.getLogger(__name__)
@@ -115,18 +116,10 @@ class MessagesRequest(BaseModel):
if self.original_model is None:
self.original_model = self.model
- # Strip provider prefixes
- clean_v = self.model
- for prefix in ["anthropic/", "openai/", "gemini/"]:
- if clean_v.startswith(prefix):
- clean_v = clean_v[len(prefix) :]
- break
-
- # Map all Claude models to the single configured model
- if any(
- name in clean_v.lower() for name in ["haiku", "sonnet", "opus", "claude"]
- ):
- self.model = settings.model
+ # Use centralized model normalization
+ normalized = normalize_model_name(self.model, settings.model)
+ if normalized != self.model:
+ self.model = normalized
if self.model != self.original_model:
logger.debug(f"MODEL MAPPING: '{self.original_model}' -> '{self.model}'")
@@ -147,17 +140,8 @@ class TokenCountRequest(BaseModel):
def validate_model_field(cls, v, info):
"""Map any Claude model name to the configured model."""
settings = get_settings()
- clean_v = v
- for prefix in ["anthropic/", "openai/", "gemini/"]:
- if clean_v.startswith(prefix):
- clean_v = clean_v[len(prefix) :]
- break
-
- if any(
- name in clean_v.lower() for name in ["haiku", "sonnet", "opus", "claude"]
- ):
- return settings.model
- return v
+ # Use centralized model normalization
+ return normalize_model_name(v, settings.model)
class TokenCountResponse(BaseModel):
diff --git a/api/request_utils.py b/api/request_utils.py
new file mode 100644
index 00000000..31f83e7a
--- /dev/null
+++ b/api/request_utils.py
@@ -0,0 +1,243 @@
+"""Request utility functions for API route handlers.
+
+This module contains optimization functions, quota detection, title generation detection,
+prefix detection, and token counting utilities.
+"""
+
+import json
+import logging
+from typing import List, Optional, Tuple, Union
+
+import tiktoken
+
+from .models import MessagesRequest
+
+logger = logging.getLogger(__name__)
+ENCODER = tiktoken.get_encoding("cl100k_base")
+
+
+def is_quota_check_request(request_data: MessagesRequest) -> bool:
+ """Check if this is a quota probe request.
+
+ Quota checks are typically simple requests with max_tokens=1
+ and a single message containing the word "quota".
+
+ Args:
+ request_data: The incoming request data
+
+ Returns:
+ True if this is a quota probe request
+ """
+ if (
+ request_data.max_tokens == 1
+ and len(request_data.messages) == 1
+ and request_data.messages[0].role == "user"
+ ):
+ content = request_data.messages[0].content
+ # Check string content
+ if isinstance(content, str) and "quota" in content.lower():
+ return True
+ # Check list content
+ elif isinstance(content, list):
+ for block in content:
+ if hasattr(block, "text") and "quota" in block.text.lower():
+ return True
+ return False
+
+
+def is_title_generation_request(request_data: MessagesRequest) -> bool:
+ """Check if this is a conversation title generation request.
+
+ Title generation requests typically contain the phrase
+ "write a 5-10 word title" in the user's message.
+
+ Args:
+ request_data: The incoming request data
+
+ Returns:
+ True if this is a title generation request
+ """
+ if len(request_data.messages) > 0 and request_data.messages[-1].role == "user":
+ content = request_data.messages[-1].content
+ # Check string content
+ target_phrase = "write a 5-10 word title"
+ if isinstance(content, str) and target_phrase in content.lower():
+ return True
+ # Check list content
+ elif isinstance(content, list):
+ for block in content:
+ if hasattr(block, "text") and target_phrase in block.text.lower():
+ return True
+ return False
+
+
+def extract_command_prefix(command: str) -> str:
+ """Extract the command prefix for fast prefix detection.
+
+ Parses a shell command safely, handling environment variables and
+ command injection attempts. Returns the command prefix suitable
+ for quick identification.
+
+ Args:
+ command: The command string to analyze
+
+ Returns:
+ Command prefix (e.g., "git", "git commit", "npm install")
+ or "none" if no valid command found
+ """
+ import shlex
+
+ # Quick check for command injection patterns
+ if "`" in command or "$(" in command:
+ return "command_injection_detected"
+
+ try:
+ parts = shlex.split(command)
+ if not parts:
+ return "none"
+
+ # Handle environment variable prefixes (e.g., KEY=value command)
+ env_prefix = []
+ cmd_start = 0
+ for i, part in enumerate(parts):
+ if "=" in part and not part.startswith("-"):
+ env_prefix.append(part)
+ cmd_start = i + 1
+ else:
+ break
+
+ if cmd_start >= len(parts):
+ return "none"
+
+ cmd_parts = parts[cmd_start:]
+ if not cmd_parts:
+ return "none"
+
+ first_word = cmd_parts[0]
+ two_word_commands = {
+ "git",
+ "npm",
+ "docker",
+ "kubectl",
+ "cargo",
+ "go",
+ "pip",
+ "yarn",
+ }
+
+ # For compound commands, include the subcommand (e.g., "git commit")
+ if first_word in two_word_commands and len(cmd_parts) > 1:
+ second_word = cmd_parts[1]
+ if not second_word.startswith("-"):
+ return f"{first_word} {second_word}"
+ return first_word
+ return first_word if not env_prefix else " ".join(env_prefix) + " " + first_word
+
+ except ValueError:
+ # Fall back to simple split if shlex fails
+ return command.split()[0] if command.split() else "none"
+
+
+def is_prefix_detection_request(request_data: MessagesRequest) -> Tuple[bool, str]:
+ """Check if this is a fast prefix detection request.
+
+ Prefix detection requests contain a policy_spec block and
+ a Command: section for extracting shell command prefixes.
+
+ Args:
+ request_data: The incoming request data
+
+ Returns:
+ Tuple of (is_prefix_request, command_string)
+ """
+ if len(request_data.messages) != 1 or request_data.messages[0].role != "user":
+ return False, ""
+
+ msg = request_data.messages[0]
+ content = ""
+ if isinstance(msg.content, str):
+ content = msg.content
+ elif isinstance(msg.content, list):
+ for block in msg.content:
+ if hasattr(block, "text"):
+ content += block.text
+
+ if "<policy_spec>" in content and "Command:" in content:
+ try:
+ cmd_start = content.rfind("Command:") + len("Command:")
+ return True, content[cmd_start:].strip()
+ except Exception:
+ pass
+
+ return False, ""
+
+
+def get_token_count(
+ messages: List,
+ system: Optional[Union[str, List]] = None,
+ tools: Optional[List] = None,
+) -> int:
+ """Estimate token count for a request.
+
+ Uses tiktoken cl100k_base encoding to estimate token usage.
+ Includes system prompt, messages, tools, and per-message overhead.
+
+ Args:
+ messages: List of message objects with content
+ system: Optional system prompt (str or list of blocks)
+ tools: Optional list of tool definitions
+
+ Returns:
+ Estimated total token count
+ """
+ total_tokens = 0
+
+ # Count system prompt tokens
+ if system:
+ if isinstance(system, str):
+ total_tokens += len(ENCODER.encode(system))
+ elif isinstance(system, list):
+ for block in system:
+ if hasattr(block, "text"):
+ total_tokens += len(ENCODER.encode(block.text))
+
+ # Count message tokens
+ for msg in messages:
+ if isinstance(msg.content, str):
+ total_tokens += len(ENCODER.encode(msg.content))
+ elif isinstance(msg.content, list):
+ for block in msg.content:
+ b_type = getattr(block, "type", None)
+
+ if b_type == "text":
+ total_tokens += len(ENCODER.encode(getattr(block, "text", "")))
+ elif b_type == "thinking":
+ total_tokens += len(ENCODER.encode(getattr(block, "thinking", "")))
+ elif b_type == "tool_use":
+ name = getattr(block, "name", "")
+ inp = getattr(block, "input", {})
+ total_tokens += len(ENCODER.encode(name))
+ total_tokens += len(ENCODER.encode(json.dumps(inp)))
+ total_tokens += 10 # Tool use overhead
+ elif b_type == "tool_result":
+ content = getattr(block, "content", "")
+ if isinstance(content, str):
+ total_tokens += len(ENCODER.encode(content))
+ else:
+ total_tokens += len(ENCODER.encode(json.dumps(content)))
+ total_tokens += 5 # Tool result overhead
+
+ # Count tool definition tokens
+ if tools:
+ for tool in tools:
+ tool_str = (
+ tool.name + (tool.description or "") + json.dumps(tool.input_schema)
+ )
+ total_tokens += len(ENCODER.encode(tool_str))
+
+ # Add per-message overhead
+ total_tokens += len(messages) * 3
+ if tools:
+ total_tokens += len(tools) * 5
+
+ return max(1, total_tokens)
diff --git a/api/routes.py b/api/routes.py
index 354a062c..900848c1 100644
--- a/api/routes.py
+++ b/api/routes.py
@@ -4,7 +4,6 @@ import json
import logging
import uuid
-import tiktoken
from fastapi import APIRouter, Request, Depends, HTTPException
from fastapi.responses import StreamingResponse
@@ -12,189 +11,27 @@ from .models import (
MessagesRequest,
MessagesResponse,
TokenCountRequest,
- MessagesResponse,
- TokenCountRequest,
TokenCountResponse,
Usage,
)
-from .dependencies import get_provider
+from .dependencies import get_provider, get_settings
+from .request_utils import (
+ is_quota_check_request,
+ is_title_generation_request,
+ is_prefix_detection_request,
+ extract_command_prefix,
+ get_token_count,
+)
+from config.settings import Settings
from providers.nvidia_nim import NvidiaNimProvider
from providers.exceptions import ProviderError
from providers.logging_utils import log_request_compact
-from config.settings import get_settings
logger = logging.getLogger(__name__)
-ENCODER = tiktoken.get_encoding("cl100k_base")
router = APIRouter()
-# =============================================================================
-# Helper Functions
-# =============================================================================
-
-
-def is_quota_check_request(request_data: MessagesRequest) -> bool:
- """Check if this is a quota probe request."""
- if (
- request_data.max_tokens == 1
- and len(request_data.messages) == 1
- and request_data.messages[0].role == "user"
- ):
- content = request_data.messages[0].content
- # Check string content
- if isinstance(content, str) and "quota" in content.lower():
- return True
- # Check list content
- elif isinstance(content, list):
- for block in content:
- if hasattr(block, "text") and "quota" in block.text.lower():
- return True
- return False
-
-
-def is_title_generation_request(request_data: MessagesRequest) -> bool:
- """Check if this is a conversation title generation request."""
- if len(request_data.messages) > 0 and request_data.messages[-1].role == "user":
- content = request_data.messages[-1].content
- # Check string content
- target_phrase = "write a 5-10 word title"
- if isinstance(content, str) and target_phrase in content.lower():
- return True
- # Check list content
- elif isinstance(content, list):
- for block in content:
- if hasattr(block, "text") and target_phrase in block.text.lower():
- return True
- return False
-
-
-def extract_command_prefix(command: str) -> str:
- """Extract the command prefix for fast prefix detection."""
- import shlex
-
- if "`" in command or "$(" in command:
- return "command_injection_detected"
-
- try:
- parts = shlex.split(command)
- if not parts:
- return "none"
-
- env_prefix = []
- cmd_start = 0
- for i, part in enumerate(parts):
- if "=" in part and not part.startswith("-"):
- env_prefix.append(part)
- cmd_start = i + 1
- else:
- break
-
- if cmd_start >= len(parts):
- return "none"
-
- cmd_parts = parts[cmd_start:]
- if not cmd_parts:
- return "none"
-
- first_word = cmd_parts[0]
- two_word_commands = {
- "git",
- "npm",
- "docker",
- "kubectl",
- "cargo",
- "go",
- "pip",
- "yarn",
- }
-
- if first_word in two_word_commands and len(cmd_parts) > 1:
- second_word = cmd_parts[1]
- if not second_word.startswith("-"):
- return f"{first_word} {second_word}"
- return first_word
- return first_word if not env_prefix else " ".join(env_prefix) + " " + first_word
-
- except ValueError:
- return command.split()[0] if command.split() else "none"
-
-
-def is_prefix_detection_request(request_data: MessagesRequest) -> tuple[bool, str]:
- """Check if this is a fast prefix detection request."""
- if len(request_data.messages) != 1 or request_data.messages[0].role != "user":
- return False, ""
-
- msg = request_data.messages[0]
- content = ""
- if isinstance(msg.content, str):
- content = msg.content
- elif isinstance(msg.content, list):
- for block in msg.content:
- if hasattr(block, "text"):
- content += block.text
-
- if "<policy_spec>" in content and "Command:" in content:
- try:
- cmd_start = content.rfind("Command:") + len("Command:")
- return True, content[cmd_start:].strip()
- except Exception:
- pass
-
- return False, ""
-
-
-def get_token_count(messages, system=None, tools=None) -> int:
- """Estimate token count for a request."""
- total_tokens = 0
-
- if system:
- if isinstance(system, str):
- total_tokens += len(ENCODER.encode(system))
- elif isinstance(system, list):
- for block in system:
- if hasattr(block, "text"):
- total_tokens += len(ENCODER.encode(block.text))
-
- for msg in messages:
- if isinstance(msg.content, str):
- total_tokens += len(ENCODER.encode(msg.content))
- elif isinstance(msg.content, list):
- for block in msg.content:
- b_type = getattr(block, "type", None)
-
- if b_type == "text":
- total_tokens += len(ENCODER.encode(getattr(block, "text", "")))
- elif b_type == "thinking":
- total_tokens += len(ENCODER.encode(getattr(block, "thinking", "")))
- elif b_type == "tool_use":
- name = getattr(block, "name", "")
- inp = getattr(block, "input", {})
- total_tokens += len(ENCODER.encode(name))
- total_tokens += len(ENCODER.encode(json.dumps(inp)))
- total_tokens += 10
- elif b_type == "tool_result":
- content = getattr(block, "content", "")
- if isinstance(content, str):
- total_tokens += len(ENCODER.encode(content))
- else:
- total_tokens += len(ENCODER.encode(json.dumps(content)))
- total_tokens += 5
-
- if tools:
- for tool in tools:
- tool_str = (
- tool.name + (tool.description or "") + json.dumps(tool.input_schema)
- )
- total_tokens += len(ENCODER.encode(tool_str))
-
- total_tokens += len(messages) * 3
- if tools:
- total_tokens += len(tools) * 5
-
- return max(1, total_tokens)
-
-
# =============================================================================
# Routes
# =============================================================================
@@ -205,9 +42,9 @@ async def create_message(
request_data: MessagesRequest,
raw_request: Request,
provider: NvidiaNimProvider = Depends(get_provider),
+ settings: Settings = Depends(get_settings),
):
"""Create a message (streaming or non-streaming)."""
- settings = get_settings()
try:
if settings.fast_prefix_detection:
@@ -290,9 +127,8 @@ async def count_tokens(request_data: TokenCountRequest):
@router.get("/")
-async def root():
+async def root(settings: Settings = Depends(get_settings)):
"""Root endpoint."""
- settings = get_settings()
return {
"status": "ok",
"provider": "nvidia_nim",
diff --git a/messaging/__init__.py b/messaging/__init__.py
index 5f6f5c19..9499434e 100644
--- a/messaging/__init__.py
+++ b/messaging/__init__.py
@@ -1,13 +1,17 @@
"""Platform-agnostic messaging layer."""
-from .base import MessagingPlatform
+from .base import MessagingPlatform, SessionManagerInterface, CLISession
from .models import IncomingMessage, OutgoingMessage
from .handler import ClaudeMessageHandler
from .session import SessionStore
-from .tree_queue import TreeQueueManager, MessageTree, MessageNode, MessageState
+from .tree_data import MessageTree, MessageNode, MessageState
+from .tree_queue import TreeQueueManager
+from .event_parser import parse_cli_event
__all__ = [
"MessagingPlatform",
+ "SessionManagerInterface",
+ "CLISession",
"IncomingMessage",
"OutgoingMessage",
"ClaudeMessageHandler",
@@ -16,4 +20,5 @@ __all__ = [
"MessageTree",
"MessageNode",
"MessageState",
+ "parse_cli_event",
]
diff --git a/messaging/base.py b/messaging/base.py
index 00b01bc2..0981c0b2 100644
--- a/messaging/base.py
+++ b/messaging/base.py
@@ -1,10 +1,56 @@
"""Abstract base class for messaging platforms."""
from abc import ABC, abstractmethod
-from typing import Callable, Awaitable, Optional, Any
+from typing import Callable, Awaitable, Optional, Any, Protocol, Tuple, runtime_checkable
from .models import IncomingMessage
+class CLISession(ABC):
+ """Abstract base for CLI session - avoid circular import from cli package."""
+
+ @abstractmethod
+ async def start_task(self, prompt: str, session_id: Optional[str] = None):
+ """Start a task in the CLI session."""
+ pass
+
+ @property
+ @abstractmethod
+ def is_busy(self) -> bool:
+ """Check if session is busy."""
+ pass
+
+
+@runtime_checkable
+class SessionManagerInterface(Protocol):
+ """
+ Protocol for session managers to avoid tight coupling with cli package.
+
+ Implementations: CLISessionManager
+ """
+
+ async def get_or_create_session(
+ self, session_id: Optional[str] = None
+ ) -> Tuple[CLISession, str, bool]:
+ """
+ Get an existing session or create a new one.
+
+ Returns: Tuple of (session, session_id, is_new_session)
+ """
+ ...
+
+ async def register_real_session_id(self, temp_id: str, real_session_id: str) -> bool:
+ """Register the real session ID from CLI output."""
+ ...
+
+ async def stop_all(self) -> None:
+ """Stop all sessions."""
+ ...
+
+ def get_stats(self) -> dict:
+ """Get session statistics."""
+ ...
+
+
class MessagingPlatform(ABC):
"""
Base class for all messaging platform adapters.
diff --git a/messaging/event_parser.py b/messaging/event_parser.py
new file mode 100644
index 00000000..2b0da0b7
--- /dev/null
+++ b/messaging/event_parser.py
@@ -0,0 +1,124 @@
+"""CLI event parser for Claude Code CLI output.
+
+Extracted from cli.parser to avoid tight coupling between messaging and cli packages.
+"""
+
+import logging
+from typing import Dict, List
+
+logger = logging.getLogger(__name__)
+
+
+def parse_cli_event(event: Dict) -> List[Dict]:
+ """
+ Parse a CLI event and return a structured result.
+
+ Args:
+ event: Raw event dictionary from CLI
+
+ Returns:
+ List of parsed event dicts. Empty list if not recognized.
+ """
+ if not isinstance(event, dict):
+ return []
+
+ etype = event.get("type")
+ results = []
+
+ # 1. Handle full messages (assistant or result)
+ msg_obj = None
+ if etype == "assistant":
+ msg_obj = event.get("message")
+ elif etype == "result":
+ res = event.get("result")
+ if isinstance(res, dict):
+ msg_obj = res.get("message")
+ if not msg_obj:
+ msg_obj = event.get("message")
+
+ if msg_obj and isinstance(msg_obj, dict):
+ content = msg_obj.get("content", [])
+ if isinstance(content, list):
+ parts = []
+ thinking_parts = []
+ tool_calls = []
+ for c in content:
+ if not isinstance(c, dict):
+ continue
+ ctype = c.get("type")
+ if ctype == "text":
+ parts.append(c.get("text", ""))
+ elif ctype == "thinking":
+ thinking_parts.append(c.get("thinking", ""))
+ elif ctype == "tool_use":
+ tool_calls.append(c)
+
+ # Prioritize thinking first
+ if thinking_parts:
+ results.append(
+ {"type": "thinking", "text": "\n".join(thinking_parts)}
+ )
+
+ # Then tools or subagents
+ if tool_calls:
+ # Check for subagents (Task tool)
+ subagents = [
+ t.get("input", {}).get("description", "Subagent")
+ for t in tool_calls
+ if t.get("name") == "Task"
+ ]
+ if subagents:
+ results.append({"type": "subagent_start", "tasks": subagents})
+ else:
+ results.append({"type": "tool_start", "tools": tool_calls})
+
+ # Then text content if any
+ if parts:
+ results.append({"type": "content", "text": "".join(parts)})
+
+ if results:
+ return results
+
+ # 2. Handle streaming deltas
+ if etype == "content_block_delta":
+ delta = event.get("delta", {})
+ if isinstance(delta, dict):
+ if delta.get("type") == "text_delta":
+ return [{"type": "content", "text": delta.get("text", "")}]
+ if delta.get("type") == "thinking_delta":
+ return [{"type": "thinking", "text": delta.get("thinking", "")}]
+
+ # 3. Handle tool usage start
+ if etype == "content_block_start":
+ block = event.get("content_block", {})
+ if isinstance(block, dict) and block.get("type") == "tool_use":
+ if block.get("name") == "Task":
+ desc = block.get("input", {}).get("description", "Subagent")
+ return [{"type": "subagent_start", "tasks": [desc]}]
+ return [{"type": "tool_start", "tools": [block]}]
+
+ # 4. Handle errors and exit
+ if etype == "error":
+ err = event.get("error")
+ msg = err.get("message") if isinstance(err, dict) else str(err)
+ logger.info(f"CLI_PARSER: Parsed error event: {msg[:100]}")
+ return [{"type": "error", "message": msg}]
+ elif etype == "exit":
+ code = event.get("code", 0)
+ stderr = event.get("stderr")
+ if code == 0:
+ logger.debug(f"CLI_PARSER: Successful exit (code={code})")
+ return [{"type": "complete", "status": "success"}]
+ else:
+ # Non-zero exit is an error
+ error_msg = stderr if stderr else f"Process exited with code {code}"
+ logger.warning(f"CLI_PARSER: Error exit (code={code}): {error_msg[:100]}")
+ return [
+ {"type": "error", "message": error_msg},
+ {"type": "complete", "status": "failed"},
+ ]
+
+ # Log unrecognized events for debugging
+ if etype:
+ logger.debug(f"CLI_PARSER: Unrecognized event type: {etype}")
+ return []
diff --git a/messaging/handler.py b/messaging/handler.py
index d36d7beb..e36c7183 100644
--- a/messaging/handler.py
+++ b/messaging/handler.py
@@ -11,11 +11,11 @@ import asyncio
import logging
from typing import Optional, TYPE_CHECKING
-from .base import MessagingPlatform
+from .base import MessagingPlatform, SessionManagerInterface, CLISession
from .models import IncomingMessage
from .session import SessionStore
from .tree_queue import TreeQueueManager, MessageNode, MessageState
-from cli import CLISessionManager, CLIParser
+from .event_parser import parse_cli_event
if TYPE_CHECKING:
pass
@@ -37,7 +37,7 @@ class ClaudeMessageHandler:
def __init__(
self,
platform: MessagingPlatform,
- cli_manager: CLISessionManager,
+ cli_manager: SessionManagerInterface,
session_store: SessionStore,
):
self.platform = platform
@@ -251,7 +251,7 @@ class ClaudeMessageHandler:
temp_session_id = None
continue
- parsed_list = CLIParser.parse_event(event_data)
+ parsed_list = parse_cli_event(event_data)
logger.debug(f"HANDLER: Parsed {len(parsed_list)} events from CLI")
for parsed in parsed_list:
diff --git a/messaging/tree_data.py b/messaging/tree_data.py
new file mode 100644
index 00000000..a51d6faf
--- /dev/null
+++ b/messaging/tree_data.py
@@ -0,0 +1,303 @@
+"""Tree data structures for message queue.
+
+Contains MessageState, MessageNode, and MessageTree classes.
+"""
+
+import asyncio
+import logging
+from enum import Enum
+from datetime import datetime
+from typing import Dict, Optional, List, Any
+from dataclasses import dataclass, field
+
+from .models import IncomingMessage
+
+logger = logging.getLogger(__name__)
+
+
+class MessageState(Enum):
+ """State of a message node in the tree."""
+
+ PENDING = "pending" # Queued, waiting to be processed
+ IN_PROGRESS = "in_progress" # Currently being processed by Claude
+ COMPLETED = "completed" # Processing finished successfully
+ ERROR = "error" # Processing failed
+
+
+@dataclass
+class MessageNode:
+ """
+ A node in the message tree.
+
+ Each node represents a single message and tracks:
+ - Its relationship to parent/children
+ - Its processing state
+ - Claude session information
+ """
+
+ node_id: str # Unique ID (typically message_id)
+ incoming: IncomingMessage # The original message
+ status_message_id: str # Bot's status message ID
+ state: MessageState = MessageState.PENDING
+ parent_id: Optional[str] = None # Parent node ID (None for root)
+ session_id: Optional[str] = None # Claude session ID (forked from parent)
+ children_ids: List[str] = field(default_factory=list)
+ created_at: datetime = field(default_factory=datetime.utcnow)
+ completed_at: Optional[datetime] = None
+ error_message: Optional[str] = None
+ context: Any = None # Additional context if needed
+
+ def to_dict(self) -> dict:
+ """Convert to dictionary for JSON serialization."""
+ return {
+ "node_id": self.node_id,
+ "incoming": {
+ "text": self.incoming.text,
+ "chat_id": self.incoming.chat_id,
+ "user_id": self.incoming.user_id,
+ "message_id": self.incoming.message_id,
+ "platform": self.incoming.platform,
+ "reply_to_message_id": self.incoming.reply_to_message_id,
+ "username": self.incoming.username,
+ },
+ "status_message_id": self.status_message_id,
+ "state": self.state.value,
+ "parent_id": self.parent_id,
+ "session_id": self.session_id,
+ "children_ids": self.children_ids,
+ "created_at": self.created_at.isoformat(),
+ "completed_at": self.completed_at.isoformat()
+ if self.completed_at
+ else None,
+ "error_message": self.error_message,
+ }
+
+ @classmethod
+ def from_dict(cls, data: dict) -> "MessageNode":
+ """Create from dictionary (JSON deserialization)."""
+ incoming_data = data["incoming"]
+ incoming = IncomingMessage(
+ text=incoming_data["text"],
+ chat_id=incoming_data["chat_id"],
+ user_id=incoming_data["user_id"],
+ message_id=incoming_data["message_id"],
+ platform=incoming_data["platform"],
+ reply_to_message_id=incoming_data.get("reply_to_message_id"),
+ username=incoming_data.get("username"),
+ )
+ return cls(
+ node_id=data["node_id"],
+ incoming=incoming,
+ status_message_id=data["status_message_id"],
+ state=MessageState(data["state"]),
+ parent_id=data.get("parent_id"),
+ session_id=data.get("session_id"),
+ children_ids=data.get("children_ids", []),
+ created_at=datetime.fromisoformat(data["created_at"]),
+ completed_at=datetime.fromisoformat(data["completed_at"])
+ if data.get("completed_at")
+ else None,
+ error_message=data.get("error_message"),
+ )
+
+
+class MessageTree:
+ """
+ A tree of message nodes with queue functionality.
+
+ Provides:
+ - O(1) node lookup via hashmap
+ - Per-tree message queue
+ - Thread-safe operations via asyncio.Lock
+ """
+
+ def __init__(self, root_node: MessageNode):
+ """
+ Initialize tree with a root node.
+
+ Args:
+ root_node: The root message node
+ """
+ self.root_id = root_node.node_id
+ self._nodes: Dict[str, MessageNode] = {root_node.node_id: root_node}
+ self._queue: asyncio.Queue[str] = asyncio.Queue()
+ self._lock = asyncio.Lock()
+ self._is_processing = False
+ self._current_node_id: Optional[str] = None
+ self._current_task: Optional[asyncio.Task] = None
+
+ logger.debug(f"Created MessageTree with root {self.root_id}")
+
+ @property
+ def is_processing(self) -> bool:
+ """Check if tree is currently processing a message."""
+ return self._is_processing
+
+ async def add_node(
+ self,
+ node_id: str,
+ incoming: IncomingMessage,
+ status_message_id: str,
+ parent_id: str,
+ ) -> MessageNode:
+ """
+ Add a child node to the tree.
+
+ Args:
+ node_id: Unique ID for the new node
+ incoming: The incoming message
+ status_message_id: Bot's status message ID
+ parent_id: Parent node ID
+
+ Returns:
+ The created MessageNode
+ """
+ async with self._lock:
+ if parent_id not in self._nodes:
+ raise ValueError(f"Parent node {parent_id} not found in tree")
+
+ node = MessageNode(
+ node_id=node_id,
+ incoming=incoming,
+ status_message_id=status_message_id,
+ parent_id=parent_id,
+ state=MessageState.PENDING,
+ )
+
+ self._nodes[node_id] = node
+ self._nodes[parent_id].children_ids.append(node_id)
+
+ logger.debug(f"Added node {node_id} as child of {parent_id}")
+ return node
+
+ def get_node(self, node_id: str) -> Optional[MessageNode]:
+ """Get a node by ID (O(1) lookup)."""
+ return self._nodes.get(node_id)
+
+ def get_root(self) -> MessageNode:
+ """Get the root node."""
+ return self._nodes[self.root_id]
+
+ def get_children(self, node_id: str) -> List[MessageNode]:
+ """Get all child nodes of a given node."""
+ node = self._nodes.get(node_id)
+ if not node:
+ return []
+ return [self._nodes[cid] for cid in node.children_ids if cid in self._nodes]
+
+ def get_parent(self, node_id: str) -> Optional[MessageNode]:
+ """Get the parent node."""
+ node = self._nodes.get(node_id)
+ if not node or not node.parent_id:
+ return None
+ return self._nodes.get(node.parent_id)
+
+ def get_parent_session_id(self, node_id: str) -> Optional[str]:
+ """
+ Get the parent's session ID for forking.
+
+ Returns None for root nodes.
+ """
+ parent = self.get_parent(node_id)
+ return parent.session_id if parent else None
+
+ async def update_state(
+ self,
+ node_id: str,
+ state: MessageState,
+ session_id: Optional[str] = None,
+ error_message: Optional[str] = None,
+ ) -> None:
+ """Update a node's state."""
+ async with self._lock:
+ node = self._nodes.get(node_id)
+ if not node:
+ logger.warning(f"Node {node_id} not found for state update")
+ return
+
+ node.state = state
+ if session_id:
+ node.session_id = session_id
+ if error_message:
+ node.error_message = error_message
+ if state in (MessageState.COMPLETED, MessageState.ERROR):
+ node.completed_at = datetime.utcnow()
+
+ logger.debug(f"Node {node_id} state -> {state.value}")
+
+ async def enqueue(self, node_id: str) -> int:
+ """
+ Add a node to the processing queue.
+
+ Returns:
+ Queue position (1-indexed)
+ """
+ async with self._lock:
+ await self._queue.put(node_id)
+ position = self._queue.qsize()
+ logger.debug(f"Enqueued node {node_id}, position {position}")
+ return position
+
+ async def dequeue(self) -> Optional[str]:
+ """
+ Get the next node ID from the queue.
+
+ Returns None if queue is empty.
+ """
+ try:
+ return self._queue.get_nowait()
+ except asyncio.QueueEmpty:
+ return None
+
+ def get_queue_size(self) -> int:
+ """Get number of messages waiting in queue."""
+ return self._queue.qsize()
+
+ def get_queue_position(self, node_id: str) -> int:
+ """
+ Get position of a node in the queue.
+
+ Returns 0 if not in queue, 1+ for queue position.
+ """
+ # Note: asyncio.Queue doesn't support direct iteration
+ # This is an approximation based on order
+ return 0 # TODO: Track positions separately if needed
+
+ def to_dict(self) -> dict:
+ """Serialize tree to dictionary."""
+ return {
+ "root_id": self.root_id,
+ "nodes": {nid: node.to_dict() for nid, node in self._nodes.items()},
+ }
+
+ @classmethod
+ def from_dict(cls, data: dict) -> "MessageTree":
+ """Deserialize tree from dictionary."""
+ root_id = data["root_id"]
+ nodes_data = data["nodes"]
+
+ # Create root node first
+ root_node = MessageNode.from_dict(nodes_data[root_id])
+ tree = cls(root_node)
+
+ # Add remaining nodes
+ for node_id, node_data in nodes_data.items():
+ if node_id != root_id:
+ tree._nodes[node_id] = MessageNode.from_dict(node_data)
+
+ return tree
+
+ def all_nodes(self) -> List[MessageNode]:
+ """Get all nodes in the tree."""
+ return list(self._nodes.values())
+
+ def has_node(self, node_id: str) -> bool:
+ """Check if a node exists in this tree."""
+ return node_id in self._nodes
+
+ def find_node_by_status_message(self, status_msg_id: str) -> Optional[MessageNode]:
+ """Find the node that has this status message ID."""
+ for node in self._nodes.values():
+ if node.status_message_id == status_msg_id:
+ return node
+ return None
diff --git a/messaging/tree_processor.py b/messaging/tree_processor.py
new file mode 100644
index 00000000..ca48b810
--- /dev/null
+++ b/messaging/tree_processor.py
@@ -0,0 +1,111 @@
+"""Async queue processor for message trees.
+
+Handles the async processing lifecycle of tree nodes.
+"""
+
+import asyncio
+import logging
+from typing import Callable, Awaitable
+
+from .tree_data import MessageTree, MessageNode, MessageState
+
+logger = logging.getLogger(__name__)
+
+
+class TreeQueueProcessor:
+ """
+ Handles async queue processing for a single tree.
+
+ Separates the async processing logic from the data management.
+ """
+
+ async def process_node(
+ self,
+ tree: MessageTree,
+ node: MessageNode,
+ processor: Callable[[str, MessageNode], Awaitable[None]],
+ ) -> None:
+ """Process a single node and then check the queue."""
+ try:
+ await processor(node.node_id, node)
+ except asyncio.CancelledError:
+ logger.info(f"Task for node {node.node_id} was cancelled")
+ raise
+ except Exception as e:
+ logger.error(f"Error processing node {node.node_id}: {e}")
+ await tree.update_state(
+ node.node_id, MessageState.ERROR, error_message=str(e)
+ )
+ finally:
+ tree._current_node_id = None
+ # Check if there are more messages in the queue
+ await self._process_next(tree, processor)
+
+ async def _process_next(
+ self,
+ tree: MessageTree,
+ processor: Callable[[str, MessageNode], Awaitable[None]],
+ ) -> None:
+ """Process the next message in queue, if any."""
+ async with tree._lock:
+ next_node_id = await tree.dequeue()
+
+ if not next_node_id:
+ # No more messages, mark tree as free
+ tree._is_processing = False
+ logger.debug(f"Tree {tree.root_id} queue empty, marking as free")
+ return
+
+ tree._current_node_id = next_node_id
+ logger.info(f"Processing next queued node {next_node_id}")
+
+ # Process next node (outside lock)
+ node = tree.get_node(next_node_id)
+ if node:
+ tree._current_task = asyncio.create_task(
+ self.process_node(tree, node, processor)
+ )
+
+ async def enqueue_and_start(
+ self,
+ tree: MessageTree,
+ node_id: str,
+ processor: Callable[[str, MessageNode], Awaitable[None]],
+ ) -> bool:
+ """
+ Enqueue a node or start processing immediately.
+
+ Args:
+ tree: The message tree
+ node_id: Node to process
+ processor: Async function to process the node
+
+ Returns:
+ True if queued, False if processing immediately
+ """
+ async with tree._lock:
+ if tree._is_processing:
+ # Tree is busy, queue the message
+ await tree._queue.put(node_id)
+ queue_size = tree._queue.qsize()
+ logger.info(f"Queued node {node_id}, position {queue_size}")
+ return True
+ else:
+ # Tree is free, start processing
+ tree._is_processing = True
+ tree._current_node_id = node_id
+
+ # Process outside the lock
+ node = tree.get_node(node_id)
+ if node:
+ tree._current_task = asyncio.create_task(
+ self.process_node(tree, node, processor)
+ )
+ return False
+
+ def cancel_current(self, tree: MessageTree) -> bool:
+ """Cancel the currently running task in a tree."""
+ if tree._current_task and not tree._current_task.done():
+ tree._current_task.cancel()
+ return True
+ return False
diff --git a/messaging/tree_queue.py b/messaging/tree_queue.py
index 0d36665b..68dc75db 100644
--- a/messaging/tree_queue.py
+++ b/messaging/tree_queue.py
@@ -1,329 +1,58 @@
-"""
-Tree-Based Message Queue Manager
-
-Implements a tree structure for message queuing where:
-- Each new message creates a root node
-- Replies become child nodes of the message being replied to
-- Each node has a state (PENDING, IN_PROGRESS, COMPLETED, ERROR)
-- Per-tree queue processes messages in order
-- Child nodes only access parent context (via session forking)
+"""Tree-Based Message Queue Manager - Refactored.
+
+Coordinates data access, async processing, and error handling.
+Uses TreeRepository for data, TreeQueueProcessor for async logic.
"""
import asyncio
import logging
-from enum import Enum
-from datetime import datetime
-from typing import Dict, Optional, List, Callable, Awaitable, Any
-from dataclasses import dataclass, field, asdict
+from typing import Callable, Awaitable, List, Optional
from .models import IncomingMessage
+from .tree_data import MessageState, MessageNode, MessageTree
+from .tree_repository import TreeRepository
+from .tree_processor import TreeQueueProcessor
+
+# Backward compatibility: re-export moved classes
+__all__ = [
+ "TreeQueueManager",
+ "MessageState",
+ "MessageNode",
+ "MessageTree",
+]
logger = logging.getLogger(__name__)
-class MessageState(Enum):
- """State of a message node in the tree."""
-
- PENDING = "pending" # Queued, waiting to be processed
- IN_PROGRESS = "in_progress" # Currently being processed by Claude
- COMPLETED = "completed" # Processing finished successfully
- ERROR = "error" # Processing failed
-
-
-@dataclass
-class MessageNode:
- """
- A node in the message tree.
-
- Each node represents a single message and tracks:
- - Its relationship to parent/children
- - Its processing state
- - Claude session information
- """
-
- node_id: str # Unique ID (typically message_id)
- incoming: IncomingMessage # The original message
- status_message_id: str # Bot's status message ID
- state: MessageState = MessageState.PENDING
- parent_id: Optional[str] = None # Parent node ID (None for root)
- session_id: Optional[str] = None # Claude session ID (forked from parent)
- children_ids: List[str] = field(default_factory=list)
- created_at: datetime = field(default_factory=datetime.utcnow)
- completed_at: Optional[datetime] = None
- error_message: Optional[str] = None
- context: Any = None # Additional context if needed
-
- def to_dict(self) -> dict:
- """Convert to dictionary for JSON serialization."""
- return {
- "node_id": self.node_id,
- "incoming": {
- "text": self.incoming.text,
- "chat_id": self.incoming.chat_id,
- "user_id": self.incoming.user_id,
- "message_id": self.incoming.message_id,
- "platform": self.incoming.platform,
- "reply_to_message_id": self.incoming.reply_to_message_id,
- "username": self.incoming.username,
- },
- "status_message_id": self.status_message_id,
- "state": self.state.value,
- "parent_id": self.parent_id,
- "session_id": self.session_id,
- "children_ids": self.children_ids,
- "created_at": self.created_at.isoformat(),
- "completed_at": self.completed_at.isoformat()
- if self.completed_at
- else None,
- "error_message": self.error_message,
- }
-
- @classmethod
- def from_dict(cls, data: dict) -> "MessageNode":
- """Create from dictionary (JSON deserialization)."""
- incoming_data = data["incoming"]
- incoming = IncomingMessage(
- text=incoming_data["text"],
- chat_id=incoming_data["chat_id"],
- user_id=incoming_data["user_id"],
- message_id=incoming_data["message_id"],
- platform=incoming_data["platform"],
- reply_to_message_id=incoming_data.get("reply_to_message_id"),
- username=incoming_data.get("username"),
- )
- return cls(
- node_id=data["node_id"],
- incoming=incoming,
- status_message_id=data["status_message_id"],
- state=MessageState(data["state"]),
- parent_id=data.get("parent_id"),
- session_id=data.get("session_id"),
- children_ids=data.get("children_ids", []),
- created_at=datetime.fromisoformat(data["created_at"]),
- completed_at=datetime.fromisoformat(data["completed_at"])
- if data.get("completed_at")
- else None,
- error_message=data.get("error_message"),
- )
-
-
-class MessageTree:
- """
- A tree of message nodes with queue functionality.
-
- Provides:
- - O(1) node lookup via hashmap
- - Per-tree message queue
- - Thread-safe operations via asyncio.Lock
- """
-
- def __init__(self, root_node: MessageNode):
- """
- Initialize tree with a root node.
-
- Args:
- root_node: The root message node
- """
- self.root_id = root_node.node_id
- self._nodes: Dict[str, MessageNode] = {root_node.node_id: root_node}
- self._queue: asyncio.Queue[str] = asyncio.Queue()
- self._lock = asyncio.Lock()
- self._is_processing = False
- self._current_node_id: Optional[str] = None
- self._current_task: Optional[asyncio.Task] = None
-
- logger.debug(f"Created MessageTree with root {self.root_id}")
-
- @property
- def is_processing(self) -> bool:
- """Check if tree is currently processing a message."""
- return self._is_processing
-
- async def add_node(
- self,
- node_id: str,
- incoming: IncomingMessage,
- status_message_id: str,
- parent_id: str,
- ) -> MessageNode:
- """
- Add a child node to the tree.
-
- Args:
- node_id: Unique ID for the new node
- incoming: The incoming message
- status_message_id: Bot's status message ID
- parent_id: Parent node ID
-
- Returns:
- The created MessageNode
- """
- async with self._lock:
- if parent_id not in self._nodes:
- raise ValueError(f"Parent node {parent_id} not found in tree")
-
- node = MessageNode(
- node_id=node_id,
- incoming=incoming,
- status_message_id=status_message_id,
- parent_id=parent_id,
- state=MessageState.PENDING,
- )
-
- self._nodes[node_id] = node
- self._nodes[parent_id].children_ids.append(node_id)
-
- logger.debug(f"Added node {node_id} as child of {parent_id}")
- return node
-
- def get_node(self, node_id: str) -> Optional[MessageNode]:
- """Get a node by ID (O(1) lookup)."""
- return self._nodes.get(node_id)
-
- def get_root(self) -> MessageNode:
- """Get the root node."""
- return self._nodes[self.root_id]
-
- def get_children(self, node_id: str) -> List[MessageNode]:
- """Get all child nodes of a given node."""
- node = self._nodes.get(node_id)
- if not node:
- return []
- return [self._nodes[cid] for cid in node.children_ids if cid in self._nodes]
-
- def get_parent(self, node_id: str) -> Optional[MessageNode]:
- """Get the parent node."""
- node = self._nodes.get(node_id)
- if not node or not node.parent_id:
- return None
- return self._nodes.get(node.parent_id)
-
- def get_parent_session_id(self, node_id: str) -> Optional[str]:
- """
- Get the parent's session ID for forking.
-
- Returns None for root nodes.
- """
- parent = self.get_parent(node_id)
- return parent.session_id if parent else None
-
- async def update_state(
- self,
- node_id: str,
- state: MessageState,
- session_id: Optional[str] = None,
- error_message: Optional[str] = None,
- ) -> None:
- """Update a node's state."""
- async with self._lock:
- node = self._nodes.get(node_id)
- if not node:
- logger.warning(f"Node {node_id} not found for state update")
- return
-
- node.state = state
- if session_id:
- node.session_id = session_id
- if error_message:
- node.error_message = error_message
- if state in (MessageState.COMPLETED, MessageState.ERROR):
- node.completed_at = datetime.utcnow()
-
- logger.debug(f"Node {node_id} state -> {state.value}")
-
- async def enqueue(self, node_id: str) -> int:
- """
- Add a node to the processing queue.
-
- Returns:
- Queue position (1-indexed)
- """
- async with self._lock:
- await self._queue.put(node_id)
- position = self._queue.qsize()
- logger.debug(f"Enqueued node {node_id}, position {position}")
- return position
-
- async def dequeue(self) -> Optional[str]:
- """
- Get the next node ID from the queue.
-
- Returns None if queue is empty.
- """
- try:
- return self._queue.get_nowait()
- except asyncio.QueueEmpty:
- return None
-
- def get_queue_size(self) -> int:
- """Get number of messages waiting in queue."""
- return self._queue.qsize()
-
- def get_queue_position(self, node_id: str) -> int:
- """
- Get position of a node in the queue.
-
- Returns 0 if not in queue, 1+ for queue position.
- """
- # Note: asyncio.Queue doesn't support direct iteration
- # This is an approximation based on order
- return 0 # TODO: Track positions separately if needed
-
- def to_dict(self) -> dict:
- """Serialize tree to dictionary."""
- return {
- "root_id": self.root_id,
- "nodes": {nid: node.to_dict() for nid, node in self._nodes.items()},
- }
-
- @classmethod
- def from_dict(cls, data: dict) -> "MessageTree":
- """Deserialize tree from dictionary."""
- root_id = data["root_id"]
- nodes_data = data["nodes"]
-
- # Create root node first
- root_node = MessageNode.from_dict(nodes_data[root_id])
- tree = cls(root_node)
-
- # Add remaining nodes
- for node_id, node_data in nodes_data.items():
- if node_id != root_id:
- tree._nodes[node_id] = MessageNode.from_dict(node_data)
-
- return tree
-
- def all_nodes(self) -> List[MessageNode]:
- """Get all nodes in the tree."""
- return list(self._nodes.values())
-
- def has_node(self, node_id: str) -> bool:
- """Check if a node exists in this tree."""
- return node_id in self._nodes
-
- def find_node_by_status_message(self, status_msg_id: str) -> Optional[MessageNode]:
- """Find the node that has this status message ID."""
- for node in self._nodes.values():
- if node.status_message_id == status_msg_id:
- return node
- return None
-
-
class TreeQueueManager:
"""
- Manages multiple message trees.
+ Manages multiple message trees. Facade that coordinates components.
Each new conversation creates a new tree.
Replies to existing messages add nodes to existing trees.
+
+ Components:
+ - TreeRepository: Data access layer
+ - TreeQueueProcessor: Async queue processing
"""
def __init__(self):
- self._trees: Dict[str, MessageTree] = {} # root_id -> tree
- self._node_to_tree: Dict[str, str] = {} # node_id -> root_id
+ self._repository = TreeRepository()
+ self._processor = TreeQueueProcessor()
self._lock = asyncio.Lock()
logger.info("TreeQueueManager initialized")
+ @property
+ def _trees(self):
+ """Access internal tree dict for backward compatibility."""
+ return self._repository._trees
+
+ @property
+ def _node_to_tree(self):
+ """Access internal node mapping for backward compatibility."""
+ return self._repository._node_to_tree
+
async def create_tree(
self,
node_id: str,
@@ -350,8 +79,7 @@ class TreeQueueManager:
)
tree = MessageTree(root_node)
- self._trees[node_id] = tree
- self._node_to_tree[node_id] = node_id
+ self._repository.add_tree(node_id, tree)
logger.info(f"Created new tree with root {node_id}")
return tree
@@ -376,13 +104,13 @@ class TreeQueueManager:
Tuple of (tree, new_node)
"""
async with self._lock:
- if parent_node_id not in self._node_to_tree:
+ if parent_node_id not in self._repository._node_to_tree:
raise ValueError(f"Parent node {parent_node_id} not found in any tree")
- root_id = self._node_to_tree[parent_node_id]
- tree = self._trees[root_id]
+ root_id = self._repository._node_to_tree[parent_node_id]
+ tree = self._repository._trees[root_id]
- # Add node (tree has its own lock)
+ # Add node (tree has its own lock) - outside manager lock to avoid deadlock
node = await tree.add_node(
node_id=node_id,
incoming=incoming,
@@ -391,61 +119,34 @@ class TreeQueueManager:
)
async with self._lock:
- self._node_to_tree[node_id] = root_id
+ self._repository.register_node(node_id, root_id)
logger.info(f"Added node {node_id} to tree {root_id}")
return tree, node
def get_tree(self, root_id: str) -> Optional[MessageTree]:
"""Get a tree by its root ID."""
- return self._trees.get(root_id)
+ return self._repository.get_tree(root_id)
def get_tree_for_node(self, node_id: str) -> Optional[MessageTree]:
"""Get the tree containing a given node."""
- root_id = self._node_to_tree.get(node_id)
- if not root_id:
- return None
- return self._trees.get(root_id)
+ return self._repository.get_tree_for_node(node_id)
def get_node(self, node_id: str) -> Optional[MessageNode]:
"""Get a node from any tree."""
- tree = self.get_tree_for_node(node_id)
- return tree.get_node(node_id) if tree else None
+ return self._repository.get_node(node_id)
def resolve_parent_node_id(self, msg_id: str) -> Optional[str]:
- """
- Resolve a message ID to the actual parent node ID.
-
- Handles the case where msg_id is a status message ID
- (which maps to the tree but isn't an actual node).
-
- Returns:
- The node_id to use as parent, or None if not found
- """
- tree = self.get_tree_for_node(msg_id)
- if not tree:
- return None
-
- # Check if msg_id is an actual node
- if tree.has_node(msg_id):
- return msg_id
-
- # Otherwise, it might be a status message - find the owning node
- node = tree.find_node_by_status_message(msg_id)
- if node:
- return node.node_id
-
- return None
+ """Resolve a message ID to the actual parent node ID."""
+ return self._repository.resolve_parent_node_id(msg_id)
def is_tree_busy(self, root_id: str) -> bool:
"""Check if a tree is currently processing."""
- tree = self._trees.get(root_id)
- return tree.is_processing if tree else False
+ return self._repository.is_tree_busy(root_id)
def is_node_tree_busy(self, node_id: str) -> bool:
"""Check if the tree containing a node is busy."""
- tree = self.get_tree_for_node(node_id)
- return tree.is_processing if tree else False
+ return self._repository.is_node_tree_busy(node_id)
async def enqueue(
self,
@@ -465,107 +166,20 @@ class TreeQueueManager:
Returns:
True if queued, False if processing immediately
"""
- tree = self.get_tree_for_node(node_id)
+ tree = self._repository.get_tree_for_node(node_id)
if not tree:
logger.error(f"No tree found for node {node_id}")
return False
- async with tree._lock:
- if tree._is_processing:
- # Tree is busy, queue the message
- await tree._queue.put(node_id)
- queue_size = tree._queue.qsize()
- logger.info(f"Queued node {node_id}, position {queue_size}")
- return True
- else:
- # Tree is free, start processing
- tree._is_processing = True
- tree._current_node_id = node_id
-
- # Process outside the lock
- node = tree.get_node(node_id)
- if node:
- tree._current_task = asyncio.create_task(
- self._process_node(tree, node, processor)
- )
- return False
-
- async def _process_node(
- self,
- tree: MessageTree,
- node: MessageNode,
- processor: Callable[[str, MessageNode], Awaitable[None]],
- ) -> None:
- """Process a single node and then check the queue."""
- try:
- await processor(node.node_id, node)
- except asyncio.CancelledError:
- logger.info(f"Task for node {node.node_id} was cancelled")
- raise
- except Exception as e:
- logger.error(f"Error processing node {node.node_id}: {e}")
- await tree.update_state(
- node.node_id, MessageState.ERROR, error_message=str(e)
- )
- finally:
- tree._current_node_id = None
- # Check if there are more messages in the queue
- await self._process_next(tree, processor)
-
- async def _process_next(
- self,
- tree: MessageTree,
- processor: Callable[[str, MessageNode], Awaitable[None]],
- ) -> None:
- """Process the next message in queue, if any."""
- async with tree._lock:
- next_node_id = await tree.dequeue()
-
- if not next_node_id:
- # No more messages, mark tree as free
- tree._is_processing = False
- logger.debug(f"Tree {tree.root_id} queue empty, marking as free")
- return
-
- tree._current_node_id = next_node_id
- logger.info(f"Processing next queued node {next_node_id}")
-
- # Process next node (outside lock)
- node = tree.get_node(next_node_id)
- if node:
- tree._current_task = asyncio.create_task(
- self._process_node(tree, node, processor)
- )
+ return await self._processor.enqueue_and_start(tree, node_id, processor)
def get_queue_size(self, node_id: str) -> int:
"""Get queue size for the tree containing a node."""
- tree = self.get_tree_for_node(node_id)
- return tree.get_queue_size() if tree else 0
+ return self._repository.get_queue_size(node_id)
def get_pending_children(self, node_id: str) -> List[MessageNode]:
- """
- Get all pending child nodes (recursively) of a given node.
-
- Used for error propagation - when a node fails, its pending
- children should also be marked as failed.
- """
- tree = self.get_tree_for_node(node_id)
- if not tree:
- return []
-
- pending = []
- node = tree.get_node(node_id)
- if not node:
- return []
-
- for child_id in node.children_ids:
- child = tree.get_node(child_id)
- if child and child.state == MessageState.PENDING:
- pending.append(child)
- # Recursively get children of pending children
- pending.extend(self.get_pending_children(child_id))
-
- return pending
+ """Get all pending child nodes (recursively) of a given node."""
+ return self._repository.get_pending_children(node_id)
async def mark_node_error(
self,
@@ -584,7 +198,7 @@ class TreeQueueManager:
Returns:
List of all nodes marked as error (including children)
"""
- tree = self.get_tree_for_node(node_id)
+ tree = self._repository.get_tree_for_node(node_id)
if not tree:
return []
@@ -596,15 +210,15 @@ class TreeQueueManager:
)
affected.append(node)
- if propagate_to_children:
- pending_children = self.get_pending_children(node_id)
- for child in pending_children:
- await tree.update_state(
- child.node_id,
- MessageState.ERROR,
- error_message=f"Parent failed: {error_message}",
- )
- affected.append(child)
+ if propagate_to_children:
+ pending_children = self._repository.get_pending_children(node_id)
+ for child in pending_children:
+ await tree.update_state(
+ child.node_id,
+ MessageState.ERROR,
+ error_message=f"Parent failed: {error_message}",
+ )
+ affected.append(child)
return affected
@@ -614,15 +228,14 @@ class TreeQueueManager:
Updates node states to ERROR and returns list of affected nodes.
"""
- tree = self._trees.get(root_id)
+ tree = self._repository.get_tree(root_id)
if not tree:
return []
cancelled_nodes = []
- # Cancel running task
- if tree._current_task and not tree._current_task.done():
- tree._current_task.cancel()
+ # Cancel running task via processor
+ if self._processor.cancel_current(tree):
if tree._current_node_id:
node = tree.get_node(tree._current_node_id)
if node and node.state not in (
@@ -662,26 +275,21 @@ class TreeQueueManager:
"""Cancel all messages in all trees."""
async with self._lock:
all_cancelled = []
- for root_id in list(self._trees.keys()):
+ for root_id in list(self._repository.tree_ids()):
all_cancelled.extend(self.cancel_tree(root_id))
return all_cancelled
def register_node(self, node_id: str, root_id: str) -> None:
"""Register a node ID to a tree (for external mapping)."""
- self._node_to_tree[node_id] = root_id
+ self._repository.register_node(node_id, root_id)
def to_dict(self) -> dict:
"""Serialize all trees."""
- return {
- "trees": {rid: tree.to_dict() for rid, tree in self._trees.items()},
- "node_to_tree": self._node_to_tree.copy(),
- }
+ return self._repository.to_dict()
@classmethod
def from_dict(cls, data: dict) -> "TreeQueueManager":
"""Deserialize from dictionary."""
manager = cls()
- for root_id, tree_data in data.get("trees", {}).items():
- manager._trees[root_id] = MessageTree.from_dict(tree_data)
- manager._node_to_tree = data.get("node_to_tree", {})
+ manager._repository = TreeRepository.from_dict(data)
return manager
diff --git a/messaging/tree_repository.py b/messaging/tree_repository.py
new file mode 100644
index 00000000..1333f9f1
--- /dev/null
+++ b/messaging/tree_repository.py
@@ -0,0 +1,139 @@
+"""Repository for message tree data access.
+
+Provides data access layer for managing trees and node mappings.
+"""
+
+import logging
+from typing import Dict, Optional, List
+
+from .tree_data import MessageTree, MessageNode, MessageState
+
+logger = logging.getLogger(__name__)
+
+
+class TreeRepository:
+ """
+ Repository for message tree data access.
+
+ Manages the storage and lookup of trees and node-to-tree mappings.
+ """
+
+ def __init__(self):
+ self._trees: Dict[str, MessageTree] = {} # root_id -> tree
+ self._node_to_tree: Dict[str, str] = {} # node_id -> root_id
+
+ def get_tree(self, root_id: str) -> Optional[MessageTree]:
+ """Get a tree by its root ID."""
+ return self._trees.get(root_id)
+
+ def get_tree_for_node(self, node_id: str) -> Optional[MessageTree]:
+ """Get the tree containing a given node."""
+ root_id = self._node_to_tree.get(node_id)
+ if not root_id:
+ return None
+ return self._trees.get(root_id)
+
+ def get_node(self, node_id: str) -> Optional[MessageNode]:
+ """Get a node from any tree."""
+ tree = self.get_tree_for_node(node_id)
+ return tree.get_node(node_id) if tree else None
+
+ def add_tree(self, root_id: str, tree: MessageTree) -> None:
+ """Add a new tree to the repository."""
+ self._trees[root_id] = tree
+ self._node_to_tree[root_id] = root_id
+
+ def register_node(self, node_id: str, root_id: str) -> None:
+ """Register a node ID to a tree."""
+ self._node_to_tree[node_id] = root_id
+
+ def is_tree_busy(self, root_id: str) -> bool:
+ """Check if a tree is currently processing."""
+ tree = self._trees.get(root_id)
+ return tree.is_processing if tree else False
+
+ def is_node_tree_busy(self, node_id: str) -> bool:
+ """Check if the tree containing a node is busy."""
+ tree = self.get_tree_for_node(node_id)
+ return tree.is_processing if tree else False
+
+ def get_queue_size(self, node_id: str) -> int:
+ """Get queue size for the tree containing a node."""
+ tree = self.get_tree_for_node(node_id)
+ return tree.get_queue_size() if tree else 0
+
+ def resolve_parent_node_id(self, msg_id: str) -> Optional[str]:
+ """
+ Resolve a message ID to the actual parent node ID.
+
+ Handles the case where msg_id is a status message ID
+ (which maps to the tree but isn't an actual node).
+
+ Returns:
+ The node_id to use as parent, or None if not found
+ """
+ tree = self.get_tree_for_node(msg_id)
+ if not tree:
+ return None
+
+ # Check if msg_id is an actual node
+ if tree.has_node(msg_id):
+ return msg_id
+
+ # Otherwise, it might be a status message - find the owning node
+ node = tree.find_node_by_status_message(msg_id)
+ if node:
+ return node.node_id
+
+ return None
+
+ def get_pending_children(self, node_id: str) -> List[MessageNode]:
+ """
+ Get all pending child nodes (recursively) of a given node.
+
+ Used for error propagation - when a node fails, its pending
+ children should also be marked as failed.
+ """
+ tree = self.get_tree_for_node(node_id)
+ if not tree:
+ return []
+
+ pending = []
+ node = tree.get_node(node_id)
+ if not node:
+ return []
+
+ for child_id in node.children_ids:
+ child = tree.get_node(child_id)
+ if child and child.state == MessageState.PENDING:
+ pending.append(child)
+ # Recursively get children of pending children
+ pending.extend(self.get_pending_children(child_id))
+
+ return pending
+
+ def all_trees(self) -> List[MessageTree]:
+ """Get all trees in the repository."""
+ return list(self._trees.values())
+
+ def tree_ids(self) -> List[str]:
+ """Get all tree root IDs."""
+ return list(self._trees.keys())
+
+ def to_dict(self) -> dict:
+ """Serialize all trees."""
+ return {
+ "trees": {rid: tree.to_dict() for rid, tree in self._trees.items()},
+ "node_to_tree": self._node_to_tree.copy(),
+ }
+
+ @classmethod
+ def from_dict(cls, data: dict) -> "TreeRepository":
+ """Deserialize from dictionary."""
+ from .tree_data import MessageTree
+
+ repo = cls()
+ for root_id, tree_data in data.get("trees", {}).items():
+ repo._trees[root_id] = MessageTree.from_dict(tree_data)
+ repo._node_to_tree = data.get("node_to_tree", {})
+ return repo
diff --git a/providers/model_utils.py b/providers/model_utils.py
new file mode 100644
index 00000000..fa07ee83
--- /dev/null
+++ b/providers/model_utils.py
@@ -0,0 +1,87 @@
+"""Model name normalization utilities.
+
+Centralizes model name mapping logic to avoid duplication across the codebase.
+"""
+
+import os
+from typing import Optional
+
+# Provider prefixes to strip from model names
+_PROVIDER_PREFIXES = ["anthropic/", "openai/", "gemini/"]
+
+# Claude model identifiers
+_CLAUDE_IDENTIFIERS = ["haiku", "sonnet", "opus", "claude"]
+
+
+def strip_provider_prefixes(model: str) -> str:
+ """
+ Strip provider prefixes from model name.
+
+ Args:
+ model: The model name, possibly with prefix
+
+ Returns:
+ Model name without provider prefix
+ """
+ for prefix in _PROVIDER_PREFIXES:
+ if model.startswith(prefix):
+ return model[len(prefix):]
+ return model
+
+
+def is_claude_model(model: str) -> bool:
+ """
+ Check if a model name identifies as a Claude model.
+
+ Args:
+ model: The (prefix-stripped) model name
+
+ Returns:
+ True if this is a Claude model
+ """
+ model_lower = model.lower()
+ return any(name in model_lower for name in _CLAUDE_IDENTIFIERS)
+
+
+def normalize_model_name(model: str, default_model: Optional[str] = None) -> str:
+ """
+ Normalize a model name by stripping prefixes and mapping to default if needed.
+
+ This is the central function for model name normalization across the API.
+ It strips provider prefixes and maps Claude model names to the configured model.
+
+ Args:
+ model: The model name (may include provider prefix)
+ default_model: The default model to use for Claude models.
+ If None, uses settings.model from config.
+
+ Returns:
+ Normalized model name (original if not a Claude model, mapped if Claude)
+ """
+ # Strip provider prefixes
+ clean = strip_provider_prefixes(model)
+
+ # Map Claude models to default
+ if is_claude_model(clean):
+ if default_model is None:
+ # Use environment/config default
+ default_model = os.getenv("MODEL", "moonshotai/kimi-k2-thinking")
+ return default_model
+
+ return model
+
+
+def get_original_model(model: str) -> str:
+ """
+ Get the original model name, storing it before normalization.
+
+ Convenience function that returns the input unchanged, intended to be
+ called alongside normalize_model_name to capture the original.
+
+ Args:
+ model: The model name
+
+ Returns:
+ The model name unchanged (for documentation purposes)
+ """
+ return model
diff --git a/providers/nvidia_mixins.py b/providers/nvidia_mixins.py
new file mode 100644
index 00000000..2b8c2971
--- /dev/null
+++ b/providers/nvidia_mixins.py
@@ -0,0 +1,329 @@
+"""Mixins for NVIDIA NIM provider - decoupling responsibilities.
+
+This module contains focused mixins that handle specific aspects of the
+NVIDIA NIM provider functionality:
+- RequestBuilderMixin: Builds request bodies
+- StreamProcessorMixin: Processes streaming responses
+- ErrorMapperMixin: Maps HTTP errors to provider exceptions
+- ResponseConverterMixin: Converts responses between formats
+"""
+
+import json
+import logging
+from typing import Any, Dict, AsyncIterator
+
+from .utils import AnthropicToOpenAIConverter, map_stop_reason, extract_think_content
+from .exceptions import (
+ AuthenticationError,
+ InvalidRequestError,
+ RateLimitError,
+ OverloadedError,
+ APIError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class RequestBuilderMixin:
+ """Mixin for building OpenAI-format request bodies.
+
+ Handles conversion from Anthropic request format to OpenAI format,
+ including system prompts, tools, thinking mode, and NIM-specific parameters.
+ """
+
+ def __init__(self, *args, **kwargs):
+ super().__init__(*args, **kwargs)
+ self._nim_params: Dict[str, Any] = {}
+
+ def _load_nim_params(self) -> Dict[str, Any]:
+ """Load NIM-specific parameters from environment.
+
+ Reads NVIDIA_NIM_* environment variables to configure defaults.
+
+ Returns:
+ Dictionary of NIM-specific parameters
+ """
+ import os
+
+ params: Dict[str, Any] = {}
+ if val := os.getenv("NVIDIA_NIM_TEMPERATURE"):
+ params["temperature"] = float(val)
+ if val := os.getenv("NVIDIA_NIM_TOP_P"):
+ params["top_p"] = float(val)
+ if val := os.getenv("NVIDIA_NIM_MAX_TOKENS"):
+ params["max_tokens"] = int(val)
+ return params
+
+ def _build_request_body(self, request_data: Any, stream: bool = False) -> dict:
+ """Build OpenAI-format request body from Anthropic request.
+
+ Args:
+ request_data: The incoming Anthropic-format request
+ stream: Whether this is a streaming request
+
+ Returns:
+ OpenAI-format request body dictionary
+ """
+ messages = AnthropicToOpenAIConverter.convert_messages(request_data.messages)
+
+ # Add system prompt
+ if request_data.system:
+ system_msg = AnthropicToOpenAIConverter.convert_system_prompt(
+ request_data.system
+ )
+ if system_msg:
+ messages.insert(0, system_msg)
+
+ body = {
+ "model": request_data.model,
+ "messages": messages,
+ "max_tokens": request_data.max_tokens,
+ "stream": stream,
+ }
+
+ if request_data.temperature is not None:
+ body["temperature"] = request_data.temperature
+ if request_data.top_p is not None:
+ body["top_p"] = request_data.top_p
+ if request_data.stop_sequences:
+ body["stop"] = request_data.stop_sequences
+ if request_data.tools:
+ body["tools"] = AnthropicToOpenAIConverter.convert_tools(request_data.tools)
+
+ # Handle thinking/reasoning mode
+ extra_body = request_data.extra_body.copy() if request_data.extra_body else {}
+ if request_data.thinking and getattr(request_data.thinking, "enabled", True):
+ extra_body.setdefault("thinking", {"type": "enabled"})
+ extra_body.setdefault("reasoning_split", True)
+
+ body.update(extra_body)
+
+ # Apply NIM defaults
+ for key, val in self._nim_params.items():
+ if key not in body:
+ body[key] = val
+
+ return body
+
+
+class ErrorMapperMixin:
+ """Mixin for mapping HTTP errors to provider exceptions.
+
+ Converts HTTP status codes and error responses to appropriate
+ ProviderError subclasses for standardized error handling.
+ """
+
+ def _map_error(self, response_status: int, error_text: str) -> Exception:
+ """Map HTTP status and error body to specific ProviderError.
+
+ Args:
+ response_status: HTTP status code
+ error_text: Raw error response body
+
+ Returns:
+ Appropriate ProviderError subclass instance
+ """
+ try:
+ error_data = json.loads(error_text)
+ message = error_data.get("error", {}).get("message", error_text)
+ except Exception:
+ message = error_text
+
+ if response_status == 401:
+ return AuthenticationError(message, raw_error=error_text)
+ if response_status == 429:
+ # Trigger global rate limit block
+ from .rate_limit import GlobalRateLimiter
+
+ GlobalRateLimiter.get_instance().set_blocked(60) # Default 60s cooldown
+ return RateLimitError(message, raw_error=error_text)
+ if response_status in (400, 422):
+ return InvalidRequestError(message, raw_error=error_text)
+ if response_status >= 500:
+ if "overloaded" in message.lower() or "capacity" in message.lower():
+ return OverloadedError(message, raw_error=error_text)
+ return APIError(message, status_code=response_status, raw_error=error_text)
+
+ return APIError(message, status_code=response_status, raw_error=error_text)
+
+
+class ResponseConverterMixin:
+ """Mixin for converting OpenAI responses to Anthropic format.
+
+ Handles content extraction, reasoning/thinking blocks, tool calls,
+ and response structure transformation.
+ """
+
+ def convert_response(self, response_json: dict, original_request: Any) -> dict:
+ """Convert OpenAI response to Anthropic format.
+
+ Args:
+ response_json: OpenAI-format response JSON
+ original_request: Original Anthropic-format request
+
+ Returns:
+ Anthropic-format response dictionary
+ """
+ import uuid
+
+ choice = response_json["choices"][0]
+ message = choice["message"]
+ content = []
+
+ # Extract reasoning from various sources
+ reasoning = message.get("reasoning_content")
+ if not reasoning:
+ reasoning_details = message.get("reasoning_details")
+ if reasoning_details and isinstance(reasoning_details, list):
+ reasoning = "\n".join(
+ item.get("text", "")
+ for item in reasoning_details
+ if isinstance(item, dict)
+ )
+
+ if reasoning:
+ content.append({"type": "thinking", "thinking": reasoning})
+
+ # Extract text content (with think tag handling)
+ if message.get("content"):
+ raw_content = message["content"]
+ if isinstance(raw_content, str):
+ if not reasoning:
+ think_content, raw_content = extract_think_content(raw_content)
+ if think_content:
+ content.append(
+ {"type": "thinking", "thinking": think_content}
+ )
+ if raw_content:
+ content.append({"type": "text", "text": raw_content})
+ elif isinstance(raw_content, list):
+ for item in raw_content:
+ if isinstance(item, dict) and item.get("type") == "text":
+ content.append(item)
+
+ # Extract tool calls
+ if message.get("tool_calls"):
+ for tc in message["tool_calls"]:
+ try:
+ args = json.loads(tc["function"]["arguments"])
+ except Exception:
+ args = tc["function"].get("arguments", {})
+ content.append(
+ {
+ "type": "tool_use",
+ "id": tc["id"],
+ "name": tc["function"]["name"],
+ "input": args,
+ }
+ )
+
+ if not content:
+ # NIM models (especially Mistral-based) often require non-empty content.
+ # Adding a single space satisfies this requirement while avoiding
+ # the "(no content)" display issue in Claude Code.
+ content.append({"type": "text", "text": " "})
+
+ usage = response_json.get("usage", {})
+
+ return {
+ "id": response_json.get("id", f"msg_{uuid.uuid4()}"),
+ "type": "message",
+ "role": "assistant",
+ "model": original_request.model,
+ "content": content,
+ "stop_reason": map_stop_reason(choice.get("finish_reason")),
+ "stop_sequence": None,
+ "usage": {
+ "input_tokens": usage.get("prompt_tokens", 0),
+ "output_tokens": usage.get("completion_tokens", 0),
+ "cache_creation_input_tokens": 0,
+ "cache_read_input_tokens": 0,
+ },
+ }
+
+
+class StreamProcessorMixin:
+ """Mixin for processing streaming responses from NIM API.
+
+ Handles SSE parsing, content block management, tool call processing,
+ and error handling during streaming.
+ """
+
+ def __init__(self, *args, **kwargs):
+ super().__init__(*args, **kwargs)
+
+ def _parse_sse_event(self, event_data: str) -> Any:
+ """Parse a single SSE event, return None if invalid/done.
+
+ Args:
+ event_data: Raw SSE event data
+
+ Returns:
+ Parsed JSON data or None for [DONE] or invalid events
+ """
+ if not event_data.strip():
+ return None
+
+ for line in event_data.splitlines():
+ line = line.strip()
+ if line.startswith("data:"):
+ data_content = line[5:].lstrip()
+ if data_content == "[DONE]":
+ return None
+ try:
+ return json.loads(data_content)
+ except json.JSONDecodeError:
+ logger.debug(f"JSON decode failed for SSE data: {data_content}")
+ return None
+ return None
+
+ def _process_tool_call(self, tc: dict, sse: Any):
+ """Process a single tool call delta and yield SSE events.
+
+ Args:
+ tc: Tool call delta from OpenAI stream
+ sse: SSEBuilder instance for generating events
+
+ Yields:
+ SSE event strings
+ """
+ import uuid
+
+ tc_index = tc.get("index", 0)
+ if tc_index < 0:
+ tc_index = len(sse.blocks.tool_indices)
+
+ # Update accumulated name if present
+ fn_delta = tc.get("function", {})
+ if fn_delta.get("name") is not None:
+ sse.blocks.tool_names[tc_index] = (
+ sse.blocks.tool_names.get(tc_index, "") + fn_delta["name"]
+ )
+
+ # Check if we should start the tool block
+ if tc_index not in sse.blocks.tool_indices:
+ name = sse.blocks.tool_names.get(tc_index, "")
+ # Only start if name is non-empty or we have an ID (start of tool call)
+ if name or tc.get("id"):
+ tool_id = tc.get("id") or f"tool_{uuid.uuid4()}"
+ yield sse.start_tool_block(tc_index, tool_id, name)
+ sse.blocks.tool_started[tc_index] = True
+ elif not sse.blocks.tool_started.get(tc_index) and sse.blocks.tool_names.get(
+ tc_index
+ ):
+ # Block index exists (due to ID in previous chunk) but not started due to empty name
+ tool_id = f"tool_{uuid.uuid4()}" # Should ideally reuse ID if we saved it
+ name = sse.blocks.tool_names[tc_index]
+ yield sse.start_tool_block(tc_index, tool_id, name)
+ sse.blocks.tool_started[tc_index] = True
+
+ args = fn_delta.get("arguments", "")
+ if args:
+ # Ensure block is started before emitting args (with a fallback name if still empty)
+ if not sse.blocks.tool_started.get(tc_index):
+ tool_id = tc.get("id") or f"tool_{uuid.uuid4()}"
+ name = sse.blocks.tool_names.get(tc_index, "tool_call") or "tool_call"
+ yield sse.start_tool_block(tc_index, tool_id, name)
+ sse.blocks.tool_started[tc_index] = True
+
+ yield sse.emit_tool_delta(tc_index, args)
diff --git a/tests/test_request_utils.py b/tests/test_request_utils.py
new file mode 100644
index 00000000..99155257
--- /dev/null
+++ b/tests/test_request_utils.py
@@ -0,0 +1,446 @@
+"""Tests for api/request_utils.py module."""
+
+import pytest
+from unittest.mock import MagicMock
+
+from api.request_utils import (
+ is_quota_check_request,
+ is_title_generation_request,
+ extract_command_prefix,
+ is_prefix_detection_request,
+ get_token_count,
+)
+from api.models import MessagesRequest, Message
+
+
+class TestQuotaCheckRequest:
+ """Tests for is_quota_check_request function."""
+
+ def test_quota_check_simple_string(self):
+ """Test quota check with simple string content."""
+ msg = MagicMock(spec=Message)
+ msg.role = "user"
+ msg.content = "Check my quota"
+
+ req = MagicMock(spec=MessagesRequest)
+ req.max_tokens = 1
+ req.messages = [msg]
+
+ assert is_quota_check_request(req) is True
+
+ def test_quota_check_case_insensitive(self):
+ """Test quota check is case insensitive."""
+ msg = MagicMock(spec=Message)
+ msg.role = "user"
+ msg.content = "Check my QUOTA"
+
+ req = MagicMock(spec=MessagesRequest)
+ req.max_tokens = 1
+ req.messages = [msg]
+
+ assert is_quota_check_request(req) is True
+
+ def test_quota_check_list_content(self):
+ """Test quota check with list content blocks."""
+ block = MagicMock()
+ block.text = "Check my quota"
+
+ msg = MagicMock(spec=Message)
+ msg.role = "user"
+ msg.content = [block]
+
+ req = MagicMock(spec=MessagesRequest)
+ req.max_tokens = 1
+ req.messages = [msg]
+
+ assert is_quota_check_request(req) is True
+
+ def test_not_quota_check_wrong_max_tokens(self):
+ """Test not quota check when max_tokens != 1."""
+ msg = MagicMock(spec=Message)
+ msg.role = "user"
+ msg.content = "Check my quota"
+
+ req = MagicMock(spec=MessagesRequest)
+ req.max_tokens = 100
+ req.messages = [msg]
+
+ assert is_quota_check_request(req) is False
+
+ def test_not_quota_check_multiple_messages(self):
+ """Test not quota check when multiple messages."""
+ msg1 = MagicMock(spec=Message)
+ msg1.role = "user"
+ msg1.content = "Check my quota"
+
+ msg2 = MagicMock(spec=Message)
+ msg2.role = "assistant"
+ msg2.content = "Hello"
+
+ req = MagicMock(spec=MessagesRequest)
+ req.max_tokens = 1
+ req.messages = [msg1, msg2]
+
+ assert is_quota_check_request(req) is False
+
+ def test_not_quota_check_wrong_role(self):
+ """Test not quota check when role is not user."""
+ msg = MagicMock(spec=Message)
+ msg.role = "assistant"
+ msg.content = "Check my quota"
+
+ req = MagicMock(spec=MessagesRequest)
+ req.max_tokens = 1
+ req.messages = [msg]
+
+ assert is_quota_check_request(req) is False
+
+ def test_not_quota_check_no_quota_keyword(self):
+ """Test not quota check when content doesn't contain quota."""
+ msg = MagicMock(spec=Message)
+ msg.role = "user"
+ msg.content = "Hello world"
+
+ req = MagicMock(spec=MessagesRequest)
+ req.max_tokens = 1
+ req.messages = [msg]
+
+ assert is_quota_check_request(req) is False
+
+
+class TestTitleGenerationRequest:
+ """Tests for is_title_generation_request function."""
+
+ def test_title_generation_simple(self):
+ """Test title generation detection with target phrase."""
+ msg = MagicMock(spec=Message)
+ msg.role = "user"
+ msg.content = "Please write a 5-10 word title for this conversation"
+
+ req = MagicMock(spec=MessagesRequest)
+ req.messages = [msg]
+
+ assert is_title_generation_request(req) is True
+
+ def test_title_generation_case_insensitive(self):
+ """Test title generation is case insensitive."""
+ msg = MagicMock(spec=Message)
+ msg.role = "user"
+ msg.content = "Write a 5-10 Word Title please"
+
+ req = MagicMock(spec=MessagesRequest)
+ req.messages = [msg]
+
+ assert is_title_generation_request(req) is True
+
+ def test_title_generation_list_content(self):
+ """Test title generation with list content blocks."""
+ block = MagicMock()
+ block.text = "Write a 5-10 word title"
+
+ msg = MagicMock(spec=Message)
+ msg.role = "user"
+ msg.content = [block]
+
+ req = MagicMock(spec=MessagesRequest)
+ req.messages = [msg]
+
+ assert is_title_generation_request(req) is True
+
+ def test_not_title_generation_no_phrase(self):
+ """Test not title generation without target phrase."""
+ msg = MagicMock(spec=Message)
+ msg.role = "user"
+ msg.content = "Hello world, how are you?"
+
+ req = MagicMock(spec=MessagesRequest)
+ req.messages = [msg]
+
+ assert is_title_generation_request(req) is False
+
+ def test_not_title_generation_wrong_role(self):
+ """Test not title generation when last message is not from user."""
+ msg = MagicMock(spec=Message)
+ msg.role = "assistant"
+ msg.content = "Write a 5-10 word title"
+
+ req = MagicMock(spec=MessagesRequest)
+ req.messages = [msg]
+
+ assert is_title_generation_request(req) is False
+
+ def test_not_title_generation_empty_messages(self):
+ """Test not title generation when no messages."""
+ req = MagicMock(spec=MessagesRequest)
+ req.messages = []
+
+ assert is_title_generation_request(req) is False
+
+
+class TestExtractCommandPrefix:
+ """Tests for extract_command_prefix function."""
+
+ def test_simple_command(self):
+ """Test extraction of simple command."""
+ assert extract_command_prefix("git status") == "git status"
+ assert extract_command_prefix("ls -la") == "ls"
+
+ def test_two_word_commands(self):
+ """Test extraction of two-word commands."""
+ assert extract_command_prefix("git commit -m 'message'") == "git commit"
+ assert extract_command_prefix("npm install package") == "npm install"
+ assert extract_command_prefix("docker run image") == "docker run"
+ assert extract_command_prefix("kubectl get pods") == "kubectl get"
+
+ def test_two_word_command_with_options(self):
+ """Test two-word command with options only returns first word."""
+ assert extract_command_prefix("git -v") == "git"
+ assert extract_command_prefix("npm --version") == "npm"
+
+ def test_with_env_vars(self):
+ """Test command with environment variables."""
+ assert extract_command_prefix("DEBUG=1 python script.py") == "DEBUG=1 python"
+ assert extract_command_prefix("API_KEY=secret node app.js") == "API_KEY=secret node"
+
+ def test_single_word_commands(self):
+ """Test single word commands."""
+ assert extract_command_prefix("ls") == "ls"
+ assert extract_command_prefix("python") == "python"
+ assert extract_command_prefix("make") == "make"
+
+ def test_command_injection_detected(self):
+ """Test detection of command injection attempts."""
+ assert extract_command_prefix("`whoami`") == "command_injection_detected"
+ assert extract_command_prefix("$(whoami)") == "command_injection_detected"
+ assert extract_command_prefix("echo $(cat /etc/passwd)") == "command_injection_detected"
+
+ def test_empty_command(self):
+ """Test handling of empty commands."""
+ assert extract_command_prefix("") == "none"
+ assert extract_command_prefix(" ") == "none"
+
+ def test_complex_git_command(self):
+ """Test complex git command extraction."""
+ assert extract_command_prefix("git log --oneline --graph") == "git log"
+ assert extract_command_prefix("git checkout -b feature-branch") == "git checkout"
+
+ def test_cargo_command(self):
+ """Test cargo command extraction."""
+ assert extract_command_prefix("cargo build") == "cargo build"
+ assert extract_command_prefix("cargo test") == "cargo test"
+ assert extract_command_prefix("cargo --version") == "cargo"
+
+
+class TestPrefixDetectionRequest:
+ """Tests for is_prefix_detection_request function."""
+
+ def test_prefix_detection_with_policy_spec(self):
+ """Test prefix detection with policy spec and command."""
+ msg = MagicMock(spec=Message)
+ msg.role = "user"
+ msg.content = "<policy_spec>policy</policy_spec> Command: git status"
+
+ req = MagicMock(spec=MessagesRequest)
+ req.messages = [msg]
+
+ is_prefix, command = is_prefix_detection_request(req)
+ assert is_prefix is True
+ assert command == "git status"
+
+ def test_prefix_detection_case_sensitive(self):
+ """Test prefix detection is case sensitive for Command:."""
+ msg = MagicMock(spec=Message)
+ msg.role = "user"
+ msg.content = "<policy_spec>policy</policy_spec> command: git status"
+
+ req = MagicMock(spec=MessagesRequest)
+ req.messages = [msg]
+
+ is_prefix, command = is_prefix_detection_request(req)
+ assert is_prefix is False
+ assert command == ""
+
+ def test_not_prefix_detection_no_policy_spec(self):
+ """Test not prefix detection without policy_spec."""
+ msg = MagicMock(spec=Message)
+ msg.role = "user"
+ msg.content = "Command: git status"
+
+ req = MagicMock(spec=MessagesRequest)
+ req.messages = [msg]
+
+ is_prefix, command = is_prefix_detection_request(req)
+ assert is_prefix is False
+ assert command == ""
+
+ def test_not_prefix_detection_multiple_messages(self):
+ """Test not prefix detection with multiple messages."""
+ msg1 = MagicMock(spec=Message)
+ msg1.role = "user"
+ msg1.content = "<policy_spec>policy</policy_spec> Command: git status"
+
+ msg2 = MagicMock(spec=Message)
+ msg2.role = "assistant"
+ msg2.content = "OK"
+
+ req = MagicMock(spec=MessagesRequest)
+ req.messages = [msg1, msg2]
+
+ is_prefix, command = is_prefix_detection_request(req)
+ assert is_prefix is False
+ assert command == ""
+
+ def test_not_prefix_detection_wrong_role(self):
+ """Test not prefix detection when message is not from user."""
+ msg = MagicMock(spec=Message)
+ msg.role = "assistant"
+ msg.content = "<policy_spec>policy</policy_spec> Command: git status"
+
+ req = MagicMock(spec=MessagesRequest)
+ req.messages = [msg]
+
+ is_prefix, command = is_prefix_detection_request(req)
+ assert is_prefix is False
+ assert command == ""
+
+ def test_prefix_detection_list_content(self):
+ """Test prefix detection with list content blocks."""
+ block = MagicMock()
+ block.text = "<policy_spec>policy</policy_spec> Command: ls -la"
+
+ msg = MagicMock(spec=Message)
+ msg.role = "user"
+ msg.content = [block]
+
+ req = MagicMock(spec=MessagesRequest)
+ req.messages = [msg]
+
+ is_prefix, command = is_prefix_detection_request(req)
+ assert is_prefix is True
+ assert command == "ls -la"
+
+
+class TestGetTokenCount:
+ """Tests for get_token_count function."""
+
+ def test_empty_messages(self):
+ """Test token count with empty messages."""
+ count = get_token_count([])
+ assert count >= 1 # Returns max(1, tokens)
+
+ def test_simple_message(self):
+ """Test token count with simple text message."""
+ msg = MagicMock()
+ msg.content = "Hello world"
+
+ count = get_token_count([msg])
+ assert count > 0
+ # "Hello world" is ~2-3 tokens plus overhead
+ assert count >= 3
+
+ def test_message_with_system_prompt(self):
+ """Test token count includes system prompt."""
+ msg = MagicMock()
+ msg.content = "Hello"
+
+ count = get_token_count([msg], system="You are a helpful assistant")
+ assert count > 0
+
+ def test_message_with_list_content(self):
+ """Test token count with list content blocks."""
+ text_block = MagicMock()
+ text_block.type = "text"
+ text_block.text = "Hello world"
+
+ msg = MagicMock()
+ msg.content = [text_block]
+
+ count = get_token_count([msg])
+ assert count > 0
+
+ def test_message_with_thinking_block(self):
+ """Test token count includes thinking blocks."""
+ thinking_block = MagicMock()
+ thinking_block.type = "thinking"
+ thinking_block.thinking = "Let me think about this..."
+
+ msg = MagicMock()
+ msg.content = [thinking_block]
+
+ count = get_token_count([msg])
+ assert count > 0
+
+ def test_message_with_tool_use(self):
+ """Test token count includes tool use blocks."""
+ tool_block = MagicMock()
+ tool_block.type = "tool_use"
+ tool_block.name = "search"
+ tool_block.input = {"query": "test"}
+
+ msg = MagicMock()
+ msg.content = [tool_block]
+
+ count = get_token_count([msg])
+ assert count > 0
+
+ def test_message_with_tool_result(self):
+ """Test token count includes tool result blocks."""
+ result_block = MagicMock()
+ result_block.type = "tool_result"
+ result_block.content = "Search results here"
+
+ msg = MagicMock()
+ msg.content = [result_block]
+
+ count = get_token_count([msg])
+ assert count > 0
+
+ def test_message_with_tools(self):
+ """Test token count includes tool definitions."""
+ msg = MagicMock()
+ msg.content = "Use the search tool"
+
+ tool = MagicMock()
+ tool.name = "search"
+ tool.description = "Search for information"
+ tool.input_schema = {"type": "object", "properties": {}}
+
+ count = get_token_count([msg], tools=[tool])
+ assert count > 0
+
+ def test_system_as_list(self):
+ """Test token count with system as list of blocks."""
+ msg = MagicMock()
+ msg.content = "Hello"
+
+ block = MagicMock()
+ block.text = "System prompt"
+
+ count = get_token_count([msg], system=[block])
+ assert count > 0
+
+ def test_tool_result_with_dict_content(self):
+ """Test token count with tool result containing dict content."""
+ result_block = MagicMock()
+ result_block.type = "tool_result"
+ result_block.content = {"result": "data"}
+
+ msg = MagicMock()
+ msg.content = [result_block]
+
+ count = get_token_count([msg])
+ assert count > 0
+
+ def test_multiple_messages_overhead(self):
+ """Test that multiple messages include overhead."""
+ msg1 = MagicMock()
+ msg1.content = "Hi"
+
+ msg2 = MagicMock()
+ msg2.content = "Hello"
+
+ count_single = get_token_count([msg1])
+ count_double = get_token_count([msg1, msg2])
+
+ # Double message should have more tokens (including overhead)
+ assert count_double > count_single