loom-agent 0.0.1__py3-none-any.whl

loom/patterns/multi_agent.py

@@ -0,0 +1,123 @@
+"""Multi-Agent 系统 - 支持多个 Agent 协作完成复杂任务"""
+
+from __future__ import annotations
+
+from typing import Dict, Optional
+
+from loom.components.agent import Agent
+from loom.interfaces.llm import BaseLLM
+
+
+class MultiAgentSystem:
+    """
+    Multi-Agent 协作系统
+
+    支持:
+    - 多个专业 Agent 协同工作
+    - 协调器 LLM 进行任务分解和结果汇总
+    - Agent 间通信与数据传递
+    """
+
+    def __init__(
+        self,
+        agents: Dict[str, Agent],
+        coordinator: Optional[BaseLLM] = None,
+    ) -> None:
+        self.agents = agents
+        self.coordinator = coordinator
+
+    async def run(self, task: str) -> str:
+        """
+        执行多 Agent 任务
+
+        工作流程:
+        1. 协调器分解任务 (如果有)
+        2. 分配子任务给不同 Agent
+        3. 汇总结果
+        """
+        if not self.coordinator:
+            # 简单模式:顺序执行所有 Agent
+            results = {}
+            for name, agent in self.agents.items():
+                result = await agent.run(f"As {name}, help with: {task}")
+                results[name] = result
+
+            return self._format_results(results)
+
+        # 协调模式:使用协调器分解任务
+        subtasks = await self._decompose_task(task)
+
+        results = {}
+        for subtask in subtasks:
+            agent_name = subtask.get("agent")
+            subtask_desc = subtask.get("task", task)
+
+            if agent_name and agent_name in self.agents:
+                result = await self.agents[agent_name].run(subtask_desc)
+                results[agent_name] = result
+
+        # 汇总结果
+        return await self._aggregate_results(task, results)
+
+    async def _decompose_task(self, task: str) -> list[dict]:
+        """使用协调器分解任务"""
+        if not self.coordinator:
+            return [{"agent": list(self.agents.keys())[0], "task": task}]
+
+        agent_list = ", ".join(self.agents.keys())
+        decompose_prompt = f"""You are a task coordinator for a multi-agent system.
+
+Available agents: {agent_list}
+
+Task: {task}
+
+Decompose this task into subtasks and assign each to the most appropriate agent.
+Return a JSON list like:
+[
+  {{"agent": "agent_name", "task": "subtask description"}},
+  ...
+]
+"""
+
+        response = await self.coordinator.generate([{"role": "user", "content": decompose_prompt}])
+
+        # 简单解析 (实际应该用 JSON)
+        import json
+
+        try:
+            subtasks = json.loads(response)
+            if isinstance(subtasks, list):
+                return subtasks
+        except Exception:
+            pass
+
+        # 降级:单个任务
+        return [{"agent": list(self.agents.keys())[0], "task": task}]
+
+    async def _aggregate_results(self, original_task: str, results: Dict[str, str]) -> str:
+        """汇总各 Agent 的结果"""
+        if not self.coordinator:
+            return self._format_results(results)
+
+        results_text = "\n\n".join([f"**{name}**: {result}" for name, result in results.items()])
+
+        aggregate_prompt = f"""You are a task coordinator for a multi-agent system.
+
+Original task: {original_task}
+
+Results from agents:
+{results_text}
+
+Synthesize these results into a coherent final answer.
+"""
+
+        return await self.coordinator.generate([{"role": "user", "content": aggregate_prompt}])
+
+    def _format_results(self, results: Dict[str, str]) -> str:
+        """格式化结果"""
+        lines = ["## Multi-Agent Results\n"]
+        for name, result in results.items():
+            lines.append(f"### Agent: {name}")
+            lines.append(result)
+            lines.append("")
+        return "\n".join(lines)

loom/patterns/rag.py

