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

ai_agent/skill/skill_kit.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+
+from ai_agent.skill.manager import SkillManager
+from ai_agent.tools import Tool
+
+
+class SkillKit:
+    """
+    技能区入口：扫描、启用与工具导出委托底层管理器。
+
+    技能仓库运行时只读；导出列表含管理工具与当前已启用子工具。
+
+    Args:
+        roots: 技能根目录；可为单路径、路径序列或根键到路径的映射
+        manager: 已构造的管理器；未传则按 roots 新建
+    """
+
+    def __init__(
+        self,
+        roots: Mapping[str, Path | str] | Sequence[Path | str] | Path | str,
+        *,
+        manager: SkillManager | None = None,
+    ) -> None:
+        if manager is None:
+            self._manager = SkillManager(roots)
+        else:
+            self._manager = manager
+
+    @property
+    def manager(self) -> SkillManager:
+        """底层动态能力管理器。"""
+        return self._manager
+
+    @property
+    def root_keys(self) -> tuple[str, ...]:
+        """已配置的根键名。"""
+        return self._manager.root_keys
+
+    def list_skills(self, root_key: str = "") -> str:
+        """扫描 skill 根目录并列出摘要。"""
+        return self._manager.list_skills(root_key)
+
+    def get_metadata(self, skill_ref: str) -> str:
+        """读取 frontmatter 元数据。"""
+        return self._manager.get_metadata(skill_ref)
+
+    def enable_skill(self, skill_ref: str) -> str:
+        """启用 skill 及其子工具。"""
+        return self._manager.enable_skill(skill_ref)
+
+    def disable_skill(self, skill_ref: str) -> str:
+        """停用 skill。"""
+        return self._manager.disable_skill(skill_ref)
+
+    def refresh(self) -> str:
+        """重新扫描 skill 根。"""
+        return self._manager.refresh()
+
+    def roots_info(self) -> str:
+        """说明 skill 根目录约束。"""
+        return self._manager.roots_info()
+
+    def build_management_tools(self) -> list[Tool]:
+        """仅 skill 管理工具。"""
+        return self._manager.build_management_tools()
+
+    def build_enabled_tools(self) -> list[Tool]:
+        """仅已启用 skill 的子工具。"""
+        return self._manager.build_enabled_tools()
+
+    def build_all_flat_tools(self) -> list[Tool]:
+        """管理工具与已启用子工具。"""
+        return self._manager.build_all_flat_tools()
+
+    def build_tools(self) -> list[Tool]:
+        """管理工具与已启用子工具（兼容旧用法）。"""
+        return self.build_all_flat_tools()

ai_agent/skill/tool_declarations.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import re
+
+from ai_agent.skill.models import SkillToolDecl
+
+_FRONTMATTER_RE = re.compile(
+    r"\A---\r?\n(.*?)\r?\n---\r?\n?",
+    re.DOTALL,
+)
+
+
+def parse_tool_declarations(text: str) -> list[SkillToolDecl]:
+    """
+    从 SKILL.md 全文解析 frontmatter 中的 tools 列表。
+
+    Args:
+        text: SKILL.md 全文
+
+    Returns:
+        声明列表；无 tools 段时为空
+    """
+    match = _FRONTMATTER_RE.match(text)
+    if not match:
+        return []
+    return _parse_tools_block(match.group(1))
+
+
+def _parse_tools_block(frontmatter: str) -> list[SkillToolDecl]:
+    lines = frontmatter.splitlines()
+    start = -1
+    for index, line in enumerate(lines):
+        if line.strip() == "tools:":
+            start = index + 1
+            break
+    if start < 0:
+        return []
+    decls: list[SkillToolDecl] = []
+    current_name = ""
+    current_handler = ""
+    for line in lines[start:]:
+        stripped = line.strip()
+        if not stripped:
+            continue
+        if stripped.startswith("- "):
+            if current_name and current_handler:
+                decls.append(
+                    SkillToolDecl(name=current_name, handler=current_handler)
+                )
+            current_name = ""
+            current_handler = ""
+            item = stripped[2:].strip()
+            if item.startswith("name:"):
+                current_name = item.split(":", 1)[1].strip()
+            elif item.startswith("handler:"):
+                current_handler = item.split(":", 1)[1].strip()
+            continue
+        if stripped.startswith("name:"):
+            current_name = stripped.split(":", 1)[1].strip()
+            continue
+        if stripped.startswith("handler:"):
+            current_handler = stripped.split(":", 1)[1].strip()
+            continue
+        if not line.startswith((" ", "\t")):
+            break
+    if current_name and current_handler:
+        decls.append(SkillToolDecl(name=current_name, handler=current_handler))
+    return decls

