loopy-agent 0.4.0__tar.gz

loopy_agent-0.4.0/.gitignore

@@ -0,0 +1,51 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Build
+*.so
+*.dylib
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Loopy specific
+.cache/
+*.log
+workflow_traces.json

loopy_agent-0.4.0/CHANGELOG.md

@@ -0,0 +1,188 @@
+# 📋 Changelog
+
+All notable changes to loopy will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.4.0] - 2026-07-24
+
+### Added
+
+- **AudioPlugin** - Speech-to-text and text-to-speech integration
+  - `SpeechToText` - Whisper-compatible transcription
+  - `TextToSpeech` - Multi-voice synthesis
+  - Configurable providers (OpenAI, ElevenLabs, local)
+  
+- **MarketplacePlugin** - Plugin discovery and installation
+  - `PluginMarketplace` - Search, install, uninstall plugins
+  - PyPI integration for plugin distribution
+  - Cache for installed plugins
+  
+- **New tests** - 4 additional tests (59 total)
+
+### Changed
+
+- Version bumped to 0.4.0
+- Updated plugin lazy imports
+
+---
+
+## [0.3.0] - 2026-07-24
+
+### Added
+
+- **TraceExporter** - Export traces to external backends
+  - `export_file()` - Export to JSON file
+  - `export_stdout()` - Export to console
+  - `export_http()` - Export to Jaeger/Zipkin via HTTP
+  
+- **RAGPlugin** - Retrieval-Augmented Generation
+  - `Retriever` - Vector/keyword document search
+  - `Document` - Document storage with metadata
+  
+- **ToolsPlugin** - Tool registry for function calling
+  - `ToolRegistry` - Register and execute tools
+  - `Tool` - Tool schema generation (OpenAI format)
+  - Built-in calculator and JSON tools
+  
+- **MemoryPlugin** - Long-term agent memory
+  - `MemoryStore` - Persistent memory storage
+  - `Memory` - Memory entries with importance scoring
+  - JSON file persistence
+  
+- **New tests** - 6 additional tests (55 total)
+
+### Changed
+
+- Version bumped to 0.3.0
+- Updated plugins/__init__.py with lazy imports
+
+---
+
+## [0.2.0] - 2026-07-24
+
+### Added
+
+- **Evaluator-Optimizer Pattern** (2026 agentic workflow)
+  - `EvalGate` - LLM-as-judge evaluation gate
+  - `EvalGateType` - COMMAND, ARTIFACT, MANUAL, JUDGE
+  - `JudgeConfig` - Configure evaluation criteria and thresholds
+  - `EvalGateResult` - Pass/fail with score and feedback
+  
+- **Orchestrator-Workers Pattern**
+  - `Router` - Pattern-based task routing to specialist agents
+  - `RoutingRule` - Define routing patterns
+  - `TaskDecomposer` - Break tasks into subtasks with dependencies
+  - `SubTask` - Dependency-aware task execution
+  
+- **Async Context Managers**
+  - `Gateway` now supports `async with` for automatic cleanup
+  
+- **Connection Pooling**
+  - `ConnectionPool` - HTTP connection reuse for lower latency
+  
+- **New Middleware**
+  - `RetryMiddleware` - Auto-retry with exponential backoff
+  - `CircuitBreakerMiddleware` - Prevent cascade failures
+  - `FallbackMiddleware` - Provider failover
+  
+- **New tests** - 12 additional tests (49 total)
+
+### Changed
+
+- Version bumped to 0.2.0
+- Updated all exports in __init__.py
+- Enhanced Orchestrator with routing and decomposition
+
+---
+
+## [0.1.0] - 2026-07-24
+
+### Added
+
+- **Agentic Loop** (`loop.py`)
+  - `AgentLoop` - Plan → Act → Observe → Reflect cycle
+  - `LoopConfig` - Configure callbacks and stopping conditions
+  - `StepResult` - Track iteration results
+  
+- **AI Gateway** (`gateway.py`)
+  - `Gateway` - Multi-provider LLM routing
+  - `ModelProvider` - OpenAI, Anthropic, Ollama, Custom
+  - `ProviderConfig` - Provider configuration
+  - `GatewayResponse` - Unified response format
+  - Batch requests and streaming support
+  
+- **Guardrails** (`guardrails.py`)
+  - `GuardrailPipeline` - Input/output filtering
+  - PII detection (SSN, email, phone, credit card)
+  - Jailbreak detection
+  
+- **Evals** (`evals.py`)
+  - `Evaluator` - Judge-based model evaluation
+  - `EvalSuite` / `EvalCase` - Test case management
+  - Simple string matching and LLM judge support
+  
+- **Cache** (`cache.py`)
+  - `LLMCache` - Semantic token caching
+  - TTL and LRU eviction
+  - Hit rate tracking and cost estimation
+  
+- **Observability** (`observe.py`)
+  - `Tracer` - Distributed tracing
+  - `Span` - Operation tracking
+  - `MetricsCollector` - Counter/histogram/gauge metrics
+  
+- **MCP Client** (`mcp.py`)
+  - `MCPClient` - Model Context Protocol client
+  - `LocalMCP` - Local tool execution
+  
+- **Multi-Agent** (`agents.py`)
+  - `Orchestrator` - Agent pool management
+  - `SubAgent` - Individual agent configuration
+  
+- **Middleware** (`middleware.py`)
+  - `MiddlewarePipeline` - Composable request/response hooks
+  - Built-in: Logging, Timing, RateLimit, Cache, Validation, Function
+  
+- **Plugin System** (`plugins.py`)
+  - `Plugin` - Base plugin class
+  - `PluginRegistry` - Central component registry
+  - `PluginLoader` - Auto-discovery from packages/directories
+  
+- **CLI** (`cli.py`)
+  - Commands: info, chat, guard, cache, trace, eval, agent
+  
+- **Type Stubs** (`py.typed`, `_types.pyi`)
+  - Full IDE autocompletion support
+  
+- **Initial tests** - 37 tests passing
+
+---
+
+## Roadmap
+
+### v0.5.0 (Planned)
+- Streaming improvements
+- WebSocket support
+- Advanced vector embeddings
+- Rate limiting improvements
+
+### v0.6.0 (Planned)
+- Multi-modal support
+- Image generation tools
+- Code execution sandbox
+- Enhanced security features
+
+---
+
+## Version History Summary
+
+| Version | Tests | Key Features |
+|---------|-------|--------------|
+| 0.1.0 | 37 | Initial 8 concepts |
+| 0.2.0 | 49 | EvalGate, Router, Async, Middleware |
+| 0.3.0 | 55 | Plugins, OpenTelemetry, RAG, Tools, Memory |
+| 0.4.0 | 59 | Audio, Marketplace, Production Hardening |

