illusion-code 0.1.0__py3-none-any.whl

illusion/coordinator/coordinator_mode.py

@@ -0,0 +1,127 @@
+"""
+协调器模式模块
+==============
+
+本模块提供任务通知的 XML 序列化/反序列化功能。
+
+主要组件：
+    - TaskNotification: 已完成任务的结果结构
+    - format_task_notification: 序列化为 XML
+    - parse_task_notification: 从 XML 解析
+
+使用示例：
+    >>> from illusion.coordinator.coordinator_mode import TaskNotification, format_task_notification
+    >>> n = TaskNotification(task_id="agent-1", status="completed", summary="Done")
+    >>> xml = format_task_notification(n)
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+
+# ---------------------------------------------------------------------------
+# TaskNotification 数据类
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class TaskNotification:
+    """已完成代理任务的结构化结果。
+
+    Attributes:
+        task_id: 任务 ID
+        status: 状态 (completed/failed/killed)
+        summary: 人类可读的状态摘要
+        result: 代理的最终文本响应 (可选)
+        usage: 使用统计信息 (可选)
+    """
+
+    task_id: str
+    """任务 ID。"""
+
+    status: str
+    """状态 (completed/failed/killed)。"""
+
+    summary: str
+    """人类可读的状态摘要。"""
+
+    result: Optional[str] = None
+    """代理的最终文本响应。"""
+
+    usage: Optional[dict[str, int]] = None
+    """使用统计信息。"""
+
+
+# ---------------------------------------------------------------------------
+# XML 序列化/反序列化
+# ---------------------------------------------------------------------------
+
+# 使用统计字段名
+_USAGE_FIELDS = ("total_tokens", "tool_uses", "duration_ms")
+
+
+def format_task_notification(n: TaskNotification) -> str:
+    """将 TaskNotification 序列化为标准 XML envelope。
+
+    Args:
+        n: 任务通知对象
+
+    Returns:
+        str: XML 格式的字符串
+    """
+    parts = [
+        "<task-notification>",
+        f"<task-id>{n.task_id}</task-id>",
+        f"<status>{n.status}</status>",
+        f"<summary>{n.summary}</summary>",
+    ]
+    if n.result is not None:
+        parts.append(f"<result>{n.result}</result>")
+    if n.usage:
+        parts.append("<usage>")
+        for key in _USAGE_FIELDS:
+            if key in n.usage:
+                parts.append(f"  <{key}>{n.usage[key]}</{key}>")
+        parts.append("</usage>")
+    parts.append("</task-notification>")
+    return "\n".join(parts)
+
+
+def parse_task_notification(xml: str) -> TaskNotification:
+    """从 XML 字符串解析 TaskNotification。
+
+    Args:
+        xml: XML 格式的字符串
+
+    Returns:
+        TaskNotification: 解析后的任务通知对象
+    """
+
+    def _extract(tag: str) -> Optional[str]:
+        m = re.search(rf"<{tag}>(.*?)</{tag}>", xml, re.DOTALL)
+        return m.group(1).strip() if m else None
+
+    task_id = _extract("task-id") or ""
+    status = _extract("status") or ""
+    summary = _extract("summary") or ""
+    result = _extract("result")
+
+    usage: Optional[dict[str, int]] = None
+    usage_block = re.search(r"<usage>(.*?)</usage>", xml, re.DOTALL)
+    if usage_block:
+        usage = {}
+        for key in _USAGE_FIELDS:
+            m = re.search(rf"<{key}>(\d+)</{key}>", usage_block.group(1))
+            if m:
+                usage[key] = int(m.group(1))
+
+    return TaskNotification(
+        task_id=task_id,
+        status=status,
+        summary=summary,
+        result=result,
+        usage=usage,
+    )

illusion/engine/__init__.py

@@ -0,0 +1,95 @@
+"""
+核心引擎模块
+============
+
+本模块提供 IllusionCode 核心引擎的导出接口。
+
+主要组件：
+    - ConversationMessage: 对话消息模型
+    - TextBlock: 文本内容块
+    - ToolUseBlock: 工具调用块
+    - ToolResultBlock: 工具结果块
+    - QueryEngine: 查询引擎
+    - AssistantTextDelta: 助手文本增量事件
+    - AssistantTurnComplete: 助手轮次完成事件
+    - ToolExecutionStarted: 工具执行开始事件
+    - ToolExecutionCompleted: 工具执行完成事件
+
+使用示例：
+    >>> from illusion.engine import ConversationMessage, QueryEngine
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # 类型检查时导入，避免循环依赖
+    from illusion.engine.messages import (
+        ConversationMessage,
+        TextBlock,
+        ToolResultBlock,
+        ToolUseBlock,
+    )
+    from illusion.engine.query_engine import QueryEngine
+    from illusion.engine.stream_events import (
+        AssistantTextDelta,
+        AssistantTurnComplete,
+        ToolExecutionCompleted,
+        ToolExecutionStarted,
+    )
+
+__all__ = [
+    "AssistantTextDelta",
+    "AssistantTurnComplete",
+    "ConversationMessage",
+    "QueryEngine",
+    "TextBlock",
+    "ToolExecutionCompleted",
+    "ToolExecutionStarted",
+    "ToolResultBlock",
+    "ToolUseBlock",
+]
+
+
+def __getattr__(name: str):
+    if name in {"ConversationMessage", "TextBlock", "ToolResultBlock", "ToolUseBlock"}:
+        from illusion.engine.messages import (
+            ConversationMessage,
+            TextBlock,
+            ToolResultBlock,
+            ToolUseBlock,
+        )
+
+        return {
+            "ConversationMessage": ConversationMessage,
+            "TextBlock": TextBlock,
+            "ToolResultBlock": ToolResultBlock,
+            "ToolUseBlock": ToolUseBlock,
+        }[name]
+
+    if name == "QueryEngine":
+        from illusion.engine.query_engine import QueryEngine
+
+        return QueryEngine
+
+    if name in {
+        "AssistantTextDelta",
+        "AssistantTurnComplete",
+        "ToolExecutionCompleted",
+        "ToolExecutionStarted",
+    }:
+        from illusion.engine.stream_events import (
+            AssistantTextDelta,
+            AssistantTurnComplete,
+            ToolExecutionCompleted,
+            ToolExecutionStarted,
+        )
+
+        return {
+            "AssistantTextDelta": AssistantTextDelta,
+            "AssistantTurnComplete": AssistantTurnComplete,
+            "ToolExecutionCompleted": ToolExecutionCompleted,
+            "ToolExecutionStarted": ToolExecutionStarted,
+        }[name]
+
+    raise AttributeError(name)