ai_agent/tools.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+from ai_agent.context import ToolInvocation
+
+
+@dataclass
+class Tool:
+    """可注册到 Agent 的工具；由库内执行并写回 ToolInvocation.answer。"""
+
+    name: str
+    description: str
+    parameters: dict[str, Any]
+    handler: Callable[..., Any]
+
+    def to_api(self) -> dict[str, Any]:
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+    async def run(self, arguments: dict[str, Any]) -> tuple[bool, str]:
+        """
+        执行工具处理函数。
+
+        Returns:
+            是否成功、写入 invocation.answer 的文本
+        """
+        try:
+            result = self.handler(**arguments)
+            if isinstance(result, Awaitable):
+                result = await result
+            return True, str(result)
+        except Exception as exc:  # noqa: BLE001 — 工具边界统一收口
+            return False, str(exc)
+
+
+class ToolRegistry:
+    """
+    按来源分层维护工具，对外平铺为 OpenAI tools。
+
+    层顺序：基础 → skill 管理 → 已启用 skill 子工具 → 额外注入；重名时报错。
+    """
+
+    def __init__(self, tools: list[Tool] | None = None) -> None:
+        self._base: dict[str, Tool] = {}
+        self._management: dict[str, Tool] = {}
+        self._skill: dict[str, Tool] = {}
+        self._extra: dict[str, Tool] = {}
+        self._flat: dict[str, Tool] = {}
+        if tools:
+            for tool in tools:
+                self._base[tool.name] = tool
+        self._rebuild_flat()
+
+    def set_base_tools(self, tools: list[Tool]) -> None:
+        """替换基础工具层（如 Harness 沙箱工具）。"""
+        self._base = {tool.name: tool for tool in tools}
+        self._rebuild_flat()
+
+    def set_management_tools(self, tools: list[Tool]) -> None:
+        """替换 skill 管理工具层。"""
+        self._management = {tool.name: tool for tool in tools}
+        self._rebuild_flat()
+
+    def set_skill_tools(self, tools: list[Tool]) -> None:
+        """替换当前已启用 skill 暴露的子工具层。"""
+        self._skill = {tool.name: tool for tool in tools}
+        self._rebuild_flat()
+
+    def set_extra_tools(self, tools: list[Tool]) -> None:
+        """替换额外注入工具（如 MCP）。"""
+        self._extra = {tool.name: tool for tool in tools}
+        self._rebuild_flat()
+
+    def register(self, tool: Tool) -> None:
+        """向额外层注册单个工具（与 ``set_extra_tools`` 同层，可覆盖同名）。"""
+        self._extra[tool.name] = tool
+        self._rebuild_flat()
+
+    def effective_tools(self) -> list[Tool]:
+        """当前合并后的全部工具实例。"""
+        return list(self._flat.values())
+
+    def api_tools(self) -> list[dict[str, Any]]:
+        return [tool.to_api() for tool in self._flat.values()]
+
+    def get(self, name: str) -> Tool | None:
+        return self._flat.get(name)
+
+    async def execute(self, invocation: ToolInvocation) -> None:
+        """执行一次调用并更新 invocation 的 answer / ok。"""
+        tool = self.get(invocation.tool_name)
+        if tool is None:
+            invocation.ok = False
+            invocation.answer = f"unknown tool: {invocation.tool_name}"
+            return
+        ok, text = await tool.run(invocation.arguments)
+        invocation.ok = ok
+        invocation.answer = text
+
+    def _rebuild_flat(self) -> None:
+        merged: dict[str, Tool] = {}
+        for layer_name, layer in (
+            ("base", self._base),
+            ("management", self._management),
+            ("skill", self._skill),
+            ("extra", self._extra),
+        ):
+            for name, tool in layer.items():
+                if name in merged:
+                    raise ValueError(
+                        f"工具名冲突: {name!r}（{layer_name} 与已有层重复）"
+                    )
+                merged[name] = tool
+        self._flat = merged

python_library_ai_agent-0.1.0.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: python-library-ai-agent
+Version: 0.1.0
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0
+Requires-Dist: openai>=1.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: python-dotenv>=1.0; extra == 'dev'

python_library_ai_agent-0.1.0.dist-info/RECORD

