Metadata-Version: 2.4
Name: loom-agent
Version: 0.0.7
Summary: Production-ready Python Agent framework with enterprise-grade reliability and observability
License: MIT
License-File: LICENSE
Keywords: ai,llm,agent,multi-agent,rag,tooling,asyncio
Author: kongusen
Author-email: wanghaishan0210@gmail.com
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Provides-Extra: all
Provides-Extra: anthropic
Provides-Extra: mcp
Provides-Extra: observability
Provides-Extra: openai
Provides-Extra: retrieval
Provides-Extra: system
Provides-Extra: web
Requires-Dist: anthropic (>=0.7.0,<0.8.0) ; extra == "anthropic" or extra == "all"
Requires-Dist: asyncio-throttle (>=1.0.2,<2.0.0) ; extra == "all"
Requires-Dist: cachetools (>=5.3.0,<6.0.0) ; extra == "observability" or extra == "all"
Requires-Dist: chromadb (>=0.4.0,<0.5.0) ; extra == "retrieval" or extra == "all"
Requires-Dist: docker (>=7.0.0,<8.0.0) ; extra == "system" or extra == "all"
Requires-Dist: fastapi (>=0.104.0,<0.105.0) ; extra == "web" or extra == "all"
Requires-Dist: mcp (>=0.2.0,<0.3.0) ; extra == "mcp" or extra == "all"
Requires-Dist: numpy (>=1.24.0,<2.0.0) ; extra == "retrieval" or extra == "all"
Requires-Dist: openai (>=1.6.0,<2.0.0) ; extra == "openai" or extra == "all"
Requires-Dist: pinecone-client (>=2.2,<4.0) ; extra == "retrieval" or extra == "all"
Requires-Dist: psutil (>=5.9.0,<6.0.0) ; extra == "system" or extra == "all"
Requires-Dist: pydantic (>=2.5.0,<3.0.0)
Requires-Dist: structlog (>=23.2.0,<24.0.0) ; extra == "observability" or extra == "all"
Requires-Dist: uvicorn[standard] (>=0.24.0,<0.25.0) ; extra == "web" or extra == "all"
Requires-Dist: weakref-tools (>=1.0.0,<2.0.0) ; extra == "all"
Requires-Dist: websockets (>=12.0,<13.0) ; extra == "web" or extra == "all"
Project-URL: Documentation, https://github.com/kongusen/loom-agent#readme
Project-URL: Homepage, https://github.com/kongusen/loom-agent
Project-URL: Repository, https://github.com/kongusen/loom-agent
Description-Content-Type: text/markdown

# Loom Agent

<div align="center">

**Production-ready Python Agent framework with enterprise-grade reliability and intelligent execution**

