auto-agent-kit 0.1.0__tar.gz → 0.2.0__tar.gz

{auto_agent_kit-0.1.0 → auto_agent_kit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: auto-agent-kit
-Version: 0.1.0
+Version: 0.2.0
 Summary: A practical Python toolkit for building production-grade AI agents with Plan-Execute, Error Reflection, Tool Routing, Dashboard, Access Control, and MCP Server.
 Author-email: AoLongZhiZun <2480528492@qq.com>
 License: MIT

{auto_agent_kit-0.1.0 → auto_agent_kit-0.2.0}/auto_agent_kit/__init__.py

@@ -1,18 +1,22 @@
 """AutoAgentKit — 生产级 AI Agent 工具包"""
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
-from auto_agent_kit.core.plan_mode import PlanMode
+from auto_agent_kit.core.plan_mode import PlanMode, ExecutionPlan, PlanStep, StepStatus
 from auto_agent_kit.core.error_reflection import ErrorReflection, ErrorCategory, RecoveryStrategy
 from auto_agent_kit.core.tool_router import ToolRouter, ToolPhase
 from auto_agent_kit.core.dashboard import Dashboard
 from auto_agent_kit.core.access_control import AccessControl, PermissionLevel
 from auto_agent_kit.core.mcp_server import MCPServer
+from auto_agent_kit.core.plugin import Plugin, PluginManager, LoggingPlugin, MetricsPlugin
+from auto_agent_kit.core.async_plan import AsyncPlanMode, AsyncStepResult, run_plan
 
 __all__ = [
-    "PlanMode",
+    "PlanMode", "ExecutionPlan", "PlanStep", "StepStatus",
     "ErrorReflection", "ErrorCategory", "RecoveryStrategy",
     "ToolRouter", "ToolPhase",
     "Dashboard",
     "AccessControl", "PermissionLevel",
     "MCPServer",
+    "Plugin", "PluginManager", "LoggingPlugin", "MetricsPlugin",
+    "AsyncPlanMode", "AsyncStepResult", "run_plan",
 ]

auto_agent_kit-0.2.0/auto_agent_kit/core/async_plan.py

@@ -0,0 +1,177 @@
+"""AsyncPlan — 异步计划执行模式
+
+支持异步步骤执行、并发步骤、超时控制。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional
+
+from auto_agent_kit.core.plan_mode import ExecutionPlan, PlanStep, PlanMode, StepStatus
+
+
+@dataclass
+class AsyncStepResult:
+    """异步步骤执行结果"""
+    step_id: str
+    status: str
+    result: Any = None
+    error: Optional[str] = None
+    duration_ms: float = 0.0
+
+
+class AsyncPlanMode(PlanMode):
+    """异步计划执行模式 — 支持异步步骤和并发执行"""
+
+    def __init__(self, max_retries: int = 2, concurrency_limit: int = 3):
+        super().__init__(max_retries)
+        self.concurrency_limit = concurrency_limit
+        self._semaphore = asyncio.Semaphore(concurrency_limit)
+
+    async def execute_step_async(
+        self,
+        step: PlanStep,
+        executor: Callable[[str], Any],
+    ) -> AsyncStepResult:
+        """异步执行单个步骤"""
+        start = time.time()
+        self.start_step(step.id)
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                async with self._semaphore:
+                    if asyncio.iscoroutinefunction(executor):
+                        result = await executor(step.description)
+                    else:
+                        result = executor(step.description)
+                self.complete_step(step.id, result)
+                duration_ms = (time.time() - start) * 1000
+                return AsyncStepResult(
+                    step_id=step.id,
+                    status="ok",
+                    result=result,
+                    duration_ms=duration_ms,
+                )
+            except Exception as e:
+                if attempt < self.max_retries:
+                    await asyncio.sleep(2 ** attempt)  # 指数退避
+                    continue
+                self.fail_step(step.id, str(e))
+                duration_ms = (time.time() - start) * 1000
+                return AsyncStepResult(
+                    step_id=step.id,
+                    status="failed",
+                    error=str(e),
+                    duration_ms=duration_ms,
+                )
+
+    async def execute_sequentially_async(
+        self,
+        executor: Callable[[str], Any],
+        plan: Optional[ExecutionPlan] = None,
+    ) -> list[AsyncStepResult]:
+        """异步顺序执行所有步骤"""
+        plan = plan or self.current_plan
+        if not plan:
+            return []
+
+        results = []
+        for step in plan.steps:
+            result = await self.execute_step_async(step, executor)
+            results.append(result)
+        return results
+
+    async def execute_concurrently_async(
+        self,
+        executor: Callable[[str], Any],
+        plan: Optional[ExecutionPlan] = None,
+    ) -> list[AsyncStepResult]:
+        """并发执行无依赖的步骤
+
+        按依赖关系分批执行：同一批次的步骤可以并发运行。
+        """
+        plan = plan or self.current_plan
+        if not plan:
+            return []
+
+        results: list[AsyncStepResult] = []
+        completed_ids: set[str] = set()
+        pending = list(plan.steps)
+
+        while pending:
+            # 找出当前批次可执行的步骤（依赖已完成的）
+            batch = []
+            remaining = []
+            for step in pending:
+                deps = set(step.dependencies)
+                if deps.issubset(completed_ids):
+                    batch.append(step)
+                else:
+                    remaining.append(step)
+
+            if not batch:
+                # 死锁检测：有步骤但都不满足依赖
+                for step in remaining:
+                    results.append(AsyncStepResult(
+                        step_id=step.id,
+                        status="failed",
+                        error=f"Deadlock: dependencies {step.dependencies} never completed",
+                    ))
+                break
+
+            # 并发执行批次
+            batch_results = await asyncio.gather(*[
+                self.execute_step_async(step, executor) for step in batch
+            ])
+
+            for r in batch_results:
+                results.append(r)
+                if r.status == "ok":
+                    completed_ids.add(r.step_id)
+
+            pending = remaining
+
+        return results
+
+    async def execute_with_timeout(
+        self,
+        executor: Callable[[str], Any],
+        step_description: str,
+        timeout_seconds: float = 30.0,
+    ) -> AsyncStepResult:
+        """带超时控制的步骤执行"""
+        step = PlanStep(id="timeout_step", description=step_description)
+        self.current_plan = ExecutionPlan(goal=step_description)
+        self.current_plan.steps = [step]
+
+        try:
+            result = await asyncio.wait_for(
+                self.execute_step_async(step, executor),
+                timeout=timeout_seconds,
+            )
+            return result
+        except asyncio.TimeoutError:
+            return AsyncStepResult(
+                step_id=step.id,
+                status="timeout",
+                error=f"Step timed out after {timeout_seconds}s",
+                duration_ms=timeout_seconds * 1000,
+            )
+
+
+# ── 辅助函数 ──
+
+async def run_plan(
+    plan_mode: AsyncPlanMode,
+    steps: list[str],
+    executor: Callable[[str], Any],
+    concurrent: bool = False,
+) -> list[AsyncStepResult]:
+    """便捷函数：创建计划并执行"""
+    plan = plan_mode.create_plan("async_plan", steps)
+    if concurrent:
+        return await plan_mode.execute_concurrently_async(executor, plan)
+    return await plan_mode.execute_sequentially_async(executor, plan)

auto_agent_kit-0.2.0/auto_agent_kit/core/plugin.py

@@ -0,0 +1,275 @@
+"""Plugin — 插件系统
+
+支持插件注册、生命周期钩子、事件系统。
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional
+
+
+class Plugin:
+    """插件基类"""
+
+    name: str = ""
+    version: str = "0.1.0"
+    description: str = ""
+
+    def on_register(self, kit: "PluginManager"):
+        """注册时调用"""
+        pass
+
+    def on_unregister(self):
+        """注销时调用"""
+        pass
+
+    def on_before_step(self, step: dict) -> dict:
+        """步骤执行前调用，可修改步骤"""
+        return step
+
+    def on_after_step(self, step: dict, result: Any) -> None:
+        """步骤执行后调用"""
+        pass
+
+    def on_error(self, error: Exception, context: dict) -> Optional[dict]:
+        """错误发生时调用，返回恢复建议或 None"""
+        return None
+
+    def on_metric(self, name: str, value: float) -> None:
+        """指标记录时调用"""
+        pass
+
+
+@dataclass
+class Hook:
+    """钩子定义"""
+    name: str
+    handler: Callable
+    priority: int = 0  # 数字越小优先级越高
+    plugin_name: str = ""
+
+
+class PluginManager:
+    """插件管理器"""
+
+    def __init__(self):
+        self._plugins: dict[str, Plugin] = {}
+        self._hooks: dict[str, list[Hook]] = {}
+        self._events: list[dict] = []
+        self._max_events: int = 200
+
+    # ── 插件生命周期 ──
+
+    def register(self, plugin: Plugin) -> bool:
+        """注册插件"""
+        if plugin.name in self._plugins:
+            return False
+        self._plugins[plugin.name] = plugin
+        plugin.on_register(self)
+        self._record_event("plugin_register", {"name": plugin.name, "version": plugin.version})
+        return True
+
+    def unregister(self, name: str) -> bool:
+        """注销插件"""
+        plugin = self._plugins.pop(name, None)
+        if plugin is None:
+            return False
+        plugin.on_unregister()
+        # 清理该插件的钩子
+        for hook_list in self._hooks.values():
+            hook_list[:] = [h for h in hook_list if h.plugin_name != name]
+        self._record_event("plugin_unregister", {"name": name})
+        return True
+
+    def get_plugin(self, name: str) -> Optional[Plugin]:
+        """获取插件"""
+        return self._plugins.get(name)
+
+    def list_plugins(self) -> list[dict]:
+        """列出所有插件"""
+        return [
+            {"name": p.name, "version": p.version, "description": p.description}
+            for p in self._plugins.values()
+        ]
+
+    def is_registered(self, name: str) -> bool:
+        """检查插件是否已注册"""
+        return name in self._plugins
+
+    # ── 钩子系统 ──
+
+    def add_hook(self, hook_name: str, handler: Callable, plugin_name: str = "", priority: int = 0):
+        """添加钩子"""
+        if hook_name not in self._hooks:
+            self._hooks[hook_name] = []
+        self._hooks[hook_name].append(Hook(
+            name=hook_name,
+            handler=handler,
+            priority=priority,
+            plugin_name=plugin_name,
+        ))
+        # 按优先级排序
+        self._hooks[hook_name].sort(key=lambda h: h.priority)
+
+    def remove_hook(self, hook_name: str, handler: Callable) -> bool:
+        """移除钩子"""
+        hook_list = self._hooks.get(hook_name, [])
+        before = len(hook_list)
+        hook_list[:] = [h for h in hook_list if h.handler != handler]
+        return len(hook_list) < before
+
+    def emit(self, hook_name: str, **kwargs) -> list[Any]:
+        """触发钩子，返回所有处理结果"""
+        results = []
+        for hook in self._hooks.get(hook_name, []):
+            try:
+                result = hook.handler(**kwargs)
+                results.append(result)
+            except Exception as e:
+                self._record_event("hook_error", {
+                    "hook": hook_name,
+                    "plugin": hook.plugin_name,
+                    "error": str(e),
+                })
+        return results
+
+    def has_hooks(self, hook_name: str) -> bool:
+        """检查是否有钩子"""
+        return bool(self._hooks.get(hook_name))
+
+    # ── 内置钩子快捷方式 ──
+
+    def on_before_step(self, step: dict) -> dict:
+        """触发 before_step 钩子"""
+        if self.has_hooks("before_step"):
+            results = self.emit("before_step", step=step)
+            for r in results:
+                if isinstance(r, dict):
+                    step = r
+        return step
+
+    def on_after_step(self, step: dict, result: Any):
+        """触发 after_step 钩子"""
+        if self.has_hooks("after_step"):
+            self.emit("after_step", step=step, result=result)
+
+    def on_error(self, error: Exception, context: dict) -> Optional[dict]:
+        """触发 error 钩子，返回第一个非 None 的恢复建议"""
+        if self.has_hooks("error"):
+            results = self.emit("error", error=error, context=context)
+            for r in results:
+                if r is not None:
+                    return r
+        return None
+
+    # ── 事件记录 ──
+
+    def _record_event(self, event_type: str, data: dict):
+        self._events.append({
+            "timestamp": time.time(),
+            "type": event_type,
+            "data": data,
+        })
+        if len(self._events) > self._max_events:
+            self._events = self._events[-self._max_events:]
+
+    def get_events(self, limit: int = 20) -> list[dict]:
+        """获取最近事件"""
+        return self._events[-limit:]
+
+    def get_stats(self) -> dict:
+        """获取插件统计"""
+        return {
+            "total_plugins": len(self._plugins),
+            "total_hooks": sum(len(h) for h in self._hooks.values()),
+            "hook_names": list(self._hooks.keys()),
+            "plugins": self.list_plugins(),
+        }
+
+
+# ── 内置插件 ──
+
+class LoggingPlugin(Plugin):
+    """日志插件 — 记录所有步骤和错误"""
+
+    name = "logging"
+    version = "1.0.0"
+    description = "记录所有步骤执行和错误信息"
+
+    def __init__(self):
+        self.logs: list[dict] = []
+        self._max_logs = 500
+
+    def on_before_step(self, step: dict) -> dict:
+        self.logs.append({
+            "time": time.time(),
+            "type": "step_start",
+            "step_id": step.get("id", ""),
+            "description": step.get("description", ""),
+        })
+        if len(self.logs) > self._max_logs:
+            self.logs = self.logs[-self._max_logs:]
+        return step
+
+    def on_after_step(self, step: dict, result: Any):
+        self.logs.append({
+            "time": time.time(),
+            "type": "step_end",
+            "step_id": step.get("id", ""),
+            "result": str(result)[:200],
+        })
+
+    def on_error(self, error: Exception, context: dict) -> None:
+        self.logs.append({
+            "time": time.time(),
+            "type": "error",
+            "error": str(error),
+            "context": context,
+        })
+
+    def get_recent_logs(self, limit: int = 10) -> list[dict]:
+        return self.logs[-limit:]
+
+
+class MetricsPlugin(Plugin):
+    """指标插件 — 自动收集 Dashboard 指标"""
+
+    name = "metrics"
+    version = "1.0.0"
+    description = "自动收集步骤耗时和错误率指标"
+
+    def __init__(self):
+        self.step_durations: list[float] = []
+        self.error_count = 0
+        self.step_count = 0
+
+    def on_after_step(self, step: dict, result: Any):
+        self.step_count += 1
+        if "duration" in step:
+            self.step_durations.append(step["duration"])
+
+    def on_error(self, error: Exception, context: dict) -> None:
+        self.error_count += 1
+
+    @property
+    def avg_duration(self) -> float:
+        if not self.step_durations:
+            return 0.0
+        return sum(self.step_durations) / len(self.step_durations)
+
+    @property
+    def error_rate(self) -> float:
+        if self.step_count == 0:
+            return 0.0
+        return self.error_count / self.step_count
+
+    def get_report(self) -> dict:
+        return {
+            "total_steps": self.step_count,
+            "total_errors": self.error_count,
+            "error_rate": self.error_rate,
+            "avg_duration_ms": self.avg_duration * 1000,
+            "total_duration_ms": sum(self.step_durations) * 1000,
+        }

{auto_agent_kit-0.1.0 → auto_agent_kit-0.2.0}/auto_agent_kit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: auto-agent-kit
-Version: 0.1.0
+Version: 0.2.0
 Summary: A practical Python toolkit for building production-grade AI agents with Plan-Execute, Error Reflection, Tool Routing, Dashboard, Access Control, and MCP Server.
 Author-email: AoLongZhiZun <2480528492@qq.com>
 License: MIT

{auto_agent_kit-0.1.0 → auto_agent_kit-0.2.0}/auto_agent_kit.egg-info/SOURCES.txt

@@ -9,10 +9,12 @@ auto_agent_kit.egg-info/requires.txt
 auto_agent_kit.egg-info/top_level.txt
 auto_agent_kit/core/__init__.py
 auto_agent_kit/core/access_control.py
+auto_agent_kit/core/async_plan.py
 auto_agent_kit/core/dashboard.py
 auto_agent_kit/core/error_reflection.py
 auto_agent_kit/core/mcp_server.py
 auto_agent_kit/core/plan_mode.py
+auto_agent_kit/core/plugin.py
 auto_agent_kit/core/tool_router.py
 auto_agent_kit/examples/demo.py
 tests/test_all.py

{auto_agent_kit-0.1.0 → auto_agent_kit-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "auto-agent-kit"
-version = "0.1.0"
+version = "0.2.0"
 description = "A practical Python toolkit for building production-grade AI agents with Plan-Execute, Error Reflection, Tool Routing, Dashboard, Access Control, and MCP Server."
 readme = "README.md"
 requires-python = ">=3.10"

{auto_agent_kit-0.1.0 → auto_agent_kit-0.2.0}/tests/test_all.py

@@ -7,9 +7,14 @@ from auto_agent_kit import (
     PlanMode, ErrorReflection, ErrorCategory, RecoveryStrategy,
     ToolRouter, ToolPhase, Dashboard, AccessControl, PermissionLevel,
     MCPServer,
+    Plugin, PluginManager, LoggingPlugin, MetricsPlugin,
+    AsyncPlanMode, AsyncStepResult, run_plan,
 )
 
 
+import asyncio
+
+
 def test_plan_mode():
     p = PlanMode()
     plan = p.create_plan("test", ["step1", "step2"])
@@ -151,6 +156,96 @@ def test_mcp_server():
     print("  ✅ MCPServer")
 
 
+def test_plugin_system():
+    pm = PluginManager()
+
+    # 注册插件
+    log_plugin = LoggingPlugin()
+    assert pm.register(log_plugin) is True
+    assert pm.register(log_plugin) is False  # 重复注册
+    assert pm.is_registered("logging") is True
+
+    # 插件列表
+    plugins = pm.list_plugins()
+    assert len(plugins) == 1
+    assert plugins[0]["name"] == "logging"
+
+    # 钩子系统
+    def custom_hook(step: dict):
+        step["modified"] = True
+        return step
+
+    pm.add_hook("before_step", custom_hook, "test", priority=10)
+    assert pm.has_hooks("before_step") is True
+
+    # 触发钩子
+    result = pm.on_before_step({"id": "1", "description": "test"})
+    assert result["modified"] is True
+
+    # 错误钩子
+    pm.on_error(Exception("test error"), {"step": "1"})
+
+    # 移除钩子
+    assert pm.remove_hook("before_step", custom_hook) is True
+
+    # 统计
+    stats = pm.get_stats()
+    assert stats["total_plugins"] == 1
+    assert stats["total_hooks"] >= 0
+
+    # 注销
+    assert pm.unregister("logging") is True
+    assert pm.is_registered("logging") is False
+    print("  ✅ PluginSystem")
+
+
+def test_metrics_plugin():
+    mp = MetricsPlugin()
+    mp.on_after_step({"id": "1", "duration": 0.1}, "ok")
+    mp.on_after_step({"id": "2", "duration": 0.2}, "ok")
+    mp.on_error(Exception("fail"), {})
+
+    report = mp.get_report()
+    assert report["total_steps"] == 2
+    assert report["total_errors"] == 1
+    assert report["error_rate"] == 0.5
+    assert abs(report["avg_duration_ms"] - 150.0) < 0.001
+    print("  ✅ MetricsPlugin")
+
+
+def test_async_plan():
+    async def run():
+        ap = AsyncPlanMode(max_retries=1, concurrency_limit=2)
+
+        def executor(desc: str) -> str:
+            return f"done: {desc}"
+
+        results = await run_plan(ap, ["step1", "step2", "step3"], executor)
+        assert len(results) == 3
+        assert all(r.status == "ok" for r in results)
+        assert results[0].result == "done: step1"
+
+        # 并发执行
+        ap2 = AsyncPlanMode()
+        plan = ap2.create_plan("concurrent", ["a", "b", "c"])
+        concurrent_results = await ap2.execute_concurrently_async(executor, plan)
+        assert len(concurrent_results) == 3
+        assert all(r.status == "ok" for r in concurrent_results)
+
+        # 超时测试
+        async def slow_executor(desc: str) -> str:
+            await asyncio.sleep(10)
+            return "slow"
+
+        timeout_result = await ap2.execute_with_timeout(slow_executor, "slow", 0.1)
+        assert timeout_result.status == "timeout"
+
+        return True
+
+    assert asyncio.run(run()) is True
+    print("  ✅ AsyncPlan")
+
+
 if __name__ == "__main__":
     print("AutoAgentKit 测试\n")
     test_plan_mode()
@@ -159,4 +254,7 @@ if __name__ == "__main__":
     test_dashboard()
     test_access_control()
     test_mcp_server()
+    test_plugin_system()
+    test_metrics_plugin()
+    test_async_plan()
     print("\n全部测试通过 ✅")