@@ -0,0 +1,262 @@
+"""RAG Pattern - 完整的 Retrieval-Augmented Generation 编排"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from loom.components.agent import Agent
+from loom.interfaces.retriever import BaseRetriever, Document
+
+
+class RAGPattern:
+    """
+    RAG 编排模式 - 检索增强生成
+
+    完整的 RAG Pipeline:
+    1. 检索 (Retrieve) - 从知识库检索相关文档
+    2. 排序 (Rerank) - 可选的重排序步骤
+    3. 生成 (Generate) - 基于检索到的上下文生成答案
+
+    适用场景:
+    - 需要完整控制 RAG 流程
+    - 需要 Re-ranking
+    - 需要多轮迭代
+
+    示例:
+        rag = RAGPattern(
+            agent=agent,
+            retriever=retriever,
+            reranker=cross_encoder_rerank,
+            top_k=10,
+            rerank_top_k=3
+        )
+
+        result = await rag.run("What is Loom framework?")
+    """
+
+    def __init__(
+        self,
+        agent: Agent,
+        retriever: BaseRetriever,
+        reranker: Optional[callable] = None,
+        top_k: int = 5,
+        rerank_top_k: int = 3,
+    ):
+        """
+        Parameters:
+            agent: Agent 实例
+            retriever: 检索器实例
+            reranker: 可选的重排序函数 (query, docs) -> reranked_docs
+            top_k: 初始检索文档数量
+            rerank_top_k: 重排序后保留的文档数量
+        """
+        self.agent = agent
+        self.retriever = retriever
+        self.reranker = reranker
+        self.top_k = top_k
+        self.rerank_top_k = rerank_top_k
+
+    async def run(self, query: str) -> str:
+        """
+        执行完整的 RAG 流程
+
+        Parameters:
+            query: 用户查询
+
+        Returns:
+            生成的答案
+        """
+        # Step 1: 检索相关文档
+        docs = await self.retriever.retrieve(query, top_k=self.top_k)
+
+        if not docs:
+            # 没有检索到文档,直接让 Agent 回答
+            return await self.agent.run(query)
+
+        # Step 2: Re-ranking (可选)
+        if self.reranker:
+            docs = await self.reranker(query, docs)
+            docs = docs[:self.rerank_top_k]
+
+        # Step 3: 构建增强查询
+        augmented_query = self._build_augmented_query(query, docs)
+
+        # Step 4: Agent 生成答案
+        return await self.agent.run(augmented_query)
+
+    def _build_augmented_query(self, query: str, docs: List[Document]) -> str:
+        """
+        构建增强查询 - 将检索到的文档与查询组合
+
+        Parameters:
+            query: 原始查询
+            docs: 检索到的文档列表
+
+        Returns:
+            增强后的查询字符串
+        """
+        if not docs:
+            return query
+
+        context_parts = []
+        for i, doc in enumerate(docs, 1):
+            # 格式化文档
+            doc_text = f"[Document {i}]"
+            if doc.metadata and doc.metadata.get("source"):
+                doc_text += f"\nSource: {doc.metadata['source']}"
+            doc_text += f"\n{doc.content}"
+
+            context_parts.append(doc_text)
+
+        context = "\n\n".join(context_parts)
+
+        return f"""Based on the following context, please answer the question accurately and concisely.
+
+Context:
+{context}
+
+Question: {query}
+
+Answer:"""
+
+
+class MultiQueryRAG(RAGPattern):
+    """
+    多查询 RAG - 生成多个查询变体并合并结果
+
+    适用场景:
+    - 复杂查询需要多角度检索
+    - 提高召回率
+
+    示例:
+        rag = MultiQueryRAG(
+            agent=agent,
+            retriever=retriever,
+            query_count=3
+        )
+
+        result = await rag.run("How does context engineering work?")
+        # 会生成 3 个查询变体,分别检索后合并
+    """
+
+    def __init__(
+        self,
+        agent: Agent,
+        retriever: BaseRetriever,
+        reranker: Optional[callable] = None,
+        top_k: int = 5,
+        rerank_top_k: int = 3,
+        query_count: int = 3,
+    ):
+        super().__init__(agent, retriever, reranker, top_k, rerank_top_k)
+        self.query_count = query_count
+
+    async def run(self, query: str) -> str:
+        """执行多查询 RAG 流程"""
+        # Step 1: 生成查询变体
+        queries = await self._generate_query_variants(query)
+
+        # Step 2: 并发检索
+        all_docs: List[Document] = []
+        for q in queries:
+            docs = await self.retriever.retrieve(q, top_k=self.top_k // len(queries))
+            all_docs.extend(docs)
+
+        # Step 3: 去重与排序
+        unique_docs = self._deduplicate_docs(all_docs)
+
+        # Step 4: Re-ranking (可选)
+        if self.reranker:
+            unique_docs = await self.reranker(query, unique_docs)
+
+        # Step 5: 生成答案
+        augmented_query = self._build_augmented_query(query, unique_docs[:self.rerank_top_k])
+        return await self.agent.run(augmented_query)
+
+    async def _generate_query_variants(self, query: str) -> List[str]:
+        """
+        生成查询变体
+
+        简单策略:
+        - 原始查询
+        - 改写查询 (更具体)
+        - 相关问题
+        """
+        variants = [query]
+
+        # 使用 Agent 生成变体查询
+        prompt = f"""Generate {self.query_count - 1} alternative search queries for: "{query}"
+
+Return only the queries, one per line, without numbering or explanation."""
+
+        try:
+            response = await self.agent.run(prompt)
+            lines = [line.strip() for line in response.split("\n") if line.strip()]
+            variants.extend(lines[:self.query_count - 1])
+        except Exception:
+            # 生成失败,只使用原始查询
+            pass
+
+        return variants[:self.query_count]
+
+    def _deduplicate_docs(self, docs: List[Document]) -> List[Document]:
+        """
+        去重文档
+
+        简单策略: 基于内容去重
+        """
+        seen_content = set()
+        unique_docs = []
+
+        for doc in docs:
+            # 使用内容的前 100 个字符作为唯一标识
+            key = doc.content[:100]
+
+            if key not in seen_content:
+                seen_content.add(key)
+                unique_docs.append(doc)
+
+        return unique_docs
+
+
+class HierarchicalRAG(RAGPattern):
+    """
+    层次化 RAG - 先检索文档,再检索段落
+
+    适用场景:
+    - 文档很长,需要两级检索
+    - 需要更精确的定位
+
+    流程:
+    1. 检索相关文档 (粗粒度)
+    2. 在检索到的文档内检索段落 (细粒度)
+    3. 基于段落生成答案
+    """
+
+    def __init__(
+        self,
+        agent: Agent,
+        document_retriever: BaseRetriever,
+        paragraph_retriever: Optional[BaseRetriever] = None,
+        doc_top_k: int = 5,
+        para_top_k: int = 3,
+    ):
+        super().__init__(agent, document_retriever, top_k=doc_top_k)
+        self.paragraph_retriever = paragraph_retriever or document_retriever
+        self.para_top_k = para_top_k
+
+    async def run(self, query: str) -> str:
+        """执行层次化 RAG"""
+        # Step 1: 检索文档
+        docs = await self.retriever.retrieve(query, top_k=self.top_k)
+
+        if not docs:
+            return await self.agent.run(query)
+
+        # Step 2: 在检索到的文档内检索段落
+        # 简化实现: 直接使用检索到的文档
+        paragraphs = docs[:self.para_top_k]
+
+        # Step 3: 生成答案
+        augmented_query = self._build_augmented_query(query, paragraphs)
+        return await self.agent.run(augmented_query)

loom/plugins/registry.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Type
+
+from loom.interfaces.llm import BaseLLM
+from loom.interfaces.memory import BaseMemory
+from loom.interfaces.tool import BaseTool
+
+
+class PluginRegistry:
+    """插件注册中心：注册/获取 LLM、Tool、Memory 实现。"""
+
+    _llms: Dict[str, Type[BaseLLM]] = {}
+    _tools: Dict[str, Type[BaseTool]] = {}
+    _memories: Dict[str, Type[BaseMemory]] = {}
+
+    @classmethod
+    def register_llm(cls, name: str):
+        def decorator(impl: Type[BaseLLM]):
+            cls._llms[name] = impl
+            return impl
+        return decorator
+
+    @classmethod
+    def register_tool(cls, name: str):
+        def decorator(impl: Type[BaseTool]):
+            cls._tools[name] = impl
+            return impl
+        return decorator
+
+    @classmethod
+    def register_memory(cls, name: str):
+        def decorator(impl: Type[BaseMemory]):
+            cls._memories[name] = impl
+            return impl
+        return decorator
+
+    @classmethod
+    def get_llm(cls, name: str, **kwargs: Any) -> BaseLLM:
+        if name not in cls._llms:
+            raise ValueError(f"LLM '{name}' not registered")
+        return cls._llms[name](**kwargs)
+
+    @classmethod
+    def get_tool(cls, name: str, **kwargs: Any) -> BaseTool:
+        if name not in cls._tools:
+            raise ValueError(f"Tool '{name}' not registered")
+        return cls._tools[name](**kwargs)
+
+    @classmethod
+    def get_memory(cls, name: str, **kwargs: Any) -> BaseMemory:
+        if name not in cls._memories:
+            raise ValueError(f"Memory '{name}' not registered")
+        return cls._memories[name](**kwargs)
+

loom/resilience/__init__.py

@@ -0,0 +1,5 @@
+"""Resilience subsystem - circuit breakers, retry logic, error handling"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

