loom-agent 0.0.1__py3-none-any.whl

loom/core/compression_manager.py

@@ -0,0 +1,329 @@
+"""CompressionManager: AU2 8-segment context compression (US2)
+
+Implements intelligent context compression using LLM-based 8-segment summarization
+with automatic fallback to sliding window on failure.
+
+Features:
+- 92% threshold detection
+- 70-80% token reduction via 8-segment structured summarization
+- Retry logic with exponential backoff (1s, 2s, 4s)
+- Sliding window fallback after 3 failures
+- System message preservation
+- Compression metadata tracking
+
+Architecture:
+- LLM-based compression (primary): Structured 8-segment summary
+- Sliding window (fallback): Keep last N messages
+- Token counting: tiktoken (cl100k_base for GPT-4/Claude)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import List, Tuple, Optional
+
+from loom.core.types import Message, CompressionMetadata
+from loom.interfaces.llm import BaseLLM
+from loom.utils.token_counter import count_messages_tokens
+
+
+class CompressionManager:
+    """Manages context compression with 8-segment LLM-based summarization."""
+
+    # 8-segment compression prompt template
+    COMPRESSION_PROMPT_TEMPLATE = """You are a context compression expert. Your task is to compress a long conversation history into a concise 8-segment structured summary while preserving all critical information.
+
+**Input Conversation** ({message_count} messages, {token_count} tokens):
+{conversation}
+
+**Compression Requirements**:
+1. Extract and preserve ALL critical information (decisions, blockers, data, context)
+2. Reduce token count by 70-80% (target: {target_tokens} tokens)
+3. Structure output using exactly 8 segments below
+4. Use markdown formatting for readability
+5. Be concise but comprehensive - no detail too small if relevant
+
+**Output Format** (8 Segments):
+
+1. **Task Overview**: What is the user trying to accomplish? (1-2 sentences)
+2. **Key Decisions**: What important decisions or approaches were chosen? (bullet points)
+3. **Progress**: What has been completed so far? (bullet points with specific data/results)
+4. **Blockers**: What issues or errors occurred? How were they resolved? (bullet points, "None" if none)
+5. **Open Items**: What still needs to be done? What questions remain unanswered? (bullet points)
+6. **Context**: What background information or domain knowledge is relevant? (1-2 sentences)
+7. **Next Steps**: What should happen next based on the conversation? (bullet points)
+8. **Metadata**: Compression statistics and key topics (format: "Compressed {message_count} messages → 1 summary. Topics: topic1, topic2, topic3")
+
+**Example Output**:
+```
+**Compressed Context**
+
+1. **Task Overview**: User is implementing a REST API for user authentication with JWT tokens.
+
+2. **Key Decisions**:
+   - Using PostgreSQL for user storage
+   - JWT with 7-day expiration
+   - Bcrypt for password hashing (cost factor 12)
+
+3. **Progress**:
+   - Created User model with email/password fields
+   - Implemented /register endpoint (working)
+   - Implemented /login endpoint (returns JWT)
+   - Added password validation (min 8 chars, 1 special char)
+
+4. **Blockers**:
+   - Initial JWT verification failed due to incorrect secret key → Fixed by using consistent SECRET_KEY env var
+   - Database connection timeout → Fixed by increasing pool size to 20
+
+5. **Open Items**:
+   - Add /refresh endpoint for token renewal
+   - Implement rate limiting (5 login attempts per minute)
+   - Add email verification flow
+
+6. **Context**: This is part of a larger e-commerce platform migration from Django to FastAPI. Authentication needs to be compatible with existing mobile app using JWT.
+
+7. **Next Steps**:
+   - Implement /refresh endpoint with refresh token logic
+   - Add Redis for rate limiting
+   - Write integration tests for auth flow
+
+8. **Metadata**: Compressed 45 messages → 1 summary. Topics: authentication, JWT, PostgreSQL, FastAPI, API_design
+```
+
+Now compress the conversation above following this exact structure:"""
+
+    def __init__(
+        self,
+        llm: BaseLLM,
+        max_retries: int = 3,
+        compression_threshold: float = 0.92,
+        target_reduction: float = 0.75,  # 75% reduction
+        sliding_window_size: int = 20,
+    ):
+        """Initialize CompressionManager.
+
+        Args:
+            llm: LLM instance for compression (should support long context)
+            max_retries: Max retry attempts on LLM failure (default: 3)
+            compression_threshold: Token usage % to trigger compression (default: 0.92)
+            target_reduction: Target compression ratio (default: 0.75 = 75% reduction)
+            sliding_window_size: Fallback window size in messages (default: 20)
+        """
+        self.llm = llm
+        self.max_retries = max_retries
+        self.compression_threshold = compression_threshold
+        self.target_reduction = target_reduction
+        self.sliding_window_size = sliding_window_size
+
+    def should_compress(self, current_tokens: int, max_tokens: int) -> bool:
+        """Check if compression should be triggered.
+
+        Args:
+            current_tokens: Current context token count
+            max_tokens: Maximum allowed context tokens
+
+        Returns:
+            True if current_tokens >= threshold * max_tokens
+        """
+        threshold_tokens = int(max_tokens * self.compression_threshold)
+        return current_tokens >= threshold_tokens
+
+    async def compress(
+        self, messages: List[Message]
+    ) -> Tuple[List[Message], CompressionMetadata]:
+        """Compress conversation history using 8-segment LLM summarization.
+
+        Process:
+        1. Separate system messages (never compress)
+        2. Extract user/assistant messages for compression
+        3. Attempt LLM compression with retry logic
+        4. Fall back to sliding window after max_retries failures
+        5. Return compressed messages + metadata
+
+        Args:
+            messages: Full conversation history
+
+        Returns:
+            Tuple of (compressed_messages, compression_metadata)
+        """
+        if not messages:
+            return messages, CompressionMetadata(
+                original_message_count=0,
+                compressed_message_count=0,
+                original_tokens=0,
+                compressed_tokens=0,
+                compression_ratio=0.0,
+                key_topics=[],
+            )
+
+        # Separate system messages (preserve) from compressible messages
+        system_messages = [m for m in messages if m.role == "system"]
+        compressible = [m for m in messages if m.role in ("user", "assistant", "tool")]
+
+        if not compressible:
+            # No messages to compress, return as-is
+            return messages, CompressionMetadata(
+                original_message_count=len(messages),
+                compressed_message_count=len(messages),
+                original_tokens=count_messages_tokens(messages),
+                compressed_tokens=count_messages_tokens(messages),
+                compression_ratio=1.0,
+                key_topics=[],
+            )
+
+        # Count tokens
+        original_tokens = count_messages_tokens(compressible)
+        target_tokens = int(original_tokens * self.target_reduction)
+
+        # Attempt LLM compression with retry logic
+        compressed_summary = None
+        key_topics = []
+
+        for attempt in range(1, self.max_retries + 1):
+            try:
+                compressed_summary, key_topics = await self._llm_compress(
+                    compressible, original_tokens, target_tokens
+                )
+                break  # Success
+            except Exception as e:
+                if attempt < self.max_retries:
+                    # Exponential backoff: 1s, 2s, 4s
+                    backoff_delay = 2 ** (attempt - 1)
+                    await asyncio.sleep(backoff_delay)
+                else:
+                    # Max retries exhausted - fall back to sliding window
+                    compressed_summary = None
+                    key_topics = ["fallback"]
+
+        # Fall back to sliding window if LLM compression failed
+        if compressed_summary is None:
+            windowed_messages = self.sliding_window_fallback(compressible, self.sliding_window_size)
+            final_messages = system_messages + windowed_messages
+            compressed_tokens = count_messages_tokens(windowed_messages)
+
+            metadata = CompressionMetadata(
+                original_message_count=len(compressible),
+                compressed_message_count=len(windowed_messages),
+                original_tokens=original_tokens,
+                compressed_tokens=compressed_tokens,
+                compression_ratio=compressed_tokens / original_tokens if original_tokens > 0 else 0.0,
+                key_topics=["fallback"],
+            )
+            return final_messages, metadata
+
+        # LLM compression succeeded - create compressed message
+        compressed_message = Message(
+            role="system",
+            content=compressed_summary,
+            metadata={"type": "compressed_context", "original_count": len(compressible)},
+        )
+
+        compressed_tokens = count_messages_tokens([compressed_message])
+
+        # Combine system messages + compressed summary
+        final_messages = system_messages + [compressed_message]
+
+        metadata = CompressionMetadata(
+            original_message_count=len(compressible),
+            compressed_message_count=1,
+            original_tokens=original_tokens,
+            compressed_tokens=compressed_tokens,
+            compression_ratio=compressed_tokens / original_tokens if original_tokens > 0 else 0.0,
+            key_topics=key_topics,
+        )
+
+        return final_messages, metadata
+
+    async def _llm_compress(
+        self, messages: List[Message], original_tokens: int, target_tokens: int
+    ) -> Tuple[str, List[str]]:
+        """Use LLM to compress messages into 8-segment summary.
+
+        Args:
+            messages: Messages to compress
+            original_tokens: Original token count
+            target_tokens: Target token count after compression
+
+        Returns:
+            Tuple of (compressed_summary_str, key_topics_list)
+
+        Raises:
+            Exception: If LLM call fails
+        """
+        # Format conversation for prompt
+        conversation_text = self._format_messages_for_prompt(messages)
+
+        # Build compression prompt
+        prompt = self.COMPRESSION_PROMPT_TEMPLATE.format(
+            message_count=len(messages),
+            token_count=original_tokens,
+            target_tokens=target_tokens,
+            conversation=conversation_text,
+        )
+
+        # Call LLM
+        compressed_summary = await self.llm.generate([{"role": "user", "content": prompt}])
+
+        # Extract key topics from summary (simple regex extraction)
+        key_topics = self._extract_key_topics(compressed_summary)
+
+        return compressed_summary, key_topics
+
+    def _format_messages_for_prompt(self, messages: List[Message]) -> str:
+        """Format messages as readable conversation for LLM prompt.
+
+        Args:
+            messages: Messages to format
+
+        Returns:
+            Formatted conversation string
+        """
+        lines = []
+        for i, msg in enumerate(messages, 1):
+            role_label = msg.role.upper()
+            content = msg.content[:500] if len(msg.content) > 500 else msg.content  # Truncate long messages
+            lines.append(f"[{i}] {role_label}: {content}")
+
+        return "\n".join(lines)
+
+    def _extract_key_topics(self, compressed_summary: str) -> List[str]:
+        """Extract key topics from compressed summary metadata section.
+
+        Args:
+            compressed_summary: 8-segment compressed summary
+
+        Returns:
+            List of key topics (max 10)
+        """
+        # Look for "Topics:" in Metadata section
+        topics = []
+        if "Topics:" in compressed_summary:
+            topics_line = compressed_summary.split("Topics:")[-1].strip()
+            # Extract comma-separated topics
+            raw_topics = topics_line.split(",")
+            topics = [t.strip() for t in raw_topics[:10] if t.strip()]
+
+        # Fallback: extract topics from content if metadata missing
+        if not topics:
+            topics = ["general_compression"]
+
+        return topics
+
+    def sliding_window_fallback(
+        self, messages: List[Message], window_size: int
+    ) -> List[Message]:
+        """Fallback compression using sliding window (keep last N messages).
+
+        Args:
+            messages: Messages to compress
+            window_size: Number of recent messages to keep
+
+        Returns:
+            Last window_size messages
+        """
+        if len(messages) <= window_size:
+            return messages
+
+        # Keep last N messages
+        return messages[-window_size:]

loom/core/context_retriever.py

@@ -0,0 +1,185 @@
+"""上下文检索器 - AgentExecutor 的核心组件"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from loom.interfaces.retriever import BaseRetriever, Document
+
+
+class ContextRetriever:
+    """
+    上下文检索器 - 自动为查询检索相关文档
+
+    作为 AgentExecutor 的核心组件,在 LLM 调用前自动检索相关文档并注入上下文。
+
+    使用场景:
+    - 知识库问答
+    - 文档助手
+    - 需要外部知识的任务
+
+    示例:
+        retriever = VectorStoreRetriever(vector_store)
+        context_retriever = ContextRetriever(
+            retriever=retriever,
+            top_k=3,
+            auto_retrieve=True
+        )
+
+        agent = Agent(llm=llm, context_retriever=context_retriever)
+        # 每次查询都会自动检索相关文档
+    """
+
+    def __init__(
+        self,
+        retriever: BaseRetriever,
+        top_k: int = 3,
+        similarity_threshold: float = 0.0,
+        auto_retrieve: bool = True,
+        inject_as: str = "system",  # "system" or "user_prefix"
+    ) -> None:
+        """
+        Parameters:
+            retriever: 检索器实例
+            top_k: 检索文档数量
+            similarity_threshold: 相关性阈值 (0-1),低于此值的文档会被过滤
+            auto_retrieve: 是否自动检索 (False 则需要手动调用)
+            inject_as: 注入方式 ("system" 作为独立系统消息, "user_prefix" 作为用户消息前缀)
+        """
+        self.retriever = retriever
+        self.top_k = top_k
+        self.similarity_threshold = similarity_threshold
+        self.auto_retrieve = auto_retrieve
+        self.inject_as = inject_as
+
+    async def retrieve_for_query(
+        self,
+        query: str,
+        top_k: Optional[int] = None,
+        filters: Optional[Dict[str, Any]] = None,
+    ) -> List[Document]:
+        """
+        为查询检索相关文档
+
+        Parameters:
+            query: 用户查询
+            top_k: 覆盖默认的 top_k
+            filters: 元数据过滤条件
+
+        Returns:
+            相关文档列表 (已过滤低相关性文档)
+        """
+        if not self.auto_retrieve:
+            return []
+
+        k = top_k if top_k is not None else self.top_k
+
+        try:
+            docs = await self.retriever.retrieve(
+                query=query,
+                top_k=k,
+                filters=filters,
+            )
+
+            # 过滤低相关性文档
+            if self.similarity_threshold > 0:
+                docs = [
+                    doc for doc in docs
+                    if doc.score is None or doc.score >= self.similarity_threshold
+                ]
+
+            return docs
+
+        except Exception as e:
+            # 检索失败不应该阻塞主流程
+            print(f"Warning: Document retrieval failed: {e}")
+            return []
+
+    def format_documents(
+        self,
+        documents: List[Document],
+        max_length: int = 1000,
+    ) -> str:
+        """
+        格式化文档为字符串 (用于注入上下文)
+
+        Parameters:
+            documents: 文档列表
+            max_length: 单个文档最大长度
+
+        Returns:
+            格式化的文档字符串
+        """
+        if not documents:
+            return ""
+
+        lines = ["## Retrieved Context\n"]
+        lines.append(f"Found {len(documents)} relevant document(s):\n")
+
+        for i, doc in enumerate(documents, 1):
+            lines.append(f"### Document {i}")
+
+            # 元数据
+            if doc.metadata:
+                source = doc.metadata.get("source", "Unknown")
+                lines.append(f"**Source**: {source}")
+
+            if doc.score is not None:
+                lines.append(f"**Relevance**: {doc.score:.2%}")
+
+            # 内容 (截断)
+            content = doc.content
+            if len(content) > max_length:
+                content = content[:max_length] + "...\n[truncated]"
+
+            lines.append(f"\n{content}\n")
+
+        lines.append("---\n")
+        lines.append("Please answer the question based on the above context.\n")
+
+        return "\n".join(lines)
+
+    def format_as_user_prefix(
+        self,
+        documents: List[Document],
+        user_query: str,
+        max_length: int = 1000,
+    ) -> str:
+        """
+        将文档格式化为用户消息的前缀
+
+        适用于不想增加额外 system 消息的场景
+
+        Returns:
+            "Context: ...\n\nQuestion: {user_query}"
+        """
+        if not documents:
+            return user_query
+
+        doc_text = self.format_documents(documents, max_length)
+        return f"{doc_text}\nQuestion: {user_query}"
+
+    def get_metadata_summary(self, documents: List[Document]) -> Dict[str, Any]:
+        """
+        获取检索文档的元数据摘要
+
+        用于日志和调试
+
+        Returns:
+            {"count": 3, "avg_score": 0.85, "sources": [...]}
+        """
+        if not documents:
+            return {"count": 0}
+
+        scores = [doc.score for doc in documents if doc.score is not None]
+        sources = list(set(
+            doc.metadata.get("source", "Unknown")
+            for doc in documents
+            if doc.metadata
+        ))
+
+        return {
+            "count": len(documents),
+            "avg_score": sum(scores) / len(scores) if scores else None,
+            "sources": sources,
+        }