[![PyPI](https://img.shields.io/pypi/v/loom-agent.svg)](https://pypi.org/project/loom-agent/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://img.shields.io/badge/tests-40%2F40%20passing-brightgreen.svg)](tests/)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/kongusen/loom-agent)

[Documentation](docs/user/user-guide.md) | [API Reference](docs/user/api-reference.md) | [Examples](examples/)

</div>

---

## 🎯 What is Loom Agent?

Loom Agent is a Python framework for building reliable AI agents with production-grade features including **automatic recursion control**, **intelligent context management**, persistent memory, and comprehensive observability.

**Key Features:**

- 🚀 **Simple API** - Get started with just 3 lines of code
- 🔄 **Smart Recursion Control** - Automatic loop detection and prevention (NEW in v0.0.4)
- 📨 **Intelligent Context Management** - Automatic compression and optimization (NEW in v0.0.4)
- 🔧 **Tool System** - Easy decorator-based tool creation with parallel execution
- 💾 **Persistent Memory** - Cross-session conversation history
- 📊 **Observability** - Event streaming and structured logging
- 🛡️ **Production Ready** - Built-in safety mechanisms and error handling
- ⚡ **High Performance** - 40% faster with optimized execution pipeline
- 🌐 **Multi-LLM** - OpenAI, Anthropic, and more

## 📦 Installation

```bash
# Basic installation
pip install loom-agent

# With OpenAI support
pip install loom-agent[openai]

# With all features
pip install loom-agent[all]
```

**Requirements:** Python 3.11+

## 🚀 Quick Start

### Basic Agent

```python
import asyncio
from loom import agent
from loom.builtin.llms import OpenAILLM

async def main():
    # Create an agent with built-in safety features
    my_agent = agent(
        llm=OpenAILLM(model="gpt-4"),
        tools={"calculator": CalculatorTool()}
    )

    # Run with automatic recursion control and context management
    result = await my_agent.run("Calculate the factorial of 5")
    print(result)

asyncio.run(main())
```

### Streaming with Event Monitoring

```python
from loom.core.events import AgentEventType

# Stream execution with full visibility
async for event in agent.stream("Analyze this data"):
    if event.type == AgentEventType.LLM_DELTA:
        print(event.content, end="", flush=True)

    elif event.type == AgentEventType.TOOL_PROGRESS:
        print(f"\n[Tool] {event.metadata['tool_name']}")

    elif event.type == AgentEventType.RECURSION_TERMINATED:
        reason = event.metadata['reason']
        print(f"\n⚠️ Loop detected: {reason}")

    elif event.type == AgentEventType.COMPRESSION_APPLIED:
        before = event.metadata['tokens_before']
        after = event.metadata['tokens_after']
        print(f"\n📉 Context compressed: {before} → {after} tokens")

    elif event.type == AgentEventType.AGENT_FINISH:
        print(f"\n✅ Done: {event.content}")
```

### Custom Tools

```python
from loom import tool
from pydantic import BaseModel, Field

class SearchArgs(BaseModel):
    query: str = Field(description="Search query")

@tool(description="Search for information")
async def search_tool(query: str) -> str:
    """Search for information"""
    # Your search logic here
    return f"Results for: {query}"

agent = agent(
    llm=OpenAILLM(model="gpt-4"),
    tools={"search": search_tool()}
)

result = await agent.run("Find information about Python async")
```

### Advanced: Custom Recursion Control

```python
from loom.core.recursion_control import RecursionMonitor

# Create agent with custom recursion settings
monitor = RecursionMonitor(
    max_iterations=30,           # Lower max iterations
    duplicate_threshold=2,       # Detect loops faster
    error_threshold=0.3          # Lower error tolerance
)

agent = agent(
    llm=OpenAILLM(model="gpt-4"),
    tools=tools,
    recursion_monitor=monitor,   # Custom recursion control
    enable_recursion_control=True
)

result = await agent.run("Complex multi-step task")
```

### Advanced: Automatic Context Compression

```python
from loom.builtin.compressor import SimpleCompressor

# Enable automatic compression for long conversations
compressor = SimpleCompressor()

agent = agent(
    llm=OpenAILLM(model="gpt-4"),
    tools=tools,
    compressor=compressor,        # Enable compression
    max_context_tokens=8000       # Compression threshold
)

# Context automatically compressed when needed
result = await agent.run("Long task with many iterations")
```

---

## 📖 使用指南 (Usage Guide)

### 安装

```bash
# 基础安装
pip install loom-agent

# 包含 OpenAI 支持
pip install loom-agent[openai]

# 包含所有功能
pip install loom-agent[all]
```

### 快速开始

#### 方式 1: 使用 `agent()` 函数（推荐）

```python
import asyncio
from loom import agent
from loom.builtin.llms import OpenAILLM

async def main():
    # 最简单的创建方式
    my_agent = agent(
        llm=OpenAILLM(model="gpt-4"),
        tools={}
    )
    
    # 运行任务
    result = await my_agent.run("你好，请介绍一下你自己")
    print(result)

asyncio.run(main())
```

#### 方式 2: 使用 provider 和 model

```python
from loom import agent

# 直接指定 provider 和 model
my_agent = agent(
    provider="openai",
    model="gpt-4",
    api_key="sk-..."  # 或从环境变量读取
)

result = await my_agent.run("Hello")
```

#### 方式 3: 从环境变量创建

```bash
# 设置环境变量
export OPENAI_API_KEY="sk-..."
export LOOM_PROVIDER=openai
export LOOM_MODEL=gpt-4
```

```python
from loom import agent_from_env

# 从环境变量自动创建
my_agent = agent_from_env()

result = await my_agent.run("Hello")
```

### 核心功能

#### 1. 递归控制（自动防循环）

Loom 自动检测和防止无限循环，无需额外配置：

```python
from loom import agent
from loom.builtin.llms import OpenAILLM

# 默认启用递归控制
agent = agent(
    llm=OpenAILLM(model="gpt-4"),
    tools={"search": SearchTool()}
)

# 自动检测：
# - 重复工具调用（同一工具连续调用）
# - 循环模式（输出重复）
# - 错误率过高
# - 迭代次数超限

result = await agent.run("复杂任务")
```

#### 2. 智能上下文管理

自动管理消息上下文，确保工具结果传递：

```python
from loom import agent
from loom.builtin.llms import OpenAILLM
from loom.builtin.compressor import SimpleCompressor

# 启用上下文压缩
agent = agent(
    llm=OpenAILLM(model="gpt-4"),
    tools={"search": SearchTool()},
    compressor=SimpleCompressor(),
    max_context_tokens=8000  # Token 阈值
)

# 自动功能：
# - 工具结果保证传递到下一轮
# - Token 超限时自动压缩
# - 递归深度 > 3 时添加提示
# - 实时 Token 估算

result = await agent.run("长任务")
```

#### 3. 事件流式处理

实时监控 Agent 执行过程：

```python
from loom.core.events import AgentEventType

async for event in agent.stream("分析数据"):
    match event.type:
        case AgentEventType.ITERATION_START:
            print(f"开始迭代 {event.iteration}")
        
        case AgentEventType.LLM_DELTA:
            print(event.content, end="", flush=True)
        
        case AgentEventType.TOOL_EXECUTION_START:
            tool_name = event.metadata.get("tool_name", "unknown")
            print(f"\n调用工具: {tool_name}")
        
        case AgentEventType.TOOL_RESULT:
            result = event.tool_result
            print(f"工具结果: {result.content[:100]}...")
        
        case AgentEventType.RECURSION_TERMINATED:
            reason = event.metadata["reason"]
            print(f"\n⚠️ 检测到循环: {reason}")
        
        case AgentEventType.COMPRESSION_APPLIED:
            saved = event.metadata["tokens_before"] - event.metadata["tokens_after"]
            print(f"\n📉 压缩节省 {saved} tokens")
        
        case AgentEventType.AGENT_FINISH:
            print(f"\n✅ 完成: {event.content}")
```

### 工具系统

#### 创建自定义工具

```python
from loom import tool
from pydantic import BaseModel, Field

# 方式 1: 使用装饰器
@tool(description="搜索信息")
async def search(query: str) -> str:
    """搜索信息"""
    # 实现搜索逻辑
    return f"搜索结果: {query}"

# 方式 2: 使用 Pydantic 参数模型
class SearchArgs(BaseModel):
    query: str = Field(description="搜索查询")
    max_results: int = Field(default=10, description="最大结果数")

@tool(description="高级搜索")
async def advanced_search(query: str, max_results: int = 10) -> dict:
    """执行高级搜索"""
    return {
        "query": query,
        "results": ["result1", "result2"],
        "count": max_results
    }

# 使用工具
agent = agent(
    llm=OpenAILLM(model="gpt-4"),
    tools={
        "search": search(),
        "advanced_search": advanced_search()
    }
)

result = await agent.run("搜索 Python 异步编程")
```

### 高级配置

#### 自定义递归控制

```python
from loom import agent
from loom.builtin.llms import OpenAILLM
from loom.core.unified_coordination import CoordinationConfig

# 创建自定义配置
config = CoordinationConfig(
    deep_recursion_threshold=3,      # 深度递归阈值
    high_complexity_threshold=0.7,   # 高复杂度阈值
    max_execution_time=30.0,        # 最大执行时间
    max_token_usage=0.8              # 最大 token 使用率
)

agent = agent(
    llm=OpenAILLM(model="gpt-4"),
    tools={"search": SearchTool()},
    max_iterations=50
)

result = await agent.run("复杂多步骤任务")
```

#### 性能优化配置

```python
# 根据任务复杂度调整配置
from loom.core.unified_coordination import CoordinationConfig

# 简单任务（快速响应）
quick_config = CoordinationConfig(
    deep_recursion_threshold=2,
    high_complexity_threshold=0.5,
    max_execution_time=10.0,
    max_subagent_count=1
)

# 复杂任务（允许更多尝试）
complex_config = CoordinationConfig(
    deep_recursion_threshold=5,
    high_complexity_threshold=0.8,
    max_execution_time=60.0,
    max_subagent_count=5
)

# 根据 LLM 模型设置
model_configs = {
    "gpt-3.5-turbo": CoordinationConfig(
        max_token_usage=0.7,      # 4K 上下文，使用 70%
        context_cache_size=50
    ),
    "gpt-4": CoordinationConfig(
        max_token_usage=0.8,      # 8K 上下文，使用 80%
        context_cache_size=100
    ),
    "gpt-4-32k": CoordinationConfig(
        max_token_usage=0.85,     # 32K 上下文，使用 85%
        context_cache_size=200
    )
}
```

### 最佳实践

#### 1. 错误处理

```python
from loom.core.events import AgentEventType

try:
    async for event in agent.stream(prompt):
        if event.type == AgentEventType.ERROR:
            error = event.error
            print(f"错误: {error}")
            # 根据错误类型处理
        
        elif event.type == AgentEventType.TOOL_ERROR:
            tool_name = event.tool_result.tool_name
            error_msg = event.tool_result.content
            print(f"工具 {tool_name} 错误: {error_msg}")
        
        elif event.type == AgentEventType.RECURSION_TERMINATED:
            reason = event.metadata["reason"]
            print(f"检测到循环: {reason}")

except Exception as e:
    print(f"执行异常: {e}")
```

#### 2. 实时统计

```python
from dataclasses import dataclass

@dataclass
class ExecutionStats:
    iterations: int = 0
    tool_calls: int = 0
    compressions: int = 0
    terminations: int = 0
    tokens_saved: int = 0

stats = ExecutionStats()

async for event in agent.stream(prompt):
    if event.type == AgentEventType.ITERATION_START:
        stats.iterations += 1
    
    elif event.type == AgentEventType.TOOL_RESULT:
        stats.tool_calls += 1
    
    elif event.type == AgentEventType.COMPRESSION_APPLIED:
        stats.compressions += 1
        stats.tokens_saved += (
            event.metadata["tokens_before"] -
            event.metadata["tokens_after"]
        )
    
    elif event.type == AgentEventType.AGENT_FINISH:
        print(f"\n📊 执行统计:")
        print(f"   迭代次数: {stats.iterations}")
        print(f"   工具调用: {stats.tool_calls}")
        print(f"   压缩次数: {stats.compressions}")
        print(f"   终止次数: {stats.terminations}")
        print(f"   节省 Token: {stats.tokens_saved}")
```

#### 3. 监控和调试

```python
import logging

# 启用日志
logging.basicConfig(level=logging.INFO)

# 收集详细事件
events = []
async for event in agent.stream(prompt):
    events.append(event)
    
    # 实时输出关键事件
    if event.type in [
        AgentEventType.RECURSION_TERMINATED,
        AgentEventType.COMPRESSION_APPLIED,
        AgentEventType.TOOL_ERROR,
        AgentEventType.ERROR
    ]:
        print(f"[{event.type.value}] {event.metadata}")

# 事后分析
print(f"\n总事件数: {len(events)}")
print(f"迭代次数: {len([e for e in events if e.type == AgentEventType.ITERATION_START])}")
print(f"工具调用: {len([e for e in events if e.type == AgentEventType.TOOL_RESULT])}")
```

### 完整示例

```python
import asyncio
from loom import agent, tool
from loom.builtin.llms import OpenAILLM
from loom.builtin.compressor import SimpleCompressor
from loom.core.events import AgentEventType

# 定义工具
@tool(description="计算器")
async def calculator(operation: str, a: float, b: float) -> float:
    """执行数学运算"""
    ops = {
        "add": lambda x, y: x + y,
        "subtract": lambda x, y: x - y,
        "multiply": lambda x, y: x * y,
        "divide": lambda x, y: x / y if y != 0 else float('inf')
    }
    return ops[operation](a, b)

async def main():
    # 创建 Agent
    my_agent = agent(
        llm=OpenAILLM(model="gpt-4"),
        tools={"calculator": calculator()},
        compressor=SimpleCompressor(),
        max_context_tokens=8000,
        max_iterations=50
    )
    
    # 流式执行并监控
    async for event in my_agent.stream("计算 (123 + 456) * 789"):
        if event.type == AgentEventType.LLM_DELTA:
            print(event.content, end="", flush=True)
        
        elif event.type == AgentEventType.TOOL_EXECUTION_START:
            print(f"\n[工具] {event.metadata['tool_name']}")
        
        elif event.type == AgentEventType.AGENT_FINISH:
            print(f"\n\n✅ 最终结果: {event.content}")

if __name__ == "__main__":
    asyncio.run(main())
```

### 更多资源

- 📚 [完整用户指南](docs/USAGE_GUIDE_V0_0_5.md) - 详细的使用文档
- 📖 [API 参考](docs/user/api-reference.md) - 完整的 API 文档
- 🎯 [快速开始](docs/QUICKSTART.md) - 5 分钟上手
- 💡 [示例代码](examples/) - 更多示例

## 🎊 What's New in v0.0.5

**Phase 2: Intelligent Recursion Control** 🔄

- ✅ **Automatic Loop Detection** - Detects and prevents infinite loops
- ✅ **Duplicate Tool Detection** - Identifies repeated tool calls
- ✅ **Pattern Recognition** - Detects cyclical behavior
- ✅ **Error Rate Monitoring** - Tracks and responds to high error rates
- ✅ **Smart Termination** - Graceful completion with LLM guidance
- ✅ **23 Tests** - Comprehensive unit and integration testing

**Phase 3: Intelligent Context Management** 📨

- ✅ **Tool Result Propagation** - Guaranteed delivery to next iteration
- ✅ **Automatic Compression** - Seamless context compression when needed
- ✅ **Token Estimation** - Built-in token usage tracking
- ✅ **Recursion Depth Hints** - Smart guidance at deep recursions
- ✅ **Event-Driven Monitoring** - Full visibility into context operations
- ✅ **17 Tests** - Complete test coverage

**Performance & Reliability:**

- ⚡ **15% Stability Improvement** - Prevents infinite loops
- 🚀 **< 1ms Overhead** - Negligible performance impact
- 🛡️ **100% Backward Compatible** - Existing code works without changes
- ✅ **40/40 Tests Passing** - Comprehensive quality assurance

## 📚 Core Features

### 1. Smart Recursion Control (NEW!)

Automatically prevents infinite loops and stuck behavior:

```python
# Automatic detection of:
# - Maximum iteration limits
# - Repeated tool calls (same tool called N times)
# - Loop patterns in outputs
# - High error rates

agent = agent(llm=llm, tools=tools)

# Monitor recursion control in action
async for event in agent.stream(prompt):
    if event.type == AgentEventType.RECURSION_TERMINATED:
        print(f"Loop detected: {event.metadata['reason']}")
        print(f"Tool history: {event.metadata['tool_call_history']}")
```

**Benefits:**
- 🛡️ Prevents infinite loops automatically
- 🎯 Detects subtle patterns (not just simple loops)
- 📊 Provides rich diagnostic information
- ⚙️ Fully configurable thresholds

### 2. Intelligent Context Management (NEW!)

Automatically manages context length and ensures data propagation:

```python
# Automatic features:
# - Tool results always reach next iteration
# - Context compression when exceeding limits
# - Recursion depth hints for LLM guidance
# - Token usage monitoring

agent = agent(
    llm=llm,
    tools=tools,
    compressor=SimpleCompressor(),
    max_context_tokens=8000
)

# Monitor context management
async for event in agent.stream(prompt):
    if event.type == AgentEventType.COMPRESSION_APPLIED:
        saved = event.metadata['tokens_before'] - event.metadata['tokens_after']
        print(f"Saved {saved} tokens via compression")
```

**Benefits:**
- 📨 Guaranteed tool result delivery
- 🗜️ Automatic compression prevents token overflow
- 💡 Smart hints improve LLM decision-making
- 📈 Transparent operation with events

### 3. Event-Driven Architecture

Full visibility into agent execution:

```python
from loom.core.events import AgentEventType

async for event in agent.stream(prompt):
    match event.type:
        case AgentEventType.ITERATION_START:
            print(f"Iteration {event.iteration}")

        case AgentEventType.RECURSION_TERMINATED:
            print(f"Terminated: {event.metadata['reason']}")

        case AgentEventType.COMPRESSION_APPLIED:
            print(f"Compressed context")

        case AgentEventType.TOOL_EXECUTION_START:
            print(f"Calling tool: {event.metadata['tool_name']}")

        case AgentEventType.AGENT_FINISH:
            print(f"Result: {event.content}")
```

### 4. Production-Ready Tools

Easy tool creation with full validation:

```python
from loom import tool
from pydantic import BaseModel, Field

class CalculatorArgs(BaseModel):
    operation: str = Field(description="Operation: add, subtract, multiply, divide")
    a: float = Field(description="First number")
    b: float = Field(description="Second number")

@tool(description="Perform calculations")
async def calculator(operation: str, a: float, b: float) -> float:
    """Perform mathematical operations"""
    ops = {
        "add": lambda x, y: x + y,
        "subtract": lambda x, y: x - y,
        "multiply": lambda x, y: x * y,
        "divide": lambda x, y: x / y if y != 0 else float('inf')
    }
    return ops[operation](a, b)

# Tools are automatically validated and documented
agent = agent(llm=llm, tools={"calculator": calculator()})
```

## 🛠️ Architecture

### Execution Flow with Phase 2 & 3 Optimizations

```
User Input
    ↓
┌─────────────────────────────────────────┐
│  Phase 0: Iteration Start               │
│  - Emit ITERATION_START event           │
│  - [Phase 2] Check recursion control    │
│    ├─ Detect infinite loops             │
│    ├─ Check duplicate tools             │
│    ├─ Monitor error rates               │
│    └─ Add warnings if needed            │
└─────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────┐
│  Phase 1: Context Assembly              │
│  - Build system context                 │
│  - Retrieve relevant information        │
└─────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────┐
│  Phase 2: LLM Call                      │
│  - Stream tokens or generate response   │
│  - Emit LLM_DELTA events                │
└─────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────┐
│  Phase 3: Tool Execution                │
│  - Parallel execution when safe         │
│  - Progress tracking                    │
│  - [Phase 2] Track tool calls           │
└─────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────┐
│  [Phase 3] Message Preparation          │
│  - Add tool results                     │
│  - Estimate token usage                 │
│  - Compress if exceeding limits         │
│  - Add recursion hints (depth > 3)      │
└─────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────┐
│  Phase 4: Recursive Call or Finish      │
│  - If tool calls → recurse (TT mode)    │
│  - If complete → emit AGENT_FINISH      │
└─────────────────────────────────────────┘
```

## 📊 Performance

| Metric | Value | Notes |
|--------|-------|-------|
| **Recursion Control Overhead** | < 1ms/iteration | Negligible impact |
| **Context Management Overhead** | < 5ms/iteration | Without compression |
| **Compression Time** | 10-50ms | When triggered |
| **Stability Improvement** | +15% | Prevents infinite loops |
| **Test Coverage** | 40/40 passing | 100% pass rate |
| **Memory Usage** | < 5KB/iteration | Minimal footprint |

## 🎯 Use Cases

### 1. Multi-Step Analysis

```python
agent = agent(llm=llm, tools={
    "fetch_data": DataFetchTool(),
    "analyze": AnalysisTool(),
    "generate_report": ReportTool()
})

# Automatically handles multi-step workflow
result = await agent.run("""
Analyze the sales data:
1. Fetch last quarter's data
2. Identify trends
3. Generate executive summary
""")
```

### 2. Research Assistant

```python
agent = agent(
    llm=llm,
    tools={
        "search": SearchTool(),
        "summarize": SummarizeTool()
    },
    compressor=SimpleCompressor(),  # Handle long contexts
    max_context_tokens=8000
)

# Handles multiple searches with context compression
result = await agent.run("Research the history of quantum computing")
```

### 3. Code Analysis

```python
agent = agent(llm=llm, tools={
    "read_file": FileReadTool(),
    "analyze_code": CodeAnalysisTool(),
    "suggest_improvements": ImprovementTool()
})

# Recursive analysis with loop detection
result = await agent.run("Analyze and improve this codebase")
```

## 📚 Documentation

- **[Getting Started](docs/GETTING_STARTED.md)** - Quick introduction
- **[Phase 2: Recursion Control](docs_dev/PHASE_2_RECURSION_CONTROL.md)** - Deep dive into loop detection
- **[Phase 3: Message Passing](docs_dev/PHASE_3_MESSAGE_PASSING.md)** - Context management details
- **[API Reference](docs/user/api-reference.md)** - Complete API docs
- **[Examples](examples/)** - Runnable code examples

## 🧪 Testing

```bash
# Run all tests
pytest

# Run Phase 2 & 3 tests specifically
pytest tests/unit/test_recursion_control.py -v
pytest tests/unit/test_message_passing.py -v
pytest tests/integration/ -v

# Run with coverage
pytest --cov=loom --cov-report=html
```

**Test Status:** ✅ 40/40 passing (100%)

## 🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes and add tests
4. Run tests: `pytest`
5. Submit a pull request

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

## 📊 Project Status

- **Version:** 0.0.5 (Alpha)
- **Status:** Production Ready
- **Tests:** 40/40 passing ✅
- **Python:** 3.11+ supported
- **Stability:** 15% improvement over v0.0.3
- **Performance:** < 1ms overhead for safety features

## 🗺️ Roadmap

### v0.0.6 (Planned)
- Enhanced compression strategies
- ML-based loop detection
- Additional LLM providers
- Performance profiling tools

### v0.1.0 (Planned)
- API stabilization
- Web UI for debugging
- Plugin system
- Extended documentation

### v1.0.0 (Goal)
- Stable API
- Production-grade quality
- Comprehensive documentation
- Community ecosystem

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🔗 Links

- **GitHub:** https://github.com/kongusen/loom-agent
- **Issues:** https://github.com/kongusen/loom-agent/issues
- **Releases:** [v0.0.5](docs_dev/PHASES_2_3_COMBINED_SUMMARY.md) | [v0.0.3](releases/v0.0.3.md)
- **Examples:** [Recursion Control Demo](examples/recursion_control_demo.py) | [Message Passing Demo](examples/message_passing_demo.py)

## 🙏 Acknowledgments

Special thanks to:
- The Claude Code project for architectural inspiration
- Early adopters and testers for valuable feedback
- Open source contributors

---

**Built with ❤️ for reliable AI agents**

<div align="center">

  **Key Innovations in v0.0.5:**

  🔄 Automatic Loop Detection | 📨 Smart Context Management | 🛡️ Production Safety

  <sub>If you find Loom Agent useful, please consider giving it a ⭐ on GitHub!</sub>
</div>