loopy_agent-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,305 @@
+# 🤝 Contributing to Loopy
+
+Thank you for your interest in contributing to Loopy! This document provides guidelines and information for contributors.
+
+---
+
+## 📋 Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [Making Changes](#making-changes)
+- [Testing](#testing)
+- [Pull Request Process](#pull-request-process)
+- [Style Guidelines](#style-guidelines)
+- [Adding Features](#adding-features)
+- [Bug Reports](#bug-reports)
+
+---
+
+## 📜 Code of Conduct
+
+Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md). We are committed to providing a welcoming and inclusive environment for everyone.
+
+---
+
+## 🚀 Getting Started
+
+1. **Fork the repository** on GitHub
+2. **Clone your fork** locally:
+   ```bash
+   git clone https://github.com/your-username/loopy.git
+   cd loopy
+   ```
+3. **Add upstream remote**:
+   ```bash
+   git remote add upstream https://github.com/Dream-Pixels-Forge/loopy.git
+   ```
+
+---
+
+## 🛠️ Development Setup
+
+### Prerequisites
+
+- Python 3.11+
+- pip or poetry
+
+### Installation
+
+```bash
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # Linux/Mac
+# or
+venv\Scripts\activate  # Windows
+
+# Install in development mode
+pip install -e ".[dev]"
+
+# Install pre-commit hooks (optional)
+pip install pre-commit
+pre-commit install
+```
+
+### Project Structure
+
+```
+loopy/
+├── loopy/              # Source code
+│   ├── __init__.py     # Public API exports
+│   ├── loop.py         # Agentic loop engine
+│   ├── gateway.py      # AI Gateway
+│   ├── guardrails.py   # Guardrails
+│   ├── evals.py        # Evals + EvalGate
+│   ├── cache.py        # LLM Cache
+│   ├── observe.py      # Observability
+│   ├── mcp.py          # MCP Client
+│   ├── agents.py       # Multi-Agent
+│   ├── middleware.py    # Middleware
+│   ├── cli.py          # CLI
+│   └── plugins/        # First-party plugins
+│       ├── __init__.py
+│       ├── rag.py
+│       ├── tools.py
+│       ├── memory.py
+│       ├── audio.py
+│       └── marketplace.py
+├── tests/              # Test suite
+├── docs/               # Documentation
+├── examples/           # Usage examples
+└── pyproject.toml      # Project configuration
+```
+
+---
+
+## ✏️ Making Changes
+
+### Branch Naming
+
+Use descriptive branch names:
+- `feature/add-new-middleware`
+- `fix/cache-eviction-bug`
+- `docs/update-api-reference`
+- `refactor/improve-gateway`
+
+### Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+- `feat: add new RetryMiddleware`
+- `fix: resolve cache eviction issue`
+- `docs: update API reference`
+- `refactor: improve gateway performance`
+- `test: add tests for RAG plugin`
+
+---
+
+## 🧪 Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with verbose output
+pytest -v
+
+# Run specific test file
+pytest tests/test_loopy.py
+
+# Run specific test class
+pytest tests/test_loopy.py::TestAgentLoop
+
+# Run with coverage
+pytest --cov=loopy --cov-report=html
+```
+
+### Writing Tests
+
+- Place tests in `tests/` directory
+- Name test files `test_<module>.py`
+- Use `pytest` fixtures when appropriate
+- Aim for high coverage (80%+ target)
+
+Example test:
+
+```python
+import asyncio
+from loopy import AgentLoop, LoopConfig
+
+def test_basic_loop():
+    """Test basic agent loop execution."""
+    async def planner(history):
+        return "Test plan"
+    
+    async def actor(plan):
+        return "Test action"
+    
+    loop = AgentLoop(LoopConfig(
+        planner=planner,
+        actor=actor,
+        max_steps=1,
+    ))
+    
+    async def run_test():
+        results = await loop.run()
+        assert len(results) == 1
+        assert results[0].status == StepStatus.COMPLETE
+    
+    asyncio.run(run_test())
+```
+
+---
+
+## 🔀 Pull Request Process
+
+1. **Create a feature branch** from `main`
+2. **Make your changes** with tests
+3. **Run the test suite** to ensure everything passes
+4. **Update documentation** if needed
+5. **Submit a pull request** with:
+   - Clear title and description
+   - Link to related issues
+   - Screenshots (if applicable)
+
+### PR Checklist
+
+- [ ] Tests pass locally
+- [ ] New tests added for new features
+- [ ] Documentation updated
+- [ ] Type hints added/updated
+- [ ] No breaking changes (or documented in CHANGELOG)
+- [ ] Code follows style guidelines
+
+---
+
+## 📏 Style Guidelines
+
+### Python Style
+
+- Follow PEP 8
+- Use type hints consistently
+- Maximum line length: 100 characters
+- Use f-strings for string formatting
+
+### Docstrings
+
+Use Google-style docstrings:
+
+```python
+def my_function(param1: str, param2: int = 10) -> bool:
+    """
+    Brief description of the function.
+
+    Longer description if needed.
+
+    Args:
+        param1: Description of param1
+        param2: Description of param2
+
+    Returns:
+        Description of return value
+
+    Raises:
+        ValueError: When something is wrong
+
+    Example:
+        >>> result = my_function("hello", 5)
+        >>> print(result)
+        True
+    """
+```
+
+### Import Order
+
+```python
+# Standard library
+import asyncio
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+# Third-party
+import httpx
+
+# Local
+from loopy.gateway import Gateway
+```
+
+---
+
+## ➕ Adding Features
+
+### Adding a New Module
+
+1. Create `loopy/new_module.py`
+2. Add exports to `loopy/__init__.py`
+3. Add to `__all__` list
+4. Write tests in `tests/test_new_module.py`
+5. Update documentation
+
+### Adding a New Plugin
+
+1. Create `loopy/plugins/new_plugin.py`
+2. Implement `Plugin` base class
+3. Add lazy import to `loopy/plugins/__init__.py`
+4. Write tests in `tests/test_loopy.py`
+5. Document in docs/README.md
+
+### Adding Middleware
+
+1. Create class inheriting from `Middleware`
+2. Implement `before()`, `after()`, and/or `on_error()`
+3. Add to `loopy/middleware.py`
+4. Export in `loopy/__init__.py`
+5. Write tests
+
+---
+
+## 🐛 Bug Reports
+
+When filing a bug report, please include:
+
+1. **Environment** (Python version, OS)
+2. **Steps to reproduce**
+3. **Expected behavior**
+4. **Actual behavior**
+5. **Error messages/tracebacks**
+6. **Minimal code example**
+
+---
+
+## 📚 Resources
+
+- [Documentation](docs/README.md)
+- [API Reference](docs/README.md#api-reference)
+- [Examples](examples/)
+- [Changelog](CHANGELOG.md)
+
+---
+
+## 🙏 Thank You!
+
+Thank you for contributing to Loopy! Your help is appreciated.