klaude-code 1.2.6__py3-none-any.whl

klaude_code/protocol/llm_param.py

@@ -0,0 +1,147 @@
+from enum import Enum
+from typing import Any, Literal
+
+from pydantic import BaseModel
+from pydantic.json_schema import JsonSchemaValue
+
+from klaude_code.protocol.model import ConversationItem
+
+
+class LLMClientProtocol(Enum):
+    OPENAI = "openai"
+    RESPONSES = "responses"
+    OPENROUTER = "openrouter"
+    ANTHROPIC = "anthropic"
+
+
+class ToolSchema(BaseModel):
+    name: str
+    type: Literal["function"]
+    description: str
+    parameters: JsonSchemaValue
+
+
+class Thinking(BaseModel):
+    """
+    Unified Thinking & Reasoning Configuration
+    """
+
+    # OpenAI Reasoning Style
+    reasoning_effort: Literal["high", "medium", "low", "minimal", "none"] | None = None
+    reasoning_summary: Literal["auto", "concise", "detailed"] | None = None
+
+    # Claude/Gemini Thinking Style
+    type: Literal["enabled", "disabled"] | None = None
+    budget_tokens: int | None = None
+
+
+class Cost(BaseModel):
+    """Cost configuration per million tokens (USD)."""
+
+    input: float  # Input token price per million tokens
+    output: float  # Output token price per million tokens
+    cache_read: float = 0.0  # Cache read price per million tokens
+    cache_write: float = 0.0  # Cache write price per million tokens (ignored in calculation for now)
+
+
+class OpenRouterProviderRouting(BaseModel):
+    """
+    https://openrouter.ai/docs/features/provider-routing#json-schema-for-provider-preferences
+    """
+
+    allow_fallbacks: bool | None = None
+    require_parameters: bool | None = None
+
+    # Data collection setting: allow (default) or deny
+    data_collection: Literal["deny", "allow"] | None = None
+
+    # Provider lists
+    order: list[str] | None = None
+    only: list[str] | None = None
+    ignore: list[str] | None = None
+
+    # Quantization filters
+    quantizations: list[Literal["int4", "int8", "fp4", "fp6", "fp8", "fp16", "bf16", "fp32", "unknown"]] | None = None
+
+    # Sorting strategy when order is not specified
+    sort: Literal["price", "throughput", "latency"] | None = None
+
+    class MaxPrice(BaseModel):
+        # USD price per million tokens (or provider-specific string); OpenRouter also
+        # accepts other JSON types according to the schema, so Any covers that.
+        prompt: float | str | Any | None = None
+        completion: float | str | Any | None = None
+        image: float | str | Any | None = None
+        audio: float | str | Any | None = None
+        request: float | str | Any | None = None
+
+    max_price: MaxPrice | None = None
+
+    class Experimental(BaseModel):
+        # Placeholder for future experimental settings (no properties allowed in schema)
+        pass
+
+    experimental: Experimental | None = None
+
+
+class LLMConfigProviderParameter(BaseModel):
+    provider_name: str = ""
+    protocol: LLMClientProtocol
+    base_url: str | None = None
+    api_key: str | None = None
+    is_azure: bool = False
+    azure_api_version: str | None = None
+
+
+class LLMConfigModelParameter(BaseModel):
+    model: str | None = None
+    temperature: float | None = None
+    max_tokens: int | None = None
+    context_limit: int | None = None
+
+    # OpenAI GPT-5
+    verbosity: Literal["low", "medium", "high"] | None = None
+
+    # Unified Thinking & Reasoning
+    thinking: Thinking | None = None
+
+    # OpenRouter Provider Routing Preferences
+    provider_routing: OpenRouterProviderRouting | None = None
+
+    # Cost configuration (USD per million tokens)
+    cost: Cost | None = None
+
+
+class LLMConfigParameter(LLMConfigProviderParameter, LLMConfigModelParameter):
+    """
+    Parameter support in config yaml
+
+    When adding a new parameter, please also modify the following:
+    - llm_parameter.py#apply_config_defaults
+    - llm/*/client.py, handle the new parameter, e.g. add it to extra_body
+    - ui/repl_display.py#display_welcome
+    - config/list_models.py#display_models_and_providers
+    - config/select_model.py#select_model_from_config
+    """
+
+    pass
+
+
+class LLMCallParameter(LLMConfigModelParameter):
+    """
+    Parameters for a single agent call
+    """
+
+    # Agent
+    input: list[ConversationItem]
+    system: str | None = None
+    tools: list[ToolSchema] | None = None
+
+    stream: Literal[True] = True  # Always True
+
+    # OpenAI Responses
+    include: list[str] | None = None
+    store: bool = True
+    previous_response_id: str | None = None
+
+    session_id: str | None = None

