loom-agent 0.0.1__tar.gz → 0.0.2__tar.gz

loom_agent-0.0.2/PKG-INFO

@@ -0,0 +1,295 @@
+Metadata-Version: 2.4
+Name: loom-agent
+Version: 0.0.2
+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 observability**
+
+[![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-18%2F18%20passing-brightgreen.svg)](tests/)
+
+[Documentation](docs/user/user-guide.md) | [API Reference](docs/user/api-reference.md) | [Contributing](CONTRIBUTING.md)
+
+</div>
+
+---
+
+## 🎯 What is Loom Agent?
+
+Loom Agent is a Python framework for building reliable AI agents with production-grade features like automatic retries, context compression, persistent memory, and comprehensive observability.
+
+**Key Features:**
+
+- 🚀 **Simple API** - Get started with just 3 lines of code
+- 🔧 **Tool System** - Easy decorator-based tool creation
+- 💾 **Persistent Memory** - Cross-session conversation history
+- 📊 **Observability** - Structured logging with correlation IDs
+- 🛡️ **Production Ready** - Circuit breakers, retries, and failover
+- ⚡ **High Performance** - Parallel tool execution and smart context compression
+- 🌐 **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 MockLLM
+
+async def main():
+    # Create an agent
+    my_agent = agent(llm=MockLLM())
+
+    # Run it
+    result = await my_agent.run("Hello, world!")
+    print(result)
+
+asyncio.run(main())
+```
+
+### With OpenAI
+
+```python
+from loom import agent
+
+# Create agent with OpenAI
+my_agent = agent(
+    provider="openai",
+    model="gpt-4",
+    api_key="sk-..."  # or set OPENAI_API_KEY env var
+)
+
+result = await my_agent.run("What is the capital of France?")
+print(result)
+```
+
+### Custom Tools
+
+```python
+from loom import agent, tool
+
+@tool()
+def add(a: int, b: int) -> int:
+    """Add two numbers together"""
+    return a + b
+
+my_agent = agent(
+    provider="openai",
+    model="gpt-4",
+    tools=[add()]
+)
+
+result = await my_agent.run("What is 15 plus 27?")
+print(result)
+```
+
+## 📚 Documentation
+
+- **[Getting Started](docs/user/getting-started.md)** - Your first Loom agent in 5 minutes
+- **[User Guide](docs/user/user-guide.md)** - Complete usage documentation
+- **[API Reference](docs/user/api-reference.md)** - Detailed API documentation
+- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute
+
+## 🛠️ Core Components
+
+### Agent Builder
+```python
+from loom import agent
+
+my_agent = agent(
+    provider="openai",      # LLM provider
+    model="gpt-4",          # Model name
+    tools=[...],            # Custom tools
+    memory=...,             # Memory system
+    callbacks=[...]         # Observability
+)
+```
+
+### Tool Decorator
+```python
+from loom import tool
+
+@tool(description="Fetch weather data")
+def get_weather(city: str) -> dict:
+    return {"temp": 72, "condition": "sunny"}
+```
+
+### Memory System
+```python
+from loom import PersistentMemory
+
+memory = PersistentMemory()  # Conversations persist across restarts
+agent = agent(llm=..., memory=memory)
+```
+
+### Observability
+```python
+from loom import ObservabilityCallback, MetricsAggregator
+
+obs = ObservabilityCallback()
+metrics = MetricsAggregator()
+
+agent = agent(llm=..., callbacks=[obs, metrics])
+```
+
+## 🎯 Supported Platforms
+
+- **Python:** 3.11, 3.12
+- **Operating Systems:** Linux, macOS, Windows
+- **LLM Providers:** OpenAI, Anthropic, Ollama
+
+## ⚠️ Alpha Release Notice
+
+**This is v0.0.1 - our first Alpha release!**
+
+While Loom Agent includes production-grade features, this is an early release. You may experience:
+
+- API changes in future versions
+- Incomplete edge case handling
+- Evolving documentation
+
+We welcome your feedback and contributions to help improve the framework!
+
+**What works well:**
+- ✅ Core agent execution
+- ✅ Tool system and decorators
+- ✅ Basic memory and context management
+- ✅ OpenAI integration
+- ✅ Structured logging
+
+**Coming soon:**
+- More LLM provider integrations
+- Enhanced tool library
+- Performance optimizations
+- Additional examples and tutorials
+
+## 🤝 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: `poetry run pytest`
+5. Submit a pull request
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+
+## 📊 Project Status
+
+- **Version:** 0.0.1 (Alpha)
+- **Status:** Active Development
+- **Tests:** 18/18 passing ✅
+- **Python:** 3.11+ supported
+
+## 🗺️ Roadmap
+
+### v0.1.0 (Planned)
+- API stabilization
+- More examples and tutorials
+- Performance optimizations
+- Extended documentation
+
+### v0.2.0 (Planned)
+- Additional LLM providers
+- Plugin system
+- Web UI for debugging
+
+### 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
+
+- **PyPI:** https://pypi.org/project/loom-agent/
+- **GitHub:** https://github.com/kongusen/loom-agent
+- **Issues:** https://github.com/kongusen/loom-agent/issues
+- **Releases:** [v0.0.1](releases/v0.0.1.md)
+
+## 🙏 Acknowledgments
+
+Special thanks to the Claude Code project for inspiration and to all early testers and contributors!
+
+---
+
+**Built with ❤️ for the AI community**
+
+<div align="center">
+  <sub>If you find Loom Agent useful, please consider giving it a ⭐ on GitHub!</sub>
+</div>
+

loom_agent-0.0.2/README.md

@@ -0,0 +1,242 @@
+# Loom Agent
+
+<div align="center">
+
+**Production-ready Python Agent framework with enterprise-grade reliability and observability**
+
+[![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-18%2F18%20passing-brightgreen.svg)](tests/)
+
+[Documentation](docs/user/user-guide.md) | [API Reference](docs/user/api-reference.md) | [Contributing](CONTRIBUTING.md)
+
+</div>
+
+---
+
+## 🎯 What is Loom Agent?
+
+Loom Agent is a Python framework for building reliable AI agents with production-grade features like automatic retries, context compression, persistent memory, and comprehensive observability.
+
+**Key Features:**
+
+- 🚀 **Simple API** - Get started with just 3 lines of code
+- 🔧 **Tool System** - Easy decorator-based tool creation
+- 💾 **Persistent Memory** - Cross-session conversation history
+- 📊 **Observability** - Structured logging with correlation IDs
+- 🛡️ **Production Ready** - Circuit breakers, retries, and failover
+- ⚡ **High Performance** - Parallel tool execution and smart context compression
+- 🌐 **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 MockLLM
+
+async def main():
+    # Create an agent
+    my_agent = agent(llm=MockLLM())
+
+    # Run it
+    result = await my_agent.run("Hello, world!")
+    print(result)
+
+asyncio.run(main())
+```
+
+### With OpenAI
+
+```python
+from loom import agent
+
+# Create agent with OpenAI
+my_agent = agent(
+    provider="openai",
+    model="gpt-4",
+    api_key="sk-..."  # or set OPENAI_API_KEY env var
+)
+
+result = await my_agent.run("What is the capital of France?")
+print(result)
+```
+
+### Custom Tools
+
+```python
+from loom import agent, tool
+
+@tool()
+def add(a: int, b: int) -> int:
+    """Add two numbers together"""
+    return a + b
+
+my_agent = agent(
+    provider="openai",
+    model="gpt-4",
+    tools=[add()]
+)
+
+result = await my_agent.run("What is 15 plus 27?")
+print(result)
+```
+
+## 📚 Documentation
+
+- **[Getting Started](docs/user/getting-started.md)** - Your first Loom agent in 5 minutes
+- **[User Guide](docs/user/user-guide.md)** - Complete usage documentation
+- **[API Reference](docs/user/api-reference.md)** - Detailed API documentation
+- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute
+
+## 🛠️ Core Components
+
+### Agent Builder
+```python
+from loom import agent
+
+my_agent = agent(
+    provider="openai",      # LLM provider
+    model="gpt-4",          # Model name
+    tools=[...],            # Custom tools
+    memory=...,             # Memory system
+    callbacks=[...]         # Observability
+)
+```
+
+### Tool Decorator
+```python
+from loom import tool
+
+@tool(description="Fetch weather data")
+def get_weather(city: str) -> dict:
+    return {"temp": 72, "condition": "sunny"}
+```
+
+### Memory System
+```python
+from loom import PersistentMemory
+
+memory = PersistentMemory()  # Conversations persist across restarts
+agent = agent(llm=..., memory=memory)
+```
+
+### Observability
+```python
+from loom import ObservabilityCallback, MetricsAggregator
+
+obs = ObservabilityCallback()
+metrics = MetricsAggregator()
+
+agent = agent(llm=..., callbacks=[obs, metrics])
+```
+
+## 🎯 Supported Platforms
+
+- **Python:** 3.11, 3.12
+- **Operating Systems:** Linux, macOS, Windows
+- **LLM Providers:** OpenAI, Anthropic, Ollama
+
+## ⚠️ Alpha Release Notice
+
+**This is v0.0.1 - our first Alpha release!**
+
+While Loom Agent includes production-grade features, this is an early release. You may experience:
+
+- API changes in future versions
+- Incomplete edge case handling
+- Evolving documentation
+
+We welcome your feedback and contributions to help improve the framework!
+
+**What works well:**
+- ✅ Core agent execution
+- ✅ Tool system and decorators
+- ✅ Basic memory and context management
+- ✅ OpenAI integration
+- ✅ Structured logging
+
+**Coming soon:**
+- More LLM provider integrations
+- Enhanced tool library
+- Performance optimizations
+- Additional examples and tutorials
+
+## 🤝 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: `poetry run pytest`
+5. Submit a pull request
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+
+## 📊 Project Status
+
+- **Version:** 0.0.1 (Alpha)
+- **Status:** Active Development
+- **Tests:** 18/18 passing ✅
+- **Python:** 3.11+ supported
+
+## 🗺️ Roadmap
+
+### v0.1.0 (Planned)
+- API stabilization
+- More examples and tutorials
+- Performance optimizations
+- Extended documentation
+
+### v0.2.0 (Planned)
+- Additional LLM providers
+- Plugin system
+- Web UI for debugging
+
+### 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
+
+- **PyPI:** https://pypi.org/project/loom-agent/
+- **GitHub:** https://github.com/kongusen/loom-agent
+- **Issues:** https://github.com/kongusen/loom-agent/issues
+- **Releases:** [v0.0.1](releases/v0.0.1.md)
+
+## 🙏 Acknowledgments
+
+Special thanks to the Claude Code project for inspiration and to all early testers and contributors!
+
+---
+
+**Built with ❤️ for the AI community**
+
+<div align="center">
+  <sub>If you find Loom Agent useful, please consider giving it a ⭐ on GitHub!</sub>
+</div>

