loom-agent 0.0.1__py3-none-any.whl

loom/interfaces/compressor.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import List, Tuple
+
+from loom.core.types import Message, CompressionMetadata
+
+
+class BaseCompressor(ABC):
+    """Context compression interface (US2-compatible).
+
+    Updated in v4.0.0 to return compression metadata alongside compressed messages.
+
+    Migration Note:
+        Old interface (v3.0.1):
+            async def compress(self, messages) -> List[Message]
+
+        New interface (v4.0.0):
+            async def compress(self, messages) -> Tuple[List[Message], CompressionMetadata]
+
+    For custom compressor implementations, update your compress() method to return
+    a tuple: (compressed_messages, metadata).
+    """
+
+    @abstractmethod
+    async def compress(
+        self, messages: List[Message]
+    ) -> Tuple[List[Message], CompressionMetadata]:
+        """Compress messages and return metadata.
+
+        Args:
+            messages: List of messages to compress
+
+        Returns:
+            Tuple of (compressed_messages, compression_metadata)
+
+        Example:
+            compressed_msgs, metadata = await compressor.compress(history)
+            print(f"Reduced tokens: {metadata.original_tokens} → {metadata.compressed_tokens}")
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def should_compress(self, token_count: int, max_tokens: int) -> bool:
+        """Check if compression should be triggered.
+
+        Args:
+            token_count: Current context token count
+            max_tokens: Maximum allowed context tokens
+
+        Returns:
+            True if compression should be triggered (typically at 92% threshold)
+
+        Example:
+            if compressor.should_compress(15000, 16000):  # 93.75% usage
+                compressed, metadata = await compressor.compress(history)
+        """
+        raise NotImplementedError
+

loom/interfaces/embedding.py

@@ -0,0 +1,51 @@
+"""Embedding 接口定义"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import List
+
+
+class BaseEmbedding(ABC):
+    """
+    Embedding 基类
+
+    文本向量化的统一接口，支持：
+    - 单个文本向量化（查询）
+    - 批量文本向量化（文档）
+    """
+
+    @abstractmethod
+    async def embed_query(self, text: str) -> List[float]:
+        """
+        对单个查询文本进行向量化
+
+        Parameters:
+            text: 查询文本
+
+        Returns:
+            向量（浮点数列表）
+        """
+        pass
+
+    @abstractmethod
+    async def embed_documents(self, texts: List[str]) -> List[List[float]]:
+        """
+        批量向量化文档
+
+        Parameters:
+            texts: 文本列表
+
+        Returns:
+            向量列表，与输入文本列表一一对应
+        """
+        pass
+
+    def get_dimension(self) -> int:
+        """
+        返回向量维度
+
+        Returns:
+            向量的维度（例如 384, 768, 1536）
+        """
+        raise NotImplementedError("Subclasses should implement get_dimension()")

loom/interfaces/llm.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import AsyncGenerator, Dict, List
+
+
+class BaseLLM(ABC):
+    """LLM 基础接口 - 所有 LLM 提供者必须实现"""
+
+    @abstractmethod
+    async def generate(self, messages: List[Dict]) -> str:
+        """非流式生成一个完整响应。"""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def stream(self, messages: List[Dict]) -> AsyncGenerator[str, None]:
+        """流式生成响应内容增量。"""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def generate_with_tools(self, messages: List[Dict], tools: List[Dict]) -> Dict:
+        """带工具调用的生成（返回可能包含 tool_calls 等结构）。"""
+        raise NotImplementedError
+
+    @property
+    @abstractmethod
+    def model_name(self) -> str:
+        raise NotImplementedError
+
+    @property
+    def supports_tools(self) -> bool:
+        return False
+

loom/interfaces/memory.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import List, Optional
+
+from loom.core.types import Message
+
+
+class BaseMemory(ABC):
+    """对话/状态内存接口。"""
+
+    @abstractmethod
+    async def add_message(self, message: Message) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def get_messages(self, limit: Optional[int] = None) -> List[Message]:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def clear(self) -> None:
+        raise NotImplementedError
+
+    async def save(self, path: str) -> None:  # 可选
+        return None
+
+    async def load(self, path: str) -> None:  # 可选
+        return None
+

loom/interfaces/retriever.py

@@ -0,0 +1,179 @@
+"""检索器接口 - RAG 系统的基础抽象"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class Document(BaseModel):
+    """
+    文档数据模型
+
+    表示从知识库检索到的文档片段
+    """
+
+    content: str = Field(description="文档内容")
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="文档元数据")
+    score: Optional[float] = Field(default=None, description="相关性分数 (0-1)")
+    doc_id: Optional[str] = Field(default=None, description="文档唯一标识")
+
+    def __str__(self) -> str:
+        source = self.metadata.get("source", "Unknown")
+        return f"Document(source={source}, score={self.score}, len={len(self.content)})"
+
+    def format(self, max_length: int = 500) -> str:
+        """格式化文档用于显示"""
+        lines = []
+        if self.metadata.get("source"):
+            lines.append(f"**Source**: {self.metadata['source']}")
+        if self.score is not None:
+            lines.append(f"**Relevance**: {self.score:.2%}")
+
+        content = self.content
+        if len(content) > max_length:
+            content = content[:max_length] + "..."
+        lines.append(content)
+
+        return "\n".join(lines)
+
+
+class BaseRetriever(ABC):
+    """
+    检索器基础接口
+
+    所有检索器必须实现此接口:
+    - VectorStoreRetriever (向量检索)
+    - BM25Retriever (关键词检索)
+    - HybridRetriever (混合检索)
+    """
+
+    @abstractmethod
+    async def retrieve(
+        self,
+        query: str,
+        top_k: int = 5,
+        filters: Optional[Dict[str, Any]] = None,
+    ) -> List[Document]:
+        """
+        检索相关文档
+
+        Parameters:
+            query: 查询字符串
+            top_k: 返回文档数量
+            filters: 过滤条件 (例如: {"source": "doc.pdf"})
+
+        Returns:
+            按相关性排序的文档列表
+        """
+        pass
+
+    @abstractmethod
+    async def add_documents(
+        self,
+        documents: List[Document],
+    ) -> None:
+        """
+        添加文档到检索系统
+
+        Parameters:
+            documents: 要添加的文档列表
+        """
+        pass
+
+    async def add_texts(
+        self,
+        texts: List[str],
+        metadatas: Optional[List[Dict[str, Any]]] = None,
+    ) -> None:
+        """
+        便捷方法: 添加文本列表
+
+        Parameters:
+            texts: 文本列表
+            metadatas: 对应的元数据列表
+        """
+        if metadatas is None:
+            metadatas = [{} for _ in texts]
+
+        documents = [
+            Document(content=text, metadata=meta)
+            for text, meta in zip(texts, metadatas)
+        ]
+
+        await self.add_documents(documents)
+
+
+class BaseVectorStore(ABC):
+    """
+    向量存储基础接口
+
+    用于底层向量数据库的抽象:
+    - ChromaDB
+    - FAISS
+    - Pinecone
+    - Weaviate
+    """
+
+    @abstractmethod
+    async def similarity_search(
+        self,
+        query: str,
+        k: int = 5,
+        filters: Optional[Dict[str, Any]] = None,
+    ) -> List[Document]:
+        """
+        基于向量相似度搜索
+
+        Parameters:
+            query: 查询字符串 (会被自动向量化)
+            k: 返回结果数量
+            filters: 元数据过滤条件
+
+        Returns:
+            按相似度排序的文档列表
+        """
+        pass
+
+    @abstractmethod
+    async def add_texts(
+        self,
+        texts: List[str],
+        metadatas: Optional[List[Dict[str, Any]]] = None,
+    ) -> List[str]:
+        """
+        添加文本到向量存储
+
+        Parameters:
+            texts: 文本列表
+            metadatas: 元数据列表
+
+        Returns:
+            文档 ID 列表
+        """
+        pass
+
+    @abstractmethod
+    async def delete(self, ids: List[str]) -> None:
+        """删除文档"""
+        pass
+
+
+class BaseEmbedding(ABC):
+    """
+    嵌入模型接口
+
+    用于将文本转换为向量
+    """
+
+    @abstractmethod
+    async def embed_query(self, text: str) -> List[float]:
+        """生成查询向量"""
+        pass
+
+    @abstractmethod
+    async def embed_documents(self, texts: List[str]) -> List[List[float]]:
+        """批量生成文档向量"""
+        pass

loom/interfaces/tool.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class BaseTool(ABC):
+    """工具基础接口。"""
+
+    name: str
+    description: str
+    args_schema: type[BaseModel]
+
+    @abstractmethod
+    async def run(self, **kwargs) -> Any:
+        raise NotImplementedError
+
+    @property
+    def is_async(self) -> bool:
+        return True
+
+    @property
+    def is_concurrency_safe(self) -> bool:
+        return True
+

loom/interfaces/vector_store.py

@@ -0,0 +1,80 @@
+"""向量存储接口定义"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional, Tuple
+
+from loom.interfaces.retriever import Document
+
+
+class BaseVectorStore(ABC):
+    """
+    向量存储基类
+
+    向量数据库的统一接口，支持：
+    - 向量的添加和删除
+    - 基于向量的相似度搜索
+    - 元数据过滤
+    """
+
+    @abstractmethod
+    async def initialize(self) -> None:
+        """
+        初始化向量存储连接
+
+        用于建立数据库连接、创建集合/索引等初始化操作
+        """
+        pass
+
+    @abstractmethod
+    async def add_vectors(
+        self,
+        vectors: List[List[float]],
+        documents: List[Document]
+    ) -> None:
+        """
+        添加向量到存储
+
+        Parameters:
+            vectors: 向量列表，每个向量是一个浮点数列表
+            documents: 对应的文档列表，与 vectors 一一对应
+        """
+        pass
+
+    @abstractmethod
+    async def search(
+        self,
+        query_vector: List[float],
+        top_k: int = 5,
+        filters: Optional[Dict[str, Any]] = None
+    ) -> List[Tuple[Document, float]]:
+        """
+        搜索相似向量
+
+        Parameters:
+            query_vector: 查询向量
+            top_k: 返回结果数量
+            filters: 可选的元数据过滤条件
+
+        Returns:
+            [(Document, score), ...] 列表，按相似度分数降序排列
+        """
+        pass
+
+    async def delete(self, doc_ids: List[str]) -> None:
+        """
+        删除指定文档
+
+        Parameters:
+            doc_ids: 要删除的文档 ID 列表
+        """
+        pass
+
+    async def clear(self) -> None:
+        """清空所有向量"""
+        pass
+
+    async def close(self) -> None:
+        """关闭连接，释放资源"""
+        pass

loom/llm/__init__.py

@@ -0,0 +1,14 @@
+from .config import LLMConfig, LLMProvider, LLMCapabilities
+from .factory import LLMFactory
+from .pool import ModelPool
+from .registry import ModelRegistry
+
+__all__ = [
+    "LLMConfig",
+    "LLMProvider",
+    "LLMCapabilities",
+    "LLMFactory",
+    "ModelPool",
+    "ModelRegistry",
+]
+

loom/llm/config.py

@@ -0,0 +1,228 @@
+"""LLM 统一配置系统
+
+提供统一的接口来配置各种 LLM 提供商，支持：
+- OpenAI (GPT-4, GPT-3.5)
+- Anthropic (Claude)
+- Google (Gemini)
+- Cohere
+- Azure OpenAI
+- Ollama (本地模型)
+- 自定义模型
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+from pydantic import BaseModel, Field
+from enum import Enum
+
+
+class LLMProvider(str, Enum):
+    """LLM 提供商枚举"""
+    OPENAI = "openai"
+    ANTHROPIC = "anthropic"
+    GOOGLE = "google"
+    COHERE = "cohere"
+    AZURE_OPENAI = "azure_openai"
+    OLLAMA = "ollama"
+    CUSTOM = "custom"
+
+
+class LLMCapabilities(BaseModel):
+    """模型能力描述"""
+    supports_tools: bool = Field(default=False, description="是否支持工具调用/Function Calling")
+    supports_vision: bool = Field(default=False, description="是否支持视觉输入")
+    supports_streaming: bool = Field(default=True, description="是否支持流式输出")
+    supports_json_mode: bool = Field(default=False, description="是否支持 JSON 模式")
+    supports_system_message: bool = Field(default=True, description="是否支持系统消息")
+    max_tokens: int = Field(default=4096, description="最大输出 token 数")
+    context_window: int = Field(default=8192, description="上下文窗口大小")
+
+
+class LLMConfig(BaseModel):
+    """统一的 LLM 配置
+
+    示例:
+        # OpenAI
+        config = LLMConfig.openai(api_key="sk-...", model="gpt-4")
+
+        # Anthropic
+        config = LLMConfig.anthropic(api_key="sk-ant-...", model="claude-3-5-sonnet-20241022")
+
+        # Ollama 本地模型
+        config = LLMConfig.ollama(model="llama3", base_url="http://localhost:11434")
+
+        # 自定义模型
+        config = LLMConfig.custom(
+            model_name="my-model",
+            base_url="https://my-api.com",
+            api_key="..."
+        )
+    """
+
+    # 基本配置
+    provider: LLMProvider = Field(description="LLM 提供商")
+    model_name: str = Field(description="模型名称")
+    api_key: Optional[str] = Field(default=None, description="API Key（如果需要）")
+    base_url: Optional[str] = Field(default=None, description="API 基础 URL（用于代理或自定义端点）")
+
+    # 生成参数
+    temperature: float = Field(default=0.7, ge=0.0, le=2.0, description="温度参数，控制随机性")
+    max_tokens: Optional[int] = Field(default=None, description="最大输出 token 数")
+    top_p: float = Field(default=1.0, ge=0.0, le=1.0, description="核采样参数")
+    frequency_penalty: float = Field(default=0.0, ge=-2.0, le=2.0, description="频率惩罚")
+    presence_penalty: float = Field(default=0.0, ge=-2.0, le=2.0, description="存在惩罚")
+
+    # 可靠性配置
+    max_retries: int = Field(default=3, ge=0, description="最大重试次数")
+    retry_delay: float = Field(default=1.0, ge=0.0, description="重试延迟（秒）")
+    timeout: float = Field(default=60.0, ge=0.0, description="请求超时时间（秒）")
+
+    # 额外参数（特定提供商的特殊参数）
+    extra_params: Dict[str, Any] = Field(default_factory=dict, description="额外的提供商特定参数")
+
+    # 模型能力（可选，用于自动检测）
+    capabilities: Optional[LLMCapabilities] = Field(default=None, description="模型能力，不指定则自动检测")
+
+    class Config:
+        use_enum_values = True
+
+    # ==================== 快速配置方法 ====================
+
+    @classmethod
+    def openai(
+        cls,
+        api_key: str,
+        model: str = "gpt-4",
+        temperature: float = 0.7,
+        max_tokens: Optional[int] = None,
+        base_url: Optional[str] = None,
+        **kwargs
+    ) -> "LLMConfig":
+        return cls(
+            provider=LLMProvider.OPENAI,
+            model_name=model,
+            api_key=api_key,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            base_url=base_url,
+            **kwargs
+        )
+
+    @classmethod
+    def anthropic(
+        cls,
+        api_key: str,
+        model: str = "claude-3-5-sonnet-20241022",
+        temperature: float = 0.7,
+        max_tokens: Optional[int] = None,
+        **kwargs
+    ) -> "LLMConfig":
+        return cls(
+            provider=LLMProvider.ANTHROPIC,
+            model_name=model,
+            api_key=api_key,
+            temperature=temperature,
+            max_tokens=max_tokens or 4096,
+            **kwargs
+        )
+
+    @classmethod
+    def ollama(
+        cls,
+        model: str = "llama3",
+        base_url: str = "http://localhost:11434",
+        temperature: float = 0.7,
+        **kwargs
+    ) -> "LLMConfig":
+        return cls(
+            provider=LLMProvider.OLLAMA,
+            model_name=model,
+            base_url=base_url,
+            temperature=temperature,
+            api_key=None,
+            **kwargs
+        )
+
+    @classmethod
+    def azure_openai(
+        cls,
+        api_key: str,
+        deployment_name: str,
+        endpoint: str,
+        api_version: str = "2024-02-15-preview",
+        temperature: float = 0.7,
+        **kwargs
+    ) -> "LLMConfig":
+        return cls(
+            provider=LLMProvider.AZURE_OPENAI,
+            model_name=deployment_name,
+            api_key=api_key,
+            base_url=endpoint,
+            temperature=temperature,
+            extra_params={"api_version": api_version},
+            **kwargs
+        )
+
+    @classmethod
+    def google(
+        cls,
+        api_key: str,
+        model: str = "gemini-pro",
+        temperature: float = 0.7,
+        **kwargs
+    ) -> "LLMConfig":
+        return cls(
+            provider=LLMProvider.GOOGLE,
+            model_name=model,
+            api_key=api_key,
+            temperature=temperature,
+            **kwargs
+        )
+
+    @classmethod
+    def cohere(
+        cls,
+        api_key: str,
+        model: str = "command-r-plus",
+        temperature: float = 0.7,
+        **kwargs
+    ) -> "LLMConfig":
+        return cls(
+            provider=LLMProvider.COHERE,
+            model_name=model,
+            api_key=api_key,
+            temperature=temperature,
+            **kwargs
+        )
+
+    @classmethod
+    def custom(
+        cls,
+        model_name: str,
+        base_url: str,
+        api_key: Optional[str] = None,
+        temperature: float = 0.7,
+        capabilities: Optional[LLMCapabilities] = None,
+        **kwargs
+    ) -> "LLMConfig":
+        return cls(
+            provider=LLMProvider.CUSTOM,
+            model_name=model_name,
+            base_url=base_url,
+            api_key=api_key,
+            temperature=temperature,
+            capabilities=capabilities,
+            **kwargs
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        return self.model_dump()
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "LLMConfig":
+        return cls(**data)
+
+    def __repr__(self) -> str:
+        return f"LLMConfig(provider={self.provider}, model={self.model_name})"
+