illusion/engine/cost_tracker.py

@@ -0,0 +1,55 @@
+"""简单的使用量聚合。
+
+本模块提供成本跟踪功能，用于累积会话期间的使用量统计。
+
+主要类：
+    - CostTracker: 使用量累积器
+
+使用示例：
+    >>> from illusion.engine.cost_tracker import CostTracker
+    >>> tracker = CostTracker()
+    >>> tracker.add(usage_snapshot)
+    >>> print(tracker.total)
+"""
+
+from __future__ import annotations
+
+from illusion.api.usage import UsageSnapshot
+
+
+class CostTracker:
+    """在整个会话期间累积使用量。
+
+    用于跟踪对话过程中的令牌使用情况，包括输入和输出令牌数。
+
+    Attributes:
+        total: 累积的总使用量（只读属性）
+
+    使用示例：
+        >>> tracker = CostTracker()
+        >>> tracker.add(UsageSnapshot(input_tokens=100, output_tokens=50))
+        >>> print(tracker.total.input_tokens)  # 100
+    """
+
+    def __init__(self) -> None:
+        self._usage = UsageSnapshot()  # 初始化使用量快照
+
+    def add(self, usage: UsageSnapshot) -> None:
+        """将使用量快照添加到运行总和。
+
+        Args:
+            usage: 要添加的使用量快照
+        """
+        self._usage = UsageSnapshot(
+            input_tokens=self._usage.input_tokens + usage.input_tokens,
+            output_tokens=self._usage.output_tokens + usage.output_tokens,
+        )
+
+    @property
+    def total(self) -> UsageSnapshot:
+        """返回聚合后的使用量。
+
+        Returns:
+            UsageSnapshot: 累积的使用量快照
+        """
+        return self._usage