loom/core/error_classifier.py

@@ -0,0 +1,193 @@
+"""US5: Error Classification and Retry Logic
+
+Classifies errors into retryable/non-retryable categories and provides
+actionable recovery guidance.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Optional, Callable, Any, TypeVar
+from loom.core.errors import ErrorCategory, LoomException
+
+T = TypeVar('T')
+
+
+class ErrorClassifier:
+    """Classifies errors and determines retry strategy."""
+
+    @staticmethod
+    def classify(error: Exception) -> ErrorCategory:
+        """Classify an error into a category.
+
+        Args:
+            error: The exception to classify
+
+        Returns:
+            ErrorCategory enum value
+        """
+        # Check if it's already a LoomException with category
+        if isinstance(error, LoomException):
+            return error.category
+
+        # Classify by exception type
+        error_type = type(error).__name__
+        error_msg = str(error).lower()
+
+        # Network errors (retryable)
+        if any(kw in error_type.lower() for kw in ['timeout', 'connect', 'network']):
+            return ErrorCategory.TIMEOUT_ERROR if 'timeout' in error_type.lower() else ErrorCategory.NETWORK_ERROR
+
+        # Rate limiting (retryable with backoff)
+        if '429' in error_msg or 'rate limit' in error_msg:
+            return ErrorCategory.RATE_LIMIT_ERROR
+
+        # Service errors (5xx - retryable)
+        if any(code in error_msg for code in ['500', '502', '503', '504']):
+            return ErrorCategory.SERVICE_ERROR
+
+        # Authentication errors (non-retryable)
+        if any(code in error_msg for code in ['401', '403']) or 'auth' in error_msg:
+            return ErrorCategory.AUTHENTICATION_ERROR
+
+        # Not found errors (non-retryable)
+        if '404' in error_msg or 'not found' in error_msg:
+            return ErrorCategory.NOT_FOUND_ERROR
+
+        # Validation errors (non-retryable)
+        if 'validation' in error_type.lower():
+            return ErrorCategory.VALIDATION_ERROR
+
+        # Default: unknown (non-retryable)
+        return ErrorCategory.UNKNOWN_ERROR
+
+    @staticmethod
+    def is_retryable(category: ErrorCategory) -> bool:
+        """Determine if an error category is retryable.
+
+        Args:
+            category: The error category
+
+        Returns:
+            True if retryable, False otherwise
+        """
+        retryable_categories = {
+            ErrorCategory.NETWORK_ERROR,
+            ErrorCategory.TIMEOUT_ERROR,
+            ErrorCategory.RATE_LIMIT_ERROR,
+            ErrorCategory.SERVICE_ERROR,
+        }
+        return category in retryable_categories
+
+    @staticmethod
+    def get_recovery_guidance(error: Exception, category: ErrorCategory) -> str:
+        """Get actionable recovery guidance for an error.
+
+        Args:
+            error: The exception
+            category: The error category
+
+        Returns:
+            Human-readable recovery guidance
+        """
+        guidance_map = {
+            ErrorCategory.NETWORK_ERROR: "Check network connectivity and retry. If problem persists, check service status.",
+            ErrorCategory.TIMEOUT_ERROR: "Operation timed out. Try increasing timeout or simplifying the request.",
+            ErrorCategory.RATE_LIMIT_ERROR: "Rate limit exceeded. Wait before retrying. Consider implementing backoff.",
+            ErrorCategory.SERVICE_ERROR: "Service temporarily unavailable. Retry after a short delay.",
+            ErrorCategory.VALIDATION_ERROR: "Invalid input parameters. Review and correct the request.",
+            ErrorCategory.PERMISSION_ERROR: "Permission denied. Check access rights and credentials.",
+            ErrorCategory.AUTHENTICATION_ERROR: "Authentication failed. Verify credentials and API keys.",
+            ErrorCategory.NOT_FOUND_ERROR: "Resource not found. Verify the resource exists and path is correct.",
+            ErrorCategory.UNKNOWN_ERROR: f"Unexpected error: {type(error).__name__}. Review error details.",
+        }
+        return guidance_map.get(category, "Unknown error. Review error details.")
+
+
+class RetryPolicy:
+    """Retry policy with exponential backoff.
+
+    US5: Automatic retry with exponential backoff (1s, 2s, 4s, max 3 attempts)
+    """
+
+    def __init__(
+        self,
+        max_retries: int = 3,
+        base_delay: float = 1.0,
+        max_delay: float = 60.0,
+        exponential_base: float = 2.0,
+    ):
+        """Initialize retry policy.
+
+        Args:
+            max_retries: Maximum number of retry attempts
+            base_delay: Initial delay in seconds
+            max_delay: Maximum delay in seconds
+            exponential_base: Base for exponential backoff (2.0 = double each time)
+        """
+        self.max_retries = max_retries
+        self.base_delay = base_delay
+        self.max_delay = max_delay
+        self.exponential_base = exponential_base
+
+    def get_delay(self, attempt: int) -> float:
+        """Calculate delay for retry attempt.
+
+        Args:
+            attempt: The retry attempt number (0-indexed)
+
+        Returns:
+            Delay in seconds
+        """
+        delay = self.base_delay * (self.exponential_base ** attempt)
+        return min(delay, self.max_delay)
+
+    async def execute_with_retry(
+        self,
+        func: Callable[..., Any],
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        """Execute a function with retry logic.
+
+        Args:
+            func: The async function to execute
+            *args: Positional arguments
+            **kwargs: Keyword arguments
+
+        Returns:
+            The result of the function
+
+        Raises:
+            The last exception if all retries fail
+        """
+        last_exception: Optional[Exception] = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                # Execute function
+                if asyncio.iscoroutinefunction(func):
+                    return await func(*args, **kwargs)
+                else:
+                    return func(*args, **kwargs)
+
+            except Exception as e:
+                last_exception = e
+                category = ErrorClassifier.classify(e)
+
+                # Don't retry if non-retryable
+                if not ErrorClassifier.is_retryable(category):
+                    raise
+
+                # If this was the last attempt, raise
+                if attempt >= self.max_retries:
+                    raise
+
+                # Calculate delay and wait
+                delay = self.get_delay(attempt)
+                await asyncio.sleep(delay)
+
+        # Should not reach here, but if we do, raise the last exception
+        if last_exception:
+            raise last_exception
+        raise RuntimeError("Retry logic failed unexpectedly")