{loom_agent-0.0.1 → loom_agent-0.0.2}/loom/builtin/tools/calculator.py

@@ -18,6 +18,10 @@ class Calculator(BaseTool):
     description = "Evaluate simple arithmetic expressions"
     args_schema = CalcArgs
 
+    # 🆕 Loom 2.0 - Orchestration attributes
+    is_read_only = True  # Pure computation, no side effects
+    category = "general"
+
     async def run(self, **kwargs) -> Any:
         expr = kwargs.get("expression", "")
         return str(_safe_eval(expr))

{loom_agent-0.0.1 → loom_agent-0.0.2}/loom/builtin/tools/document_search.py

@@ -48,6 +48,11 @@ class DocumentSearchTool(BaseTool):
     """
 
     name = "search_documents"
+
+    # 🆕 Loom 2.0 - Orchestration attributes
+    is_read_only = True  # Only searches documents, no modifications
+    category = "general"
+
     description = (
         "Search for relevant documents from the knowledge base. "
         "Use this when you need specific information that might be in the documents. "

{loom_agent-0.0.1 → loom_agent-0.0.2}/loom/builtin/tools/glob.py

@@ -19,6 +19,10 @@ class GlobTool(BaseTool):
     description = "按模式匹配文件路径"
     args_schema = GlobArgs
 
+    # 🆕 Loom 2.0 - Orchestration attributes
+    is_read_only = True
+    category = "general"
+
     async def run(self, **kwargs) -> Any:
         args = self.args_schema(**kwargs)  # type: ignore
         cwd = Path(args.cwd).expanduser() if args.cwd else Path.cwd()

{loom_agent-0.0.1 → loom_agent-0.0.2}/loom/builtin/tools/grep.py

@@ -22,6 +22,10 @@ class GrepTool(BaseTool):
     description = "在文件或文件集内检索正则匹配"
     args_schema = GrepArgs
 
+    # 🆕 Loom 2.0 - Orchestration attributes
+    is_read_only = True
+    category = "general"
+
     async def run(self, **kwargs) -> Any:
         args = self.args_schema(**kwargs)  # type: ignore
         flags = 0

{loom_agent-0.0.1 → loom_agent-0.0.2}/loom/builtin/tools/http_request.py

@@ -35,6 +35,11 @@ class HTTPRequestTool(BaseTool):
     args_schema = HTTPRequestInput
     is_concurrency_safe = True
 
+    # 🆕 Loom 2.0 - Orchestration attributes
+    is_read_only = False  # POST/PUT/DELETE may modify remote state
+    category = "network"  # Network operation
+    requires_confirmation = False  # Usually safe, but depends on usage
+
     def __init__(self, timeout: int = 10) -> None:
         if httpx is None:
             raise ImportError("Please install httpx: pip install httpx")

{loom_agent-0.0.1 → loom_agent-0.0.2}/loom/builtin/tools/python_repl.py

@@ -33,6 +33,11 @@ class PythonREPLTool(BaseTool):
     args_schema = PythonREPLInput
     is_concurrency_safe = False  # 代码执行不并发安全
 
+    # 🆕 Loom 2.0 - Orchestration attributes
+    is_read_only = False  # Code execution may have side effects
+    category = "destructive"  # Potentially dangerous
+    requires_confirmation = True  # Should require user confirmation
+
     async def run(self, code: str, **kwargs: Any) -> str:
         """执行 Python 代码"""
         # 安全性检查 - 禁止危险操作

{loom_agent-0.0.1 → loom_agent-0.0.2}/loom/builtin/tools/read_file.py

@@ -19,6 +19,10 @@ class ReadFileTool(BaseTool):
     description = "读取文本文件内容"
     args_schema = ReadArgs
 
+    # 🆕 Loom 2.0 - Orchestration attributes
+    is_read_only = True
+    category = "general"
+
     async def run(self, **kwargs) -> Any:
         args = self.args_schema(**kwargs)  # type: ignore
         p = Path(args.path).expanduser()

{loom_agent-0.0.1 → loom_agent-0.0.2}/loom/builtin/tools/task.py

@@ -47,6 +47,11 @@ class TaskTool(BaseTool):
     args_schema = TaskInput
     is_concurrency_safe = True
 
+    # 🆕 Loom 2.0 - Orchestration attributes
+    is_read_only = False  # Sub-agent may use write tools
+    category = "general"  # Not inherently dangerous, but depends on sub-agent's tools
+    requires_confirmation = False
+
     def __init__(
         self,
         agent_factory: Optional[callable] = None,

{loom_agent-0.0.1 → loom_agent-0.0.2}/loom/builtin/tools/web_search.py

@@ -33,6 +33,10 @@ class WebSearchTool(BaseTool):
     args_schema = WebSearchInput
     is_concurrency_safe = True
 
+    # 🆕 Loom 2.0 - Orchestration attributes
+    is_read_only = True  # Only reads from web, no local side effects
+    category = "network"
+
     def __init__(self) -> None:
         if DDGS is None:
             raise ImportError(

{loom_agent-0.0.1 → loom_agent-0.0.2}/loom/builtin/tools/write_file.py

@@ -20,6 +20,10 @@ class WriteFileTool(BaseTool):
     description = "写入文本到文件（可能覆盖）"
     args_schema = WriteArgs
 
+    # 🆕 Loom 2.0 - Orchestration attributes
+    is_read_only = False
+    category = "destructive"
+
     async def run(self, **kwargs) -> Any:
         args = self.args_schema(**kwargs)  # type: ignore
         p = Path(args.path).expanduser()