illusion/engine/messages.py

@@ -0,0 +1,369 @@
+"""
+对话消息模型模块
+================
+
+本模块提供查询引擎使用的对话消息模型。
+
+主要类：
+    - TextBlock: 纯文本内容块
+    - ToolUseBlock: 模型执行命名工具的请求
+    - ToolResultBlock: 发送回模型的工具结果内容
+    - ConversationMessage: 单个助手或用户消息
+
+使用示例：
+    >>> from illusion.engine.messages import ConversationMessage, TextBlock
+    >>> msg = ConversationMessage.from_user_text("Hello")
+"""
+
+from __future__ import annotations
+
+from typing import Any, Annotated, Literal
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+
+class TextBlock(BaseModel):
+    """纯文本内容块
+    
+    Attributes:
+        type: 块类型（固定为 "text"）
+        text: 文本内容
+    """
+
+    type: Literal["text"] = "text"
+    text: str
+
+
+class ToolUseBlock(BaseModel):
+    """模型执行命名工具的请求
+    
+    Attributes:
+        type: 块类型（固定为 "tool_use"）
+        id: 工具调用唯一标识
+        name: 工具名称
+        input: 工具输入参数
+    """
+
+    type: Literal["tool_use"] = "tool_use"
+    id: str = Field(default_factory=lambda: f"toolu_{uuid4().hex}")
+    name: str
+    input: dict[str, Any] = Field(default_factory=dict)
+
+
+class ToolResultBlock(BaseModel):
+    """发送回模型的工具结果内容
+
+    Attributes:
+        type: 块类型（固定为 "tool_result"）
+        tool_use_id: 对应的工具调用 ID
+        content: 工具返回的内容（纯文本或内容块列表）
+        is_error: 是否为错误结果
+    """
+
+    type: Literal["tool_result"] = "tool_result"
+    tool_use_id: str
+    content: str | list[ContentBlock] = ""
+    is_error: bool = False
+
+    @property
+    def text_content(self) -> str:
+        """返回纯文本内容。
+
+        Returns:
+            str: 文本字符串（content 为列表时提取 TextBlock 的文本）
+        """
+        if isinstance(self.content, str):
+            return self.content
+        return "".join(
+            block.text for block in self.content if isinstance(block, TextBlock)
+        )
+
+
+class ThinkingBlock(BaseModel):
+    """思考内容块（Anthropic extended thinking / DeepSeek thinking mode）
+
+    Attributes:
+        type: 块类型（固定为 "thinking"）
+        thinking: 思考文本
+        signature: 加密签名（Anthropic API 需要回传以验证思考内容未被篡改）
+    """
+
+    type: Literal["thinking"] = "thinking"
+    thinking: str
+    signature: str = ""
+
+
+class MediaBlock(BaseModel):
+    """图片文件内容块。
+
+    Attributes:
+        type: 块类型（固定为 "media"）
+        file_path: 文件绝对路径
+        media_type: MIME 类型，如 "image/png"
+        data: base64 编码的文件数据
+        metadata: 额外信息（文件大小等）
+    """
+
+    type: Literal["media"] = "media"
+    file_path: str
+    media_type: str
+    data: str = ""
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+def _build_tool_result_content(
+    output: str,
+    metadata: dict[str, Any],
+) -> str | list[ContentBlock]:
+    """从工具输出和元数据构建 ToolResultBlock 的内容。
+
+    如果元数据中包含媒体信息，返回 TextBlock + MediaBlock 的列表；
+    否则返回原始文本。
+    """
+    if "media_category" not in metadata:
+        return output
+
+    media_block = MediaBlock(
+        file_path=metadata.get("media_path", ""),
+        media_type=metadata.get("media_type", "application/octet-stream"),
+        data=metadata.get("media_data", ""),
+        metadata={"size": metadata.get("media_size", 0)},
+    )
+    return [TextBlock(text=output), media_block]
+
+
+def _messages_have_media(messages: list[ConversationMessage]) -> bool:
+    """检查消息列表中是否包含 MediaBlock"""
+    for msg in messages:
+        for block in msg.content:
+            if isinstance(block, MediaBlock):
+                return True
+            if isinstance(block, ToolResultBlock) and isinstance(block.content, list):
+                if any(isinstance(b, MediaBlock) for b in block.content):
+                    return True
+    return False
+
+
+def _strip_media_from_messages(messages: list[ConversationMessage]) -> list[ConversationMessage]:
+    """将消息中的 MediaBlock 替换为文本描述，用于不支持图片的模型优雅降级"""
+    result: list[ConversationMessage] = []
+    for msg in messages:
+        new_blocks: list[Any] = []
+        for block in msg.content:
+            if isinstance(block, MediaBlock):
+                size_str = f" ({block.metadata['size']} bytes)" if "size" in block.metadata else ""
+                new_blocks.append(TextBlock(
+                    text=f"[image file: {block.file_path}{size_str}, {block.media_type}] "
+                         "This model does not support image input",
+                ))
+            elif isinstance(block, ToolResultBlock) and isinstance(block.content, list):
+                stripped: list[Any] = []
+                for b in block.content:
+                    if isinstance(b, MediaBlock):
+                        size_str = f" ({b.metadata['size']} bytes)" if "size" in b.metadata else ""
+                        stripped.append(TextBlock(
+                            text=f"[image file: {b.file_path}{size_str}, {b.media_type}] "
+                                 "This model does not support image input",
+                        ))
+                    else:
+                        stripped.append(b)
+                new_blocks.append(ToolResultBlock(
+                    tool_use_id=block.tool_use_id,
+                    content=stripped,
+                    is_error=block.is_error,
+                ))
+            else:
+                new_blocks.append(block)
+        result.append(ConversationMessage(role=msg.role, content=new_blocks))
+    return result
+
+
+# 内容块联合类型
+ContentBlock = Annotated[
+    TextBlock | ToolUseBlock | ToolResultBlock | ThinkingBlock | MediaBlock,
+    Field(discriminator="type"),
+]
+
+
+class ConversationMessage(BaseModel):
+    """单个助手或用户消息
+    
+    Attributes:
+        role: 消息角色（"user" 或 "assistant"）
+        content: 内容块列表
+    """
+
+    role: Literal["user", "assistant"]
+    content: list[ContentBlock] = Field(default_factory=list)
+
+    @classmethod
+    def from_user_text(cls, text: str) -> "ConversationMessage":
+        """从原始文本构造用户消息
+        
+        Args:
+            text: 用户输入文本
+        
+        Returns:
+            ConversationMessage: 用户消息
+        """
+        return cls(role="user", content=[TextBlock(text=text)])
+
+    @property
+    def text(self) -> str:
+        """返回连接的文本块
+        
+        Returns:
+            str: 所有文本块的连接字符串
+        """
+        return "".join(
+            block.text for block in self.content if isinstance(block, TextBlock)
+        )
+
+    @property
+    def tool_uses(self) -> list[ToolUseBlock]:
+        """返回消息中包含的所有工具调用
+        
+        Returns:
+            list[ToolUseBlock]: 工具调用列表
+        """
+        return [block for block in self.content if isinstance(block, ToolUseBlock)]
+
+    @property
+    def thinking_text(self) -> str:
+        """返回连接后的思考文本块。"""
+        return "\n\n".join(
+            block.thinking.strip()
+            for block in self.content
+            if isinstance(block, ThinkingBlock) and block.thinking.strip()
+        )
+
+    def to_api_param(self, *, provider_type: str = "anthropic") -> dict[str, Any]:
+        """将消息转换为提供商 SDK 消息参数。
+
+        Args:
+            provider_type: 提供商类型
+
+        Returns:
+            dict[str, Any]: API 参数格式的字典
+        """
+        content_blocks = list(self.content)
+        
+        # MiMo 等 API 要求 Text block 的 text 字段最小长度为 1
+        # 过滤掉空文本块，避免 "content or tool_calls must be set" 错误
+        if self.role == "assistant":
+            content_blocks = [
+                b for b in content_blocks
+                if not (isinstance(b, TextBlock) and not b.text.strip())
+            ]
+            # 如果过滤后没有内容，添加占位符
+            if not content_blocks:
+                content_blocks = [TextBlock(text="...")]
+        
+        return {
+            "role": self.role,
+            "content": [serialize_content_block(block, provider_type=provider_type) for block in content_blocks],
+        }
+
+
+def serialize_content_block(block: ContentBlock, *, provider_type: str = "anthropic") -> dict[str, Any]:
+    """将本地内容块转换为提供商线格式。
+
+    Args:
+        block: 内容块
+        provider_type: 提供商类型（"anthropic"、"openai_compat"、"openai_codex"）
+
+    Returns:
+        dict[str, Any]: 线格式字典
+    """
+    if isinstance(block, TextBlock):
+        return {"type": "text", "text": block.text}
+
+    if isinstance(block, ToolUseBlock):
+        return {
+            "type": "tool_use",
+            "id": block.id,
+            "name": block.name,
+            "input": block.input,
+        }
+
+    if isinstance(block, ThinkingBlock):
+        result: dict[str, Any] = {"type": "thinking", "thinking": block.thinking}
+        if block.signature:
+            result["signature"] = block.signature
+        return result
+
+    if isinstance(block, MediaBlock):
+        return _serialize_media_block(block, provider_type)
+
+    # tool_result
+    if isinstance(block.content, list):
+        serialized_content = [
+            serialize_content_block(inner, provider_type=provider_type)
+            for inner in block.content
+        ]
+    else:
+        serialized_content = block.content
+    return {
+        "type": "tool_result",
+        "tool_use_id": block.tool_use_id,
+        "content": serialized_content,
+        "is_error": block.is_error,
+    }
+
+
+def _serialize_media_block(block: MediaBlock, provider_type: str) -> dict[str, Any]:
+    """将图片 MediaBlock 按提供商格式序列化。"""
+    if provider_type == "anthropic":
+        return {
+            "type": "image",
+            "source": {
+                "type": "base64",
+                "media_type": block.media_type,
+                "data": block.data,
+            },
+        }
+    if provider_type == "openai_codex":
+        return {
+            "type": "input_image",
+            "image_url": f"data:{block.media_type};base64,{block.data}",
+        }
+    # openai_compat
+    return {
+        "type": "image_url",
+        "image_url": {"url": f"data:{block.media_type};base64,{block.data}"},
+    }
+
+
+def assistant_message_from_api(raw_message: Any) -> ConversationMessage:
+    """将 Anthropic SDK 消息对象转换为对话消息
+    
+    Args:
+        raw_message: Anthropic SDK 原始消息
+    
+    Returns:
+        ConversationMessage: 转换后的对话消息
+    """
+    content: list[ContentBlock] = []
+
+    for raw_block in getattr(raw_message, "content", []):
+        block_type = getattr(raw_block, "type", None)
+        if block_type == "text":
+            content.append(TextBlock(text=getattr(raw_block, "text", "")))
+        elif block_type == "tool_use":
+            content.append(
+                ToolUseBlock(
+                    id=getattr(raw_block, "id", f"toolu_{uuid4().hex}"),
+                    name=getattr(raw_block, "name", ""),
+                    input=dict(getattr(raw_block, "input", {}) or {}),
+                )
+            )
+        elif block_type == "thinking":
+            content.append(
+                ThinkingBlock(
+                    thinking=getattr(raw_block, "thinking", ""),
+                    signature=getattr(raw_block, "signature", "") or "",
+                )
+            )
+
+    return ConversationMessage(role="assistant", content=content)