@@ -0,0 +1,62 @@
+ai_agent/__init__.py,sha256=8F76hCsDdVh8RR9XuzYuDqFpDdTwMJo4pZRXTPHO4DY,1605
+ai_agent/agent.py,sha256=YtKrsq7FU7k1Fmikh77YjhBUhnS-OqrNkVSBns9w1cM,3796
+ai_agent/context.py,sha256=iWMD3OIXN35SWsAjlcdLY7Ehhjaoe6OcnubCt5BS53I,4587
+ai_agent/json_extract.py,sha256=1z_T-Cz9LafPaA7TuZ82nwJIWkhjvzXq0IIDZq0koBA,1733
+ai_agent/listener.py,sha256=zWTLnB-DdeqKX4yijmtIDuN1eZ3GeW76k-tZAC-B-8E,5213
+ai_agent/llm.py,sha256=wquS2bnb6Bed84DeqThKgydtre4Q92p6ZWNRbqyoS6k,1002
+ai_agent/llm_openai.py,sha256=1NtacqoL1_KNDA08pCdS-wDDBgk4U21TRXTFP2g6gx4,4139
+ai_agent/loop.py,sha256=OqXovXCADW__anQWLX3a3Gl-K4QiiAnINe6FTo9iJ-o,4629
+ai_agent/mcp_config.py,sha256=FrFdzWDX5LOGbnV2WKiDmyIoBhcqAn2LUNbk48m1QGY,1810
+ai_agent/mcp_loader.py,sha256=vE5JFw2h8eYglYqpmoodfrF53w0w2xWzSdNreEoBGWY,3754
+ai_agent/react_tool_turn.py,sha256=4eIT2e_2refTtPHS6fD_GkawA2UcJtCdylPsGxwOf_o,1514
+ai_agent/tools.py,sha256=Zm4frKT2TskIUeBMbiwEgrIFHxFOhoLbEOnOdJy0thA,4314
+ai_agent/app/__init__.py,sha256=WKbCB3qLOlnjaXA_3CRWcEhd5n9B8_VquaSzhYUySC0,254
+ai_agent/app/_workspace.py,sha256=5sXJVk7pN6oAmo683_jV20X04NPhNuDwHGgKMYPfuZQ,3867
+ai_agent/app/app.py,sha256=Ujd-nPteRaWWcZxCpPZ4ykh8ZBRIWH1aCgOh6PDLQLU,13037
+ai_agent/app/harness_io.py,sha256=TU6N1wJLSdBfx8T6CRXB05DrhN7kAToCNXcAF84_M_0,3164
+ai_agent/app/output_format.py,sha256=HL5Nx7PxYzvMP13d_cqvDLbY0ayHiRZjer07SHO-7m4,3612
+ai_agent/app/packet.py,sha256=oouF2y6BTzVWkUxB-5nC3K-wFO6NOX8r9JoTFrxl0jA,1588
+ai_agent/app/session.py,sha256=oW88fxYzjW7f3kGZIJn1xrL45n1y2GDqFcw4ckORDsE,14457
+ai_agent/app/session_store.py,sha256=XBPAyjdMG0i2wK9l9s0W_rejEHHXQXaxpfvRhBPKJ8Q,2352
+ai_agent/builtin_tools/__init__.py,sha256=0qKNyfLu5qvKwXY4KaG6oqZbPMkChZ-5EzMWXTKqrD0,541
+ai_agent/builtin_tools/current_time.py,sha256=m66y7rzGEK5s9fB2zUdphEI7BUgLlqqxsbqCM_6_Rq0,1214
+ai_agent/builtin_tools/pack.py,sha256=ZcI92hZqWe9BFx7cL9Hc3wQ64Enydy0-0QX60b8yUx8,583
+ai_agent/builtin_tools/prefix.py,sha256=k0XOKMXLZHTxSQvhhTRU1YKmWx0zTqTcLTHkz3-O4iY,348
+ai_agent/harness/__init__.py,sha256=E9KxDIRTs6kpijAj46aO3V3rUxyrAUQaWj50Zn0BYdk,71
+ai_agent/harness/current_time.py,sha256=mWV1ro7KRSsvbS0Mj0ra-sxKuK0QSQUsknfkiIEhufs,721
+ai_agent/harness/harness.py,sha256=UVEXDJXUW7uQNvUzSOyh-PjIUB00nd5ZSkwpk0P-96k,12208
+ai_agent/harness/process.py,sha256=dFdF80ahZTC7AYwbYQMqVwbRfDKRqA8nGoQHw5-mDIU,3186
+ai_agent/harness/prompts.py,sha256=jdfOZ_xca4A_9WkgmoYOAfNDzTlc87YsdNmOfYaY1ic,2261
+ai_agent/harness/sandbox.py,sha256=ir19YqCTtytI9WjTJZzbUR4B7tMU2hhg7SxGvSK4GDo,4693
+ai_agent/memory/__init__.py,sha256=7t0iTqF_TNri-uJu92zDIUHTqUBM2PB6GTu9ky3_rkg,256
+ai_agent/memory/compression_work.py,sha256=jjravGtme7xc73HA3bCk3S7VZt1M93YKWVID3qTstdE,1376
+ai_agent/memory/compressor.py,sha256=31pgoSSIlc3FcBpcUBFgsA0_WxX0TCWDkX3_efQYvQQ,12002
+ai_agent/memory/config.py,sha256=gOMjFufb_62e0eglCHFowqDWn7sSCodgcMa5jubLCh8,1210
+ai_agent/memory/context_builder.py,sha256=GHJ41OLFwjMixqEjzCpRgNgiScZFZNsRWwYjI6AryqM,2164
+ai_agent/memory/memory_system.py,sha256=S0npW_HYoWdkl7In6Iy4G0l5sgkGlsuRfiwrherOrac,10446
+ai_agent/memory/models.py,sha256=YSxkKe-z81IMV9cqWHQtZnsppfIqA_zem7NHAmAURq0,2376
+ai_agent/memory/snapshot_merge.py,sha256=QQ8C4cZSq6YTCUIY0d5Vbdl3VeIxbPKOMmE28pt2ygE,5130
+ai_agent/memory/store.py,sha256=z-2ST-3Ff7GMybucIPvVUSZafCftbZK1K8IGEsXjJ_M,3490
+ai_agent/memory/worker.py,sha256=3Wui0h8KAtXxRpVVm9R2jIU_LRheJVr0l4xIb9UyIpk,7231
+ai_agent/plan/__init__.py,sha256=JIUYfRuLwC2tr8EHrYmTyjD6hCRWdOmssZtd38Ew71s,426
+ai_agent/plan/complete.py,sha256=kp8N36ueOKpid4r73l6MynunLKag6jaai9ZlDKgXWEk,2314
+ai_agent/plan/delivery.py,sha256=imA_bVx2koq2Yh3JPHCNCJV8C67vmFSyoNTsG65S0e0,1462
+ai_agent/plan/display.py,sha256=UJYsZt56bH76UnkzEQChBGCVYU_0kvEXaBQ9_qBcudc,1484
+ai_agent/plan/models.py,sha256=5CfBymIGu8eLxxZneVbCtXSlueP3N3OQOlV-YNv9nfA,1590
+ai_agent/plan/parse.py,sha256=KOPxup_ZkKap93T09dZ2r75D2MBJ4cZxdmWB7vzks8o,1169
+ai_agent/plan/planner.py,sha256=GA2iAYjZSdaPeZO49EA315lbuE2RoZQCyabPCSm9kKU,4199
+ai_agent/plan/runner.py,sha256=pRjw1o_LEFIXS1WG4RatopXZJDJyimWQ5MXipL3muuc,9473
+ai_agent/rule/__init__.py,sha256=NBOekmeJSWo8yBqLCAqsNl6RGpmp-PExcsy1w-qXOrU,66
+ai_agent/rule/rules.py,sha256=SRHbuaIW3oJlNz3VbwIeXuY3saxxvnaQa7ts3c_41PE,1269
+ai_agent/skill/__init__.py,sha256=d15lKS6jd4ZO6UNaYP3UHHc2XVLsMjvdiwtTPc3Hfvo,226
+ai_agent/skill/builtin_registry.py,sha256=7azSyzFA82MjXgf9jTz89nexExSZmQhtgkoaTlTGqM4,1658
+ai_agent/skill/catalog.py,sha256=_FfOTXsfOV6i_bAf7sYZngKFTGRu-LaAjnoVuWDhE3Q,3068
+ai_agent/skill/frontmatter.py,sha256=TcT534tfbTyVRDWK_2qrmub40SyNJ18o1G427PQ4EGU,2351
+ai_agent/skill/manager.py,sha256=uecIs89xObK8ZFG9QKbjVqNUKFKzljkWu6Rutpnz77Q,18835
+ai_agent/skill/models.py,sha256=GDh_LnU4XgACIt11iETdPCmOBUTiq7tA2f82j0BMj_c,835
+ai_agent/skill/roots.py,sha256=XcpuXffTy3MMVIWnc10zwZ4mZjF6bDtQd9LSismoFg4,5485
+ai_agent/skill/skill_kit.py,sha256=yaySLLD7VZu3hQ_GMOE5G7Yq5ax0EWlDIyfRvOZGrzs,2653
+ai_agent/skill/tool_declarations.py,sha256=dSqiXRh-VgiUkDC4BLDzvCBNGcsTv1e_XMy6fmrIBCE,2093
+python_library_ai_agent-0.1.0.dist-info/METADATA,sha256=niPh6IxfThtXDq_PK2OdHIBoI5SO4Cyy93kj-p6rvd8,284
+python_library_ai_agent-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+python_library_ai_agent-0.1.0.dist-info/RECORD,,

python_library_ai_agent-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any