python-library-ai-agent 0.1.0__py3-none-any.whl

ai_agent/__init__.py

@@ -0,0 +1,66 @@
+from ai_agent.agent import Agent
+from ai_agent.app import AgentApp, AgentSession, RunInputPacket, RunOutputPacket
+from ai_agent.harness import Harness
+from ai_agent.memory import BuiltMemoryContext, MemoryConfig, MemorySystem
+from ai_agent.skill import BuiltinToolRegistry, SkillKit, SkillManager
+from ai_agent.context import (
+    AgentContext,
+    ChatMessage,
+    RunContext,
+    RunPhase,
+    RunPhaseKind,
+    RunStatus,
+    ToolInvocation,
+)
+from ai_agent.listener import AgentListener
+from ai_agent.mcp_config import McpConfig, McpStdioServerConfig, parse_mcp_config
+from ai_agent.mcp_loader import MCPToolLoader
+from ai_agent.plan import (
+    Plan,
+    PlanParseError,
+    parse_plan_text,
+    PlanPlanner,
+    PlanRunResult,
+    PlanRunner,
+    PlanStep,
+    PlanStepFailedError,
+)
+from ai_agent.rule import RuleSet
+from ai_agent.tools import Tool
+
+__all__ = [
+    "Agent",
+    "AgentApp",
+    "AgentSession",
+    "RunInputPacket",
+    "RunOutputPacket",
+    "BuiltMemoryContext",
+    "Harness",
+    "MemoryConfig",
+    "MemorySystem",
+    "BuiltinToolRegistry",
+    "SkillKit",
+    "SkillManager",
+    "AgentContext",
+    "ChatMessage",
+    "AgentListener",
+    "McpConfig",
+    "McpStdioServerConfig",
+    "MCPToolLoader",
+    "RunContext",
+    "RunPhase",
+    "RunPhaseKind",
+    "RunStatus",
+    "Tool",
+    "ToolInvocation",
+    "parse_mcp_config",
+    "RuleSet",
+    "Plan",
+    "PlanParseError",
+    "parse_plan_text",
+    "PlanPlanner",
+    "PlanRunResult",
+    "PlanRunner",
+    "PlanStep",
+    "PlanStepFailedError",
+]