klaude_code/protocol/model.py

@@ -0,0 +1,287 @@
+from datetime import datetime
+from enum import Enum
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from klaude_code.protocol.commands import CommandName
+from klaude_code.protocol.tools import SubAgentType
+
+RoleType = Literal["system", "developer", "user", "assistant", "tool"]
+TodoStatusType = Literal["pending", "in_progress", "completed"]
+
+
+class Usage(BaseModel):
+    input_tokens: int = 0
+    cached_tokens: int = 0
+    reasoning_tokens: int = 0
+    output_tokens: int = 0
+    total_tokens: int = 0
+    context_usage_percent: float | None = None
+    throughput_tps: float | None = None
+    first_token_latency_ms: float | None = None
+
+    # Cost in USD (calculated from token counts and cost config)
+    input_cost: float | None = None  # Cost for non-cached input tokens
+    output_cost: float | None = None  # Cost for output tokens (including reasoning)
+    cache_read_cost: float | None = None  # Cost for cached tokens
+    total_cost: float | None = None  # Total cost (input + output + cache_read)
+
+
+class TodoItem(BaseModel):
+    content: str
+    status: TodoStatusType
+    activeForm: str = ""
+
+
+class TodoUIExtra(BaseModel):
+    todos: list[TodoItem]
+    new_completed: list[str]
+
+
+class ToolResultUIExtraType(str, Enum):
+    DIFF_TEXT = "diff_text"
+    TODO_LIST = "todo_list"
+    SESSION_ID = "session_id"
+    MERMAID_LINK = "mermaid_link"
+    TRUNCATION = "truncation"
+    SESSION_STATUS = "session_status"
+
+
+class ToolSideEffect(str, Enum):
+    TODO_CHANGE = "todo_change"
+
+
+class MermaidLinkUIExtra(BaseModel):
+    link: str
+    line_count: int
+
+
+class TruncationUIExtra(BaseModel):
+    saved_file_path: str
+    original_length: int
+    truncated_length: int
+
+
+class SessionStatusUIExtra(BaseModel):
+    usage: "Usage"
+    task_count: int
+
+
+class ToolResultUIExtra(BaseModel):
+    type: ToolResultUIExtraType
+    diff_text: str | None = None
+    todo_list: TodoUIExtra | None = None
+    session_id: str | None = None
+    mermaid_link: MermaidLinkUIExtra | None = None
+    truncation: TruncationUIExtra | None = None
+    session_status: SessionStatusUIExtra | None = None
+
+
+class AtPatternParseResult(BaseModel):
+    path: str
+    tool_name: str
+    result: str
+    tool_args: str
+    operation: Literal["Read", "List"]
+    images: list["ImageURLPart"] | None = None
+
+
+class CommandOutput(BaseModel):
+    command_name: CommandName
+    ui_extra: ToolResultUIExtra | None = None
+    is_error: bool = False
+
+
+class SubAgentState(BaseModel):
+    sub_agent_type: SubAgentType
+    sub_agent_desc: str
+    sub_agent_prompt: str
+
+
+"""
+Models for LLM API input and response items.
+
+A typical sequence of response items is:
+- [StartItem]
+- [ReasoningTextItem | ReasoningEncryptedItem]
+- [AssistantMessageDelta] × n
+- [AssistantMessageItem]
+- [ToolCallItem] × n
+- [ResponseMetadataItem]
+- Done
+
+A conversation history input contains:
+- [UserMessageItem]
+- [ReasoningTextItem | ReasoningEncryptedItem]
+- [AssistantMessageItem]
+- [ToolCallItem]
+- [ToolResultItem]
+- [InterruptItem]
+- [DeveloperMessageItem]
+
+When adding a new item, please also modify the following:
+- session.py#_TypeMap
+"""
+
+
+class StartItem(BaseModel):
+    response_id: str
+    created_at: datetime = Field(default_factory=datetime.now)
+
+
+class InterruptItem(BaseModel):
+    created_at: datetime = Field(default_factory=datetime.now)
+
+
+class SystemMessageItem(BaseModel):
+    id: str | None = None
+    role: RoleType = "system"
+    content: str | None = None
+    created_at: datetime = Field(default_factory=datetime.now)
+
+
+class DeveloperMessageItem(BaseModel):
+    id: str | None = None
+    role: RoleType = "developer"
+    content: str | None = None  # For LLM input
+    images: list["ImageURLPart"] | None = None
+    created_at: datetime = Field(default_factory=datetime.now)
+
+    # Special fields for reminders UI
+    memory_paths: list[str] | None = None
+    external_file_changes: list[str] | None = None
+    todo_use: bool | None = None
+    at_files: list[AtPatternParseResult] | None = None
+    command_output: CommandOutput | None = None
+    user_image_count: int | None = None
+
+
+class ImageURLPart(BaseModel):
+    class ImageURL(BaseModel):
+        url: str
+        id: str | None = None
+
+    image_url: ImageURL
+
+
+class UserInputPayload(BaseModel):
+    """Structured payload for user input containing text and optional images.
+
+    This is the unified data structure for user input across the entire
+    UI -> CLI -> Executor -> Agent -> Task chain.
+    """
+
+    text: str
+    images: list["ImageURLPart"] | None = None
+
+
+class UserMessageItem(BaseModel):
+    id: str | None = None
+    role: RoleType = "user"
+    content: str | None = None
+    images: list[ImageURLPart] | None = None
+    created_at: datetime = Field(default_factory=datetime.now)
+
+
+class AssistantMessageItem(BaseModel):
+    id: str | None = None
+    role: RoleType = "assistant"
+    content: str | None = None
+    response_id: str | None = None
+    created_at: datetime = Field(default_factory=datetime.now)
+
+
+class ReasoningTextItem(BaseModel):
+    id: str | None = None
+    response_id: str | None = None
+    content: str
+    model: str | None = None
+    created_at: datetime = Field(default_factory=datetime.now)
+
+
+class ReasoningEncryptedItem(BaseModel):
+    id: str | None = None
+    response_id: str | None = None
+    encrypted_content: str  # OpenAI encrypted content or Anthropic thinking signature
+    format: str | None = None
+    model: str | None
+    created_at: datetime = Field(default_factory=datetime.now)
+
+
+class ToolCallStartItem(BaseModel):
+    """Transient streaming signal when LLM starts a tool call.
+
+    This is NOT persisted to conversation history. Used only for
+    real-time UI feedback (e.g., "Calling Bash ...").
+    """
+
+    response_id: str | None = None
+    call_id: str
+    name: str
+    created_at: datetime = Field(default_factory=datetime.now)
+
+
+class ToolCallItem(BaseModel):
+    id: str | None = None
+    response_id: str | None = None
+    call_id: str
+    name: str
+    arguments: str
+    created_at: datetime = Field(default_factory=datetime.now)
+
+
+class ToolResultItem(BaseModel):
+    call_id: str = ""  # This field will auto set by tool registry's run_tool
+    output: str | None = None
+    status: Literal["success", "error"]
+    tool_name: str | None = None  # This field will auto set by tool registry's run_tool
+    ui_extra: ToolResultUIExtra | None = None  # Extra data for UI display, e.g. diff render
+    images: list[ImageURLPart] | None = None
+    side_effects: list[ToolSideEffect] | None = None
+    created_at: datetime = Field(default_factory=datetime.now)
+
+
+class AssistantMessageDelta(BaseModel):
+    response_id: str | None = None
+    content: str
+    created_at: datetime = Field(default_factory=datetime.now)
+
+
+class StreamErrorItem(BaseModel):
+    error: str
+    created_at: datetime = Field(default_factory=datetime.now)
+
+
+class ResponseMetadataItem(BaseModel):
+    response_id: str | None = None
+    usage: Usage | None = None
+    model_name: str = ""
+    provider: str | None = None  # OpenRouter's provider name
+    task_duration_s: float | None = None
+    status: str | None = None
+    error_reason: str | None = None
+    created_at: datetime = Field(default_factory=datetime.now)
+
+
+MessageItem = (
+    UserMessageItem
+    | AssistantMessageItem
+    | SystemMessageItem
+    | DeveloperMessageItem
+    | ReasoningTextItem
+    | ReasoningEncryptedItem
+    | ToolCallItem
+    | ToolResultItem
+)
+
+
+StreamItem = AssistantMessageDelta
+
+ConversationItem = (
+    StartItem | InterruptItem | StreamErrorItem | StreamItem | MessageItem | ResponseMetadataItem | ToolCallStartItem
+)
+
+
+def todo_list_str(todos: list[TodoItem]) -> str:
+    return "[" + "\n".join(f"[{todo.status}] {todo.content}" for todo in todos) + "]\n"

