loom-agent 0.0.1__py3-none-any.whl

loom/__init__.py

@@ -0,0 +1,77 @@
+from .components.agent import Agent
+from .core.subagent_pool import SubAgentPool
+from .llm import (
+    LLMConfig,
+    LLMProvider,
+    LLMCapabilities,
+    LLMFactory,
+    ModelPool,
+    ModelRegistry,
+)
+from .agent import agent, agent_from_env
+from .tooling import tool
+from .agents import AgentSpec, register_agent, list_agent_types, get_agent_by_type
+from .agents.refs import AgentRef, ModelRef, agent_ref, model_ref
+
+# P2 Features - Production Ready
+from .builtin.memory import InMemoryMemory, PersistentMemory
+from .core.error_classifier import ErrorClassifier, RetryPolicy
+from .core.circuit_breaker import CircuitBreaker, CircuitBreakerConfig, CircuitState
+
+# P3 Features - Optimization
+from .core.structured_logger import StructuredLogger, get_logger, set_correlation_id
+from .core.system_reminders import SystemReminderManager, get_reminder_manager
+from .callbacks.observability import ObservabilityCallback, MetricsAggregator
+from .llm.model_health import ModelHealthChecker, HealthStatus
+from .llm.model_pool_advanced import ModelPoolLLM, ModelConfig, FallbackChain
+
+try:
+    from importlib.metadata import version as _pkg_version
+
+    __version__ = _pkg_version("loom-agent")
+except Exception:  # pragma: no cover - best-effort
+    __version__ = "0"
+
+__all__ = [
+    "Agent",
+    "SubAgentPool",
+    "LLMConfig",
+    "LLMProvider",
+    "LLMCapabilities",
+    "LLMFactory",
+    "ModelPool",
+    "ModelRegistry",
+    "agent",
+    "tool",
+    "agent_from_env",
+    "AgentSpec",
+    "register_agent",
+    "list_agent_types",
+    "get_agent_by_type",
+    "AgentRef",
+    "ModelRef",
+    "agent_ref",
+    "model_ref",
+    # P2 exports
+    "InMemoryMemory",
+    "PersistentMemory",
+    "ErrorClassifier",
+    "RetryPolicy",
+    "CircuitBreaker",
+    "CircuitBreakerConfig",
+    "CircuitState",
+    # P3 exports
+    "StructuredLogger",
+    "get_logger",
+    "set_correlation_id",
+    "SystemReminderManager",
+    "get_reminder_manager",
+    "ObservabilityCallback",
+    "MetricsAggregator",
+    "ModelHealthChecker",
+    "HealthStatus",
+    "ModelPoolLLM",
+    "ModelConfig",
+    "FallbackChain",
+    "__version__",
+]

loom/agent.py