ai_agent/agent.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+
+from openai import AsyncOpenAI
+
+from ai_agent.context import (
+    AgentContext,
+    ChatMessage,
+    RunContext,
+    RunPhase,
+    RunPhaseKind,
+)
+from ai_agent.listener import AgentListener, normalize_listeners
+from ai_agent.llm import LLMClient
+from ai_agent.llm_openai import OpenAILLM
+from ai_agent.loop import ReactLoop
+from ai_agent.rule import RuleSet
+from ai_agent.tools import Tool, ToolRegistry
+
+
+class Agent:
+    """
+    ReAct 运行入口：构造时组装 ``AgentContext`` 并驱动多步循环。
+
+    系统提示由构造时的 ``rule_paths`` 指定文件读入；``run`` 只接收消息列表。
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        model: str,
+        base_url: str,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        thinking_enabled: bool = False,
+        tools: list[Tool] | ToolRegistry | None = None,
+        rule_paths: list[str] | list[Path] | tuple[str, ...] | tuple[Path, ...] | None = None,
+        max_steps: int = 20,
+        listeners: AgentListener | Iterable[AgentListener] | None = None,
+    ) -> None:
+        if not api_key.strip():
+            raise ValueError("api_key 不能为空")
+        if not model.strip():
+            raise ValueError("model 不能为空")
+        if not base_url.strip():
+            raise ValueError("base_url 不能为空")
+
+        api_key = api_key.strip()
+        model = model.strip()
+        base_url = base_url.strip().rstrip("/")
+
+        client = AsyncOpenAI(api_key=api_key, base_url=base_url)
+        llm: LLMClient = OpenAILLM(
+            client,
+            model=model,
+            base_url=base_url,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            thinking_enabled=thinking_enabled,
+        )
+        if isinstance(tools, ToolRegistry):
+            registry = tools
+        else:
+            registry = ToolRegistry(tools)
+        self.context = AgentContext(
+            llm=llm,
+            tools=registry,
+            max_steps=max_steps,
+            listeners=normalize_listeners(listeners),
+        )
+        self._rules = RuleSet(rule_paths)
+
+    @property
+    def rules(self) -> RuleSet:
+        """构造时绑定的规则集。"""
+        return self._rules
+
+    async def run(
+        self,
+        *,
+        messages: list[ChatMessage],
+    ) -> str:
+        """
+        运行一轮 ReAct 循环，返回最终回答文本。
+        """
+        return await self.run_with_system(
+            system_prompt=self._rules.build_system_prompt(),
+            messages=messages,
+        )
+
+    async def run_with_system(
+        self,
+        *,
+        system_prompt: str,
+        messages: list[ChatMessage],
+        phase: RunPhase | None = None,
+    ) -> str:
+        """
+        使用给定系统提示运行一轮（供会话层叠加计划步说明等）。
+
+        Args:
+            system_prompt: 本轮送入模型的完整系统提示
+            messages: 用户与助手历史及本轮输入
+        """
+        run = RunContext(
+            system_prompt=system_prompt,
+            messages=list(messages),
+            phase=phase or RunPhase(kind=RunPhaseKind.DIRECT),
+        )
+        if self.context.on_run_begin is not None:
+            self.context.on_run_begin(run)
+        try:
+            loop = ReactLoop(self.context)
+            async for updated in loop.run(run):
+                run = updated
+            return run.output
+        finally:
+            if self.context.on_run_end is not None:
+                self.context.on_run_end(run)

ai_agent/app/__init__.py

@@ -0,0 +1,10 @@
+from ai_agent.app.app import AgentApp
+from ai_agent.app.packet import RunInputPacket, RunOutputPacket
+from ai_agent.app.session import AgentSession
+
+__all__ = [
+    "AgentApp",
+    "AgentSession",
+    "RunInputPacket",
+    "RunOutputPacket",
+]

ai_agent/app/_workspace.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+_SESSIONS_DIR = "sessions"
+SESSION_HARNESS_SUBDIR = "harness"
+SESSION_MEMORY_SUBDIR = "memory"
+
+
+def resolve_app_sandbox_root(sandbox: Path | str) -> Path:
+    """
+    解析并创建总沙箱根目录。
+
+    Args:
+        sandbox: 总沙箱路径
+
+    Returns:
+        规范化后的绝对路径
+    """
+    root = Path(sandbox).expanduser().resolve()
+    root.mkdir(parents=True, exist_ok=True)
+    if not root.is_dir():
+        raise ValueError(f"沙箱根须为目录: {root}")
+    return root
+
+
+def validate_session_id(session_id: str) -> str:
+    """
+    校验会话标识，拒绝路径穿越与分隔符。
+
+    Args:
+        session_id: 调用方提供的会话 id
+
+    Returns:
+        去首尾空白后的 id
+    """
+    cleaned = session_id.strip()
+    if not cleaned:
+        raise ValueError("session_id 不能为空")
+    if cleaned in (".", ".."):
+        raise ValueError(f"非法 session_id: {session_id}")
+    for char in ("/", "\\", "\0"):
+        if char in cleaned:
+            raise ValueError(f"session_id 不能包含路径分隔符: {session_id}")
+    return cleaned
+
+
+def session_workspace(sandbox_root: Path, session_id: str) -> Path:
+    """
+    在总沙箱下为某会话分配子工作区目录。
+
+    Args:
+        sandbox_root: 总沙箱根（已 resolve）
+        session_id: 会话 id
+
+    Returns:
+        该会话专属子目录（已创建）
+    """
+    label = validate_session_id(session_id)
+    target = (sandbox_root / _SESSIONS_DIR / label).resolve()
+    try:
+        target.relative_to(sandbox_root)
+    except ValueError as exc:
+        raise ValueError(f"会话工作区越出总沙箱: {session_id}") from exc
+    target.mkdir(parents=True, exist_ok=True)
+    if not target.is_dir():
+        raise ValueError(f"无法创建会话工作区: {session_id}")
+    return target
+
+
+def _validate_session_subdir_name(name: str, *, label: str) -> str:
+    cleaned = name.strip()
+    if not cleaned:
+        raise ValueError(f"{label} 不能为空")
+    if cleaned in (".", ".."):
+        raise ValueError(f"非法 {label}: {name}")
+    for char in ("/", "\\", "\0"):
+        if char in cleaned:
+            raise ValueError(f"{label} 不能包含路径分隔符: {name}")
+    return cleaned
+
+
+def session_harness_workspace(session_root: Path) -> Path:
+    """
+    在会话工作区下分配 Harness 隔离子目录。
+
+    Args:
+        session_root: 会话根目录（已 resolve）
+
+    Returns:
+        Harness 工作区路径（已创建）
+    """
+    root = session_root.resolve()
+    sub = _validate_session_subdir_name(
+        SESSION_HARNESS_SUBDIR,
+        label="harness 子目录",
+    )
+    target = (root / sub).resolve()
+    try:
+        target.relative_to(root)
+    except ValueError as exc:
+        raise ValueError("Harness 子目录越出会话工作区") from exc
+    target.mkdir(parents=True, exist_ok=True)
+    if not target.is_dir():
+        raise ValueError("无法创建 Harness 工作区")
+    return target
+
+
+def reset_session_subdirs(session_root: Path) -> None:
+    """
+    清空会话内 Harness 与 memory 子目录并重建。
+
+    Args:
+        session_root: 会话根目录
+    """
+    root = session_root.resolve()
+    for sub_name in (SESSION_HARNESS_SUBDIR, SESSION_MEMORY_SUBDIR):
+        sub = _validate_session_subdir_name(sub_name, label="子目录")
+        target = (root / sub).resolve()
+        try:
+            target.relative_to(root)
+        except ValueError as exc:
+            raise ValueError(f"子目录越出会话工作区: {sub_name}") from exc
+        if target.is_dir():
+            shutil.rmtree(target)
+        target.mkdir(parents=True, exist_ok=True)

ai_agent/app/app.py

@@ -0,0 +1,321 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping, Sequence
+from pathlib import Path
+
+from ai_agent.app._workspace import (
+    SESSION_MEMORY_SUBDIR,
+    reset_session_subdirs,
+    resolve_app_sandbox_root,
+    session_harness_workspace,
+    session_workspace,
+    validate_session_id,
+)
+from ai_agent.app.harness_io import (
+    format_input_files_context,
+    resolve_output_files,
+    stage_input_files,
+)
+from ai_agent.app.output_format import parse_structured_run_output
+from ai_agent.app.packet import RunInputPacket, RunOutputPacket
+from ai_agent.app.session_store import (
+    clear_conversation,
+    load_conversation,
+    save_conversation,
+)
+from ai_agent.app.session import (
+    AgentSession,
+    build_session,
+    normalize_session_listeners,
+)
+from ai_agent.listener import AgentListener, notify_app_run_end
+from ai_agent.memory import MemoryConfig, MemorySystem
+from ai_agent.tools import Tool
+
+
+class AgentApp:
+    """
+    多会话应用入口：在总沙箱下按会话标识分配子目录，并装配隔离工作区、技能与对话代理。
+
+    各会话下固定 harness 子目录供工具读写、memory 子目录供分层记忆；语言模型与记忆压缩
+    模型在 AgentApp 构造时配置一次，会话间工作区与对话历史相互隔离。
+
+    Args:
+        sandbox: 总沙箱根目录
+        skill_roots: 只读技能仓库根；键为根键，值为目录路径；未配置则不挂载技能
+        rule_paths: 系统规则文本文件路径列表，固定拼入各轮系统提示
+        api_key: 主对话语言模型 API 密钥
+        model: 主对话模型名
+        base_url: 主对话 API 地址
+        temperature: 主对话采样温度；未设则由服务端默认
+        max_tokens: 主对话单次补全 token 上限；未设则由服务端默认
+        thinking_enabled: 主对话是否向兼容接口开启思考模式（``enable_thinking``）
+        max_steps: 单轮 ReAct 最大步数
+        extra_tools: 各会话共用的额外工具（如 MCP），共享同一列表引用
+        listeners: 运行时事件监听；可传单个或序列
+        memory_api_key: 记忆压缩用模型 API 密钥；三者缺一则不启用记忆
+        memory_model: 记忆压缩用模型名
+        memory_base_url: 记忆压缩用 API 地址
+        memory_short_term_max_messages: 短期记忆条数上限
+        memory_short_term_overflow_batch: 每次从短期弹出的条数
+        memory_date_memory_days: 日期记忆保留天数
+        memory_date_memory_max_entries_per_day: 单日日期记忆条目上限
+        memory_long_term_max_chunks: 长期记忆块数上限
+        memory_important_max_entries: 重要记忆条目上限
+        harness_enabled: 是否向模型注册 Harness 沙箱工具；默认关闭
+        current_time_tool_enabled: 是否注册 ``builtin__current_time``；默认开启
+    """
+
+    def __init__(
+        self,
+        sandbox: Path | str,
+        *,
+        skill_roots: (
+            Mapping[str, Path | str]
+            | Sequence[Path | str]
+            | Path
+            | str
+            | None
+        ) = None,
+        rule_paths: Sequence[Path | str] | None = None,
+        api_key: str,
+        model: str,
+        base_url: str,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        thinking_enabled: bool = False,
+        max_steps: int = 20,
+        extra_tools: list[Tool] | None = None,
+        listeners: AgentListener | Iterable[AgentListener] | None = None,
+        memory_api_key: str | None = None,
+        memory_model: str | None = None,
+        memory_base_url: str | None = None,
+        memory_short_term_max_messages: int = 20,
+        memory_short_term_overflow_batch: int = 5,
+        memory_date_memory_days: int = 7,
+        memory_date_memory_max_entries_per_day: int = 50,
+        memory_long_term_max_chunks: int = 30,
+        memory_important_max_entries: int = 20,
+        harness_enabled: bool = False,
+        current_time_tool_enabled: bool = True,
+    ) -> None:
+        self._sandbox_root = resolve_app_sandbox_root(sandbox)
+        self._skill_roots = skill_roots
+        self._rule_paths = tuple(rule_paths) if rule_paths else None
+        self._api_key = api_key
+        self._model = model
+        self._base_url = base_url
+        self._temperature = temperature
+        self._max_tokens = max_tokens
+        self._thinking_enabled = thinking_enabled
+        self._max_steps = max_steps
+        self._shared_extra_tools: list[Tool] = list(extra_tools or [])
+        self._listeners = normalize_session_listeners(listeners)
+        self._memory_api_key = memory_api_key
+        self._memory_model = memory_model
+        self._memory_base_url = memory_base_url
+        self._memory_config = MemoryConfig(
+            short_term_max_messages=memory_short_term_max_messages,
+            short_term_overflow_batch=memory_short_term_overflow_batch,
+            date_memory_days=memory_date_memory_days,
+            date_memory_max_entries_per_day=memory_date_memory_max_entries_per_day,
+            long_term_max_chunks=memory_long_term_max_chunks,
+            important_max_entries=memory_important_max_entries,
+        )
+        self._harness_enabled = harness_enabled
+        self._current_time_tool_enabled = current_time_tool_enabled
+        self._sessions: dict[str, AgentSession] = {}
+
+    @property
+    def shared_extra_tools(self) -> list[Tool]:
+        """各会话共用的已加载工具（如 MCP），运行时共享同一列表引用。"""
+        return self._shared_extra_tools
+
+    def set_shared_extra_tools(self, tools: list[Tool]) -> None:
+        """
+        替换各会话共用的工具表（须在 ``run`` 之前完成，例如 MCP ``load`` 之后）。
+
+        Args:
+            tools: 新工具列表；会替换内部列表内容
+        """
+        self._shared_extra_tools.clear()
+        self._shared_extra_tools.extend(tools)
+
+    @property
+    def sandbox_root(self) -> Path:
+        """总沙箱根目录。"""
+        return self._sandbox_root
+
+    @property
+    def harness_enabled(self) -> bool:
+        """各会话是否向模型注册 Harness 沙箱工具。"""
+        return self._harness_enabled
+
+    @property
+    def current_time_tool_enabled(self) -> bool:
+        """各会话是否向模型注册 ``builtin__current_time``。"""
+        return self._current_time_tool_enabled
+
+    @property
+    def thinking_enabled(self) -> bool:
+        """主对话是否在请求中开启思考模式。"""
+        return self._thinking_enabled
+
+    def list_session_ids(self) -> tuple[str, ...]:
+        """当前已打开（在内存中）的会话 id。"""
+        return tuple(sorted(self._sessions))
+
+    def has_session(self, session_id: str) -> bool:
+        """是否已有该会话实例。"""
+        label = validate_session_id(session_id)
+        return label in self._sessions
+
+    def get_session(self, session_id: str) -> AgentSession | None:
+        """
+        获取已打开的会话。
+
+        Args:
+            session_id: 会话 id
+
+        Returns:
+            已存在则返回会话，否则 ``None``
+        """
+        label = validate_session_id(session_id)
+        return self._sessions.get(label)
+
+    def open_session(
+        self,
+        session_id: str,
+        *,
+        memory: MemorySystem | None = None,
+    ) -> AgentSession:
+        """
+        打开或复用一会话：分配子沙箱并安装 Harness 与 Agent。
+
+        Args:
+            session_id: 会话 id；重复打开返回同一 ``AgentSession`` 实例
+            memory: 外部已构造的记忆系统；未传且 AgentApp 已配置记忆模型时自动创建
+
+        Returns:
+            该会话实例
+        """
+        label = validate_session_id(session_id)
+        existing = self._sessions.get(label)
+        if existing is not None:
+            return existing
+        session_root = session_workspace(self._sandbox_root, label)
+        harness_workspace = session_harness_workspace(session_root)
+        session_memory = memory
+        if session_memory is None:
+            session_memory = self._build_default_memory(session_root)
+        session = build_session(
+            session_id=label,
+            workspace=session_root,
+            harness_workspace=harness_workspace,
+            skill_roots=self._skill_roots,
+            rule_paths=self._rule_paths,
+            api_key=self._api_key,
+            model=self._model,
+            base_url=self._base_url,
+            temperature=self._temperature,
+            max_tokens=self._max_tokens,
+            thinking_enabled=self._thinking_enabled,
+            max_steps=self._max_steps,
+            extra_tools=self._shared_extra_tools,
+            listeners=self._listeners,
+            memory=session_memory,
+            harness_enabled=self._harness_enabled,
+            current_time_tool_enabled=self._current_time_tool_enabled,
+        )
+        self._sessions[label] = session
+        return session
+
+    async def run(self, packet: RunInputPacket) -> RunOutputPacket:
+        """
+        运行入口：接收输入数据包，规划并逐步执行后返回输出数据包。
+
+        单次调用内打开会话、处理完毕后从内存移除会话实例；Harness 与对话状态落在
+        ``sessions/<session_id>/``。运行时事件通过构造时传入的 ``listeners`` 回调。
+
+        Args:
+            packet: 用户名、会话 id、要求、附件路径与是否清空会话状态等
+
+        Returns:
+            结构化回答与须交还用户的文件路径列表
+        """
+        label = validate_session_id(packet.session_id)
+        user_name = packet.user_name.strip()
+        if not user_name:
+            raise ValueError("user_name 不能为空")
+        session_root = session_workspace(self._sandbox_root, label)
+        if packet.clear:
+            reset_session_subdirs(session_root)
+            clear_conversation(session_root)
+        self.close_session(label)
+        session = self.open_session(label)
+        try:
+            if not packet.clear and session.memory is None:
+                session.replace_messages(load_conversation(session_root))
+            if packet.input_files and not self._harness_enabled:
+                raise ValueError(
+                    "已传入 input_files 但 AgentApp.harness_enabled 为 False；"
+                    "请启用 Harness 或勿附带附件",
+                )
+            staged = stage_input_files(packet.input_files, session.harness.workspace)
+            file_context = format_input_files_context(staged)
+            user_message = _compose_plan_user_message(packet.request, file_context)
+            plan_result = await session.run_with_plan(
+                user_message=user_message,
+                speaker=user_name,
+                extra_planning_context=file_context,
+            )
+            answer, rel_files = parse_structured_run_output(plan_result.final_output)
+            output_files = resolve_output_files(rel_files, session.harness.workspace)
+            if session.memory is None:
+                save_conversation(session_root, list(session.messages))
+            packet = RunOutputPacket(
+                user_name=user_name,
+                session_id=label,
+                answer=answer,
+                output_files=output_files,
+            )
+            await notify_app_run_end(self._listeners, packet)
+            return packet
+        finally:
+            self.close_session(label)
+
+    def _build_default_memory(self, workspace: Path) -> MemorySystem | None:
+        key = self._memory_api_key
+        model = self._memory_model
+        base = self._memory_base_url
+        if not key or not model or not base:
+            return None
+        storage = workspace / SESSION_MEMORY_SUBDIR
+        return MemorySystem(
+            storage,
+            api_key=key,
+            model=model,
+            base_url=base,
+            config=self._memory_config,
+        )
+
+    def close_session(self, session_id: str) -> bool:
+        """
+        从应用中移除会话实例（不删除磁盘上的子沙箱内容）。
+
+        Args:
+            session_id: 会话 id
+
+        Returns:
+            若原先存在并已移除则为 True
+        """
+        label = validate_session_id(session_id)
+        return self._sessions.pop(label, None) is not None
+
+
+def _compose_plan_user_message(request: str, file_context: str) -> str:
+    """拼规划与记忆用的用户原文（不含最终交付 JSON 说明）。"""
+    parts: list[str] = [request.strip()]
+    if file_context.strip():
+        parts.append(file_context.strip())
+    return "\n\n".join(parts)