loom/tooling.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+from typing import Any, Callable, Optional, Type
+
+from pydantic import BaseModel, create_model
+
+from .interfaces.tool import BaseTool
+
+
+def tool(
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    args_schema: Optional[Type[BaseModel]] = None,
+    *,
+    concurrency_safe: bool = True,
+) -> Callable[[Callable[..., Any]], Type[BaseTool]]:
+    """Decorator to turn a Python function into a Loom Tool.
+
+    Example:
+        @tool()
+        def add(a: int, b: int) -> int:
+            # Add two integers
+            return a + b
+
+        AddTool = add  # class deriving BaseTool
+        my_tool = AddTool()
+    """
+
+    def wrapper(fn: Callable[..., Any]) -> Type[BaseTool]:
+        tool_name = name or fn.__name__
+        tool_desc = description or (inspect.getdoc(fn) or tool_name)
+        schema = args_schema or _infer_args_schema(fn, tool_name)
+        is_async = inspect.iscoroutinefunction(fn)
+
+        class _FuncTool(BaseTool):  # type: ignore[override]
+            name = tool_name
+            description = tool_desc
+            args_schema = schema
+
+            async def run(self, **kwargs) -> Any:  # type: ignore[override]
+                if is_async:
+                    return await fn(**kwargs)  # type: ignore[misc]
+                # Best-effort: offload to default executor to avoid blocking
+                loop = asyncio.get_running_loop()
+                return await loop.run_in_executor(None, lambda: fn(**kwargs))
+
+            @property
+            def is_concurrency_safe(self) -> bool:  # type: ignore[override]
+                return concurrency_safe
+
+        _FuncTool.__name__ = f"{tool_name.capitalize()}Tool"
+        return _FuncTool
+
+    return wrapper
+
+
+def _infer_args_schema(fn: Callable[..., Any], tool_name: str) -> Type[BaseModel]:
+    sig = inspect.signature(fn)
+    fields = {}
+    for name, param in sig.parameters.items():
+        if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+            continue
+        annotation = param.annotation if param.annotation is not inspect._empty else Any
+        default = ... if param.default is inspect._empty else param.default
+        fields[name] = (annotation, default)
+    if not fields:
+        # no-arg tool
+        return create_model(f"{tool_name}_Args", __base__=BaseModel)  # type: ignore
+    return create_model(f"{tool_name}_Args", __base__=BaseModel, **fields)  # type: ignore
+