klaude_code/protocol/op.py

@@ -0,0 +1,89 @@
+"""
+Operation protocol for the executor system.
+
+This module defines the operation types and submission structure
+that the executor uses to handle different types of requests.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+from klaude_code.protocol.model import UserInputPayload
+
+if TYPE_CHECKING:
+    from klaude_code.protocol.op_handler import OperationHandler
+
+
+class OperationType(Enum):
+    """Enumeration of supported operation types."""
+
+    USER_INPUT = "user_input"
+    INTERRUPT = "interrupt"
+    INIT_AGENT = "init_agent"
+    END = "end"
+
+
+class Operation(BaseModel):
+    """Base class for all operations that can be submitted to the executor."""
+
+    type: OperationType
+    id: str = Field(default_factory=lambda: uuid4().hex)
+
+    async def execute(self, handler: OperationHandler) -> None:
+        """Execute this operation using the given handler."""
+        raise NotImplementedError("Subclasses must implement execute()")
+
+
+class UserInputOperation(Operation):
+    """Operation for handling user input (text and optional images) that should be processed by an agent."""
+
+    type: OperationType = OperationType.USER_INPUT
+    input: UserInputPayload
+    session_id: str | None = None
+
+    async def execute(self, handler: OperationHandler) -> None:
+        """Execute user input by running it through an agent."""
+        await handler.handle_user_input(self)
+
+
+class InterruptOperation(Operation):
+    """Operation for interrupting currently running tasks."""
+
+    type: OperationType = OperationType.INTERRUPT
+    target_session_id: str | None = None  # If None, interrupt all sessions
+
+    async def execute(self, handler: OperationHandler) -> None:
+        """Execute interrupt by cancelling active tasks."""
+        await handler.handle_interrupt(self)
+
+
+class InitAgentOperation(Operation):
+    """Operation for initializing an agent and replaying history if any."""
+
+    type: OperationType = OperationType.INIT_AGENT
+    session_id: str | None = None
+
+    async def execute(self, handler: OperationHandler) -> None:
+        await handler.handle_init_agent(self)
+
+
+class EndOperation(Operation):
+    """Operation for gracefully stopping the executor."""
+
+    type: OperationType = OperationType.END
+
+    async def execute(self, handler: OperationHandler) -> None:
+        """Execute end operation - this is a no-op, just signals the executor to stop."""
+        pass
+
+
+class Submission(BaseModel):
+    """A submission represents a request sent to the executor for processing."""
+
+    id: str
+    operation: Operation

klaude_code/protocol/op_handler.py

@@ -0,0 +1,28 @@
+"""
+Operation handler protocol for the executor system.
+
+This module defines the protocol that operation handlers must implement.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from klaude_code.protocol.op import InitAgentOperation, InterruptOperation, UserInputOperation
+
+
+class OperationHandler(Protocol):
+    """Protocol defining the interface for handling operations."""
+
+    async def handle_user_input(self, operation: UserInputOperation) -> None:
+        """Handle a user input operation."""
+        ...
+
+    async def handle_interrupt(self, operation: InterruptOperation) -> None:
+        """Handle an interrupt operation."""
+        ...
+
+    async def handle_init_agent(self, operation: InitAgentOperation) -> None:
+        """Handle an init agent operation."""
+        ...