@@ -0,0 +1,217 @@
+"""Convenience builder for Agent
+
+Allows simple usage patterns like:
+
+import loom
+agent = loom.agent(provider="openai", model="gpt-4o", api_key="...")
+text = await agent.ainvoke("Hello")
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Dict, List, Optional, Union
+
+from .components.agent import Agent as _Agent
+from .interfaces.llm import BaseLLM
+from .interfaces.memory import BaseMemory
+from .interfaces.tool import BaseTool
+from .interfaces.compressor import BaseCompressor
+from .llm.config import LLMConfig, LLMProvider
+from .llm.factory import LLMFactory
+from .callbacks.base import BaseCallback
+from .callbacks.metrics import MetricsCollector
+from .core.steering_control import SteeringControl
+
+
+def agent(
+    *,
+    # Provide one of: llm | config | (provider+model)
+    llm: Optional[BaseLLM] = None,
+    config: Optional[LLMConfig] = None,
+    provider: Optional[Union[str, LLMProvider]] = None,
+    model: Optional[str] = None,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    # Agent options
+    tools: Optional[List[BaseTool]] = None,
+    memory: Optional[BaseMemory] = None,
+    compressor: Optional[BaseCompressor] = None,
+    max_iterations: int = 50,
+    max_context_tokens: int = 16000,
+    permission_policy: Optional[Dict[str, str]] = None,
+    ask_handler=None,
+    safe_mode: bool = False,
+    permission_store=None,
+    # Extra LLM config overrides
+    temperature: Optional[float] = None,
+    max_tokens: Optional[int] = None,
+    # Advanced
+    context_retriever=None,
+    system_instructions: Optional[str] = None,
+    callbacks: Optional[list[BaseCallback]] = None,
+    steering_control: Optional[SteeringControl] = None,
+    metrics: Optional[MetricsCollector] = None,
+) -> _Agent:
+    """Create an Agent with minimal parameters.
+
+    Priority:
+    1) Use provided `llm`
+    2) Build from `config`
+    3) Build from `provider` + `model` (+ api_key/base_url)
+    """
+
+    if llm is None:
+        if config is None and provider is not None and model is not None:
+            cfg = _build_config_from_inputs(
+                provider=provider,
+                model=model,
+                api_key=api_key,
+                base_url=base_url,
+                temperature=temperature,
+                max_tokens=max_tokens,
+            )
+            llm = LLMFactory.create(cfg)
+        elif config is not None:
+            llm = LLMFactory.create(config)
+        else:
+            raise ValueError("Please provide `llm`, or `config`, or `provider` + `model`.")
+
+    return _Agent(
+        llm=llm,
+        tools=tools,
+        memory=memory,
+        compressor=compressor,
+        max_iterations=max_iterations,
+        max_context_tokens=max_context_tokens,
+        permission_policy=permission_policy,
+        ask_handler=ask_handler,
+        safe_mode=safe_mode,
+        permission_store=permission_store,
+        context_retriever=context_retriever,
+        system_instructions=system_instructions,
+        callbacks=callbacks,
+        steering_control=steering_control,
+        metrics=metrics,
+    )
+
+
+def agent_from_env(
+    *,
+    provider: Optional[Union[str, LLMProvider]] = None,
+    model: Optional[str] = None,
+    # Agent options
+    tools: Optional[List[BaseTool]] = None,
+    memory: Optional[BaseMemory] = None,
+    compressor: Optional[BaseCompressor] = None,
+    max_iterations: int = 50,
+    max_context_tokens: int = 16000,
+    permission_policy: Optional[Dict[str, str]] = None,
+    ask_handler=None,
+    safe_mode: bool = False,
+    permission_store=None,
+    # Advanced
+    context_retriever=None,
+    system_instructions: Optional[str] = None,
+    callbacks: Optional[list[BaseCallback]] = None,
+    steering_control: Optional[SteeringControl] = None,
+    metrics: Optional[MetricsCollector] = None,
+) -> _Agent:
+    """Construct an Agent using provider/model resolved from environment.
+
+    Environment variables:
+    - LOOM_PROVIDER (fallback if provider not given)
+    - LOOM_MODEL (fallback if model not given)
+    - Provider-specific: OPENAI_API_KEY, OPENAI_BASE_URL, ANTHROPIC_API_KEY, COHERE_API_KEY, AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT
+    """
+    env_provider = os.getenv("LOOM_PROVIDER")
+    env_model = os.getenv("LOOM_MODEL")
+    use_provider = provider or env_provider
+    use_model = model or env_model
+    if not use_provider or not use_model:
+        raise ValueError("agent_from_env requires provider/model or LOOM_PROVIDER/LOOM_MODEL env")
+
+    return agent(
+        provider=use_provider,
+        model=use_model,
+        tools=tools,
+        memory=memory,
+        compressor=compressor,
+        max_iterations=max_iterations,
+        max_context_tokens=max_context_tokens,
+        permission_policy=permission_policy,
+        ask_handler=ask_handler,
+        safe_mode=safe_mode,
+        permission_store=permission_store,
+        context_retriever=context_retriever,
+        system_instructions=system_instructions,
+        callbacks=callbacks,
+        steering_control=steering_control,
+        metrics=metrics,
+    )
+
+
+def _build_config_from_inputs(
+    *,
+    provider: Union[str, LLMProvider],
+    model: str,
+    api_key: Optional[str],
+    base_url: Optional[str],
+    temperature: Optional[float],
+    max_tokens: Optional[int],
+) -> LLMConfig:
+    prov = provider.value if isinstance(provider, LLMProvider) else str(provider).lower()
+
+    # fill missing api_key from environment if possible
+    if api_key is None:
+        if prov == "openai" or prov == "custom" or prov == "azure_openai":
+            api_key = os.getenv("OPENAI_API_KEY") or os.getenv("AZURE_OPENAI_API_KEY")
+        elif prov == "anthropic":
+            api_key = os.getenv("ANTHROPIC_API_KEY")
+        elif prov == "cohere":
+            api_key = os.getenv("COHERE_API_KEY")
+
+    # default base_url for compatible providers if provided via env
+    if base_url is None and prov in {"openai", "custom", "azure_openai"}:
+        base_url = os.getenv("OPENAI_BASE_URL") or os.getenv("OPENAI_API_BASE")
+
+    kwargs = {}
+    if temperature is not None:
+        kwargs["temperature"] = temperature
+    if max_tokens is not None:
+        kwargs["max_tokens"] = max_tokens
+    if base_url is not None:
+        kwargs["base_url"] = base_url
+
+    if prov == "openai":
+        if not api_key:
+            raise ValueError("OPENAI provider requires api_key or OPENAI_API_KEY env")
+        return LLMConfig.openai(api_key=api_key, model=model, **kwargs)
+    if prov == "azure_openai":
+        # Treat like OpenAI-compatible; users can pass endpoint via base_url
+        if not api_key:
+            raise ValueError("AZURE_OPENAI provider requires api_key or AZURE_OPENAI_API_KEY env")
+        return LLMConfig.azure_openai(
+            api_key=api_key,
+            deployment_name=model,
+            endpoint=kwargs.pop("base_url", os.getenv("AZURE_OPENAI_ENDPOINT", "")),
+            **kwargs,
+        )
+    if prov == "anthropic":
+        if not api_key:
+            raise ValueError("ANTHROPIC provider requires api_key or ANTHROPIC_API_KEY env")
+        return LLMConfig.anthropic(api_key=api_key, model=model, **kwargs)
+    if prov == "cohere":
+        if not api_key:
+            raise ValueError("COHERE provider requires api_key or COHERE_API_KEY env")
+        return LLMConfig.cohere(api_key=api_key, model=model, **kwargs)
+    if prov == "google":
+        if not api_key:
+            raise ValueError("GOOGLE provider requires api_key env")
+        return LLMConfig.google(api_key=api_key, model=model, **kwargs)
+    if prov == "ollama":
+        return LLMConfig.ollama(model=model, base_url=base_url or "http://localhost:11434", **kwargs)
+    if prov == "custom":
+        return LLMConfig.custom(model_name=model, base_url=base_url or "", api_key=api_key, **kwargs)
+
+    raise ValueError(f"Unknown provider: {provider}")

loom/agents/__init__.py

@@ -0,0 +1,10 @@
+from .registry import AgentSpec, register_agent, get_agent_by_type, list_agent_types, clear_agents
+
+__all__ = [
+    "AgentSpec",
+    "register_agent",
+    "get_agent_by_type",
+    "list_agent_types",
+    "clear_agents",
+]
+

loom/agents/refs.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Union
+
+
+@dataclass(frozen=True)
+class AgentRef:
+    agent_type: str
+
+
+def agent_ref(agent_type: str) -> AgentRef:
+    return AgentRef(agent_type=agent_type)
+
+
+@dataclass(frozen=True)
+class ModelRef:
+    name: str
+
+
+def model_ref(name: str) -> ModelRef:
+    return ModelRef(name=name)
+
+
+# Back-compat typing helper for convenience
+AgentReferenceLike = Union[str, AgentRef]
+ModelReferenceLike = Union[str, ModelRef]
+

loom/agents/registry.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, List, Optional, Union
+
+
+@dataclass
+class AgentSpec:
+    """Programmatic agent definition for Loom.
+
+    This enables framework-first agent configuration without on-disk files.
+
+    Fields:
+    - agent_type: identifier used by Task tool (subagent_type)
+    - description: when to use this agent (for docs/UX; not enforced)
+    - system_instructions: system prompt injected when this agent is used
+    - tools: '*' or list of tool names that this agent may use
+    - model_name: optional model override for this agent
+    """
+
+    agent_type: str
+    description: str
+    system_instructions: str
+    tools: Union[List[str], str] = "*"
+    model_name: Optional[str] = None
+
+
+_AGENTS: Dict[str, AgentSpec] = {}
+
+
+def register_agent(spec: AgentSpec) -> AgentSpec:
+    """Register or override an agent spec in memory.
+
+    The most recent registration wins for a given agent_type.
+    """
+
+    _AGENTS[spec.agent_type] = spec
+    return spec
+
+
+def get_agent_by_type(agent_type: str) -> Optional[AgentSpec]:
+    return _AGENTS.get(agent_type)
+
+
+def list_agent_types() -> List[str]:
+    return list(_AGENTS.keys())
+
+
+def clear_agents() -> None:
+    _AGENTS.clear()

loom/builtin/compression/__init__.py

@@ -0,0 +1,4 @@
+from .structured import StructuredCompressor, CompressionConfig
+
+__all__ = ["StructuredCompressor", "CompressionConfig"]
+

loom/builtin/compression/structured.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import List
+
+from loom.core.types import Message
+from loom.interfaces.compressor import BaseCompressor
+from loom.utils.token_counter import count_messages_tokens
+
+
+@dataclass
+class CompressionConfig:
+    threshold: float = 0.92
+    warning_threshold: float = 0.80
+    target_ratio: float = 0.75
+    max_tokens_per_section: int = 512
+
+
+class StructuredCompressor(BaseCompressor):
+    """简化版 8 段式结构化压缩器。
+
+    不依赖 LLM，直观汇总近端消息片段，生成一条 system 摘要消息，并保留近端窗口。
+    """
+
+    def __init__(self, config: CompressionConfig | None = None, keep_recent: int = 6) -> None:
+        self.config = config or CompressionConfig()
+        self.keep_recent = keep_recent
+
+    async def compress(self, messages: List[Message]) -> List[Message]:
+        recent = messages[-self.keep_recent :] if self.keep_recent > 0 else []
+        # 粗略提取要点：截取用户与助手的近端内容片段
+        user_snippets = [m.content for m in messages if m.role == "user"][-3:]
+        assistant_snippets = [m.content for m in messages if m.role == "assistant"][-3:]
+        tool_snippets = [m.content for m in messages if m.role == "tool"][-5:]
+
+        summary = [
+            "# 对话历史压缩摘要",
+            f"时间: {datetime.now().isoformat(timespec='seconds')}",
+            "",
+            "## background_context",
+            "- 最近用户/助手对话被压缩为摘要，保留关键近端消息窗口。",
+            "",
+            "## key_decisions",
+            "- 见 assistant 近端结论片段（如有）。",
+            "",
+            "## tool_usage_log",
+            *[f"- {t[:200]}" for t in tool_snippets],
+            "",
+            "## user_intent_evolution",
+            *[f"- {u[:200]}" for u in user_snippets],
+            "",
+            "## execution_results",
+            *[f"- {a[:200]}" for a in assistant_snippets],
+            "",
+            "## errors_and_solutions",
+            "- （占位）如有错误会在此归档。",
+            "",
+            "## open_issues",
+            "- （占位）后续待解问题列表。",
+            "",
+            "## future_plans",
+            "- （占位）下一步行动建议。",
+        ]
+
+        compressed_msg = Message(
+            role="system",
+            content="\n".join(summary),
+            metadata={"compressed": True, "compression_time": datetime.now().isoformat()},
+        )
+
+        return [compressed_msg, *recent]
+
+    def should_compress(self, token_count: int, max_tokens: int) -> bool:
+        if max_tokens <= 0:
+            return False
+        ratio = token_count / max_tokens
+        return ratio >= self.config.threshold
+

loom/builtin/embeddings/__init__.py

@@ -0,0 +1,9 @@
+"""内置 Embedding 实现"""
+
+from loom.builtin.embeddings.openai_embedding import OpenAIEmbedding
+
+try:
+    from loom.builtin.embeddings.sentence_transformers_embedding import SentenceTransformersEmbedding
+    __all__ = ["OpenAIEmbedding", "SentenceTransformersEmbedding"]
+except ImportError:
+    __all__ = ["OpenAIEmbedding"]

loom/builtin/embeddings/openai_embedding.py

@@ -0,0 +1,135 @@
+"""OpenAI Embedding 适配器"""
+
+from __future__ import annotations
+
+from typing import List
+
+from loom.interfaces.embedding import BaseEmbedding
+
+try:
+    from openai import AsyncOpenAI
+    OPENAI_AVAILABLE = True
+except ImportError:
+    OPENAI_AVAILABLE = False
+
+
+class OpenAIEmbedding(BaseEmbedding):
+    """
+    OpenAI Embedding 适配器
+
+    支持模型:
+    - text-embedding-3-small (1536 维, 最便宜)
+    - text-embedding-3-large (3072 维, 最强)
+    - text-embedding-ada-002 (1536 维, 旧版)
+
+    示例:
+        from loom.builtin.embeddings import OpenAIEmbedding
+
+        embedding = OpenAIEmbedding(
+            api_key="your-api-key",
+            model="text-embedding-3-small"
+        )
+
+        # 单个文本
+        vector = await embedding.embed_query("Hello world")
+
+        # 批量文本
+        vectors = await embedding.embed_documents([
+            "Hello world",
+            "Loom framework"
+        ])
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        model: str = "text-embedding-3-small",
+        dimensions: int | None = None,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+    ):
+        """
+        Parameters:
+            api_key: OpenAI API Key
+            model: 模型名称
+            dimensions: 向量维度（可选，text-embedding-3-* 支持）
+            base_url: API 基础 URL（可选，用于代理）
+            timeout: 请求超时时间（秒）
+        """
+        if not OPENAI_AVAILABLE:
+            raise ImportError(
+                "OpenAI client is not installed. "
+                "Install with: pip install openai"
+            )
+
+        self.model = model
+        self.dimensions = dimensions
+        self.client = AsyncOpenAI(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout
+        )
+
+    async def embed_query(self, text: str) -> List[float]:
+        """
+        对单个查询文本进行向量化
+
+        Parameters:
+            text: 查询文本
+
+        Returns:
+            向量（列表）
+        """
+        vectors = await self.embed_documents([text])
+        return vectors[0]
+
+    async def embed_documents(self, texts: List[str]) -> List[List[float]]:
+        """
+        批量向量化文档
+
+        Parameters:
+            texts: 文本列表
+
+        Returns:
+            向量列表
+        """
+        # 过滤空文本
+        non_empty_texts = [t for t in texts if t.strip()]
+
+        if not non_empty_texts:
+            return [[0.0] * (self.dimensions or 1536)] * len(texts)
+
+        # 调用 OpenAI Embedding API
+        kwargs = {"input": non_empty_texts, "model": self.model}
+        if self.dimensions:
+            kwargs["dimensions"] = self.dimensions
+
+        response = await self.client.embeddings.create(**kwargs)
+
+        # 提取向量
+        vectors = [item.embedding for item in response.data]
+
+        # 处理空文本位置
+        result = []
+        non_empty_idx = 0
+        for text in texts:
+            if text.strip():
+                result.append(vectors[non_empty_idx])
+                non_empty_idx += 1
+            else:
+                result.append([0.0] * len(vectors[0]))
+
+        return result
+
+    def get_dimension(self) -> int:
+        """返回向量维度"""
+        if self.dimensions:
+            return self.dimensions
+
+        # 默认维度
+        dimension_map = {
+            "text-embedding-3-small": 1536,
+            "text-embedding-3-large": 3072,
+            "text-embedding-ada-002": 1536,
+        }
+        return dimension_map.get(self.model, 1536)