agent-os-kernel 1.1.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

modules/atr/CONTRIBUTING.md

@@ -0,0 +1,96 @@
+# Contributing to ATR
+
+Thank you for your interest in contributing to the Agent Tool Registry!
+
+## Development Setup
+
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/imran-siddique/atr.git
+   cd atr
+   ```
+
+2. **Create a virtual environment**
+   ```bash
+   python -m venv .venv
+   .venv\Scripts\activate  # Windows
+   # or
+   source .venv/bin/activate  # Unix/macOS
+   ```
+
+3. **Install development dependencies**
+   ```bash
+   pip install -e ".[dev]"
+   ```
+
+4. **Install pre-commit hooks**
+   ```bash
+   pre-commit install
+   ```
+
+## Code Style
+
+We use the following tools to maintain code quality:
+
+- **Ruff**: For linting and formatting
+- **MyPy**: For type checking
+- **pytest**: For testing
+
+### Running Checks Locally
+
+```bash
+# Linting
+ruff check .
+
+# Formatting
+ruff format .
+
+# Type checking
+mypy atr
+
+# Tests
+pytest
+```
+
+## Pull Request Guidelines
+
+1. **Fork** the repository and create a branch from `main`
+2. **Write tests** for any new functionality
+3. **Update documentation** if needed
+4. **Run all checks** before submitting
+5. **Write clear commit messages** following conventional commits
+
+### Commit Message Format
+
+```
+type(scope): description
+
+[optional body]
+
+[optional footer]
+```
+
+Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+
+## Testing
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=atr --cov-report=html
+
+# Run specific test file
+pytest tests/test_registry.py
+```
+
+## Documentation
+
+- Use Google-style docstrings
+- Include type hints for all parameters and return values
+- Add examples in docstrings where helpful
+
+## Questions?
+
+Open an issue on GitHub or reach out to the maintainers.

modules/atr/IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,143 @@
+# ATR Implementation Summary
+
+## Requirements Verification ✅
+
+All requirements from PRD 3 have been successfully implemented:
+
+### 1. Core Value Proposition ✅
+- Decentralized marketplace for capabilities
+- Standardized interface for tool discovery
+- Agent can request tools by capability (e.g., "scrape websites")
+- Works regardless of who built the tool or where it lives
+
+### 2. Technical Architecture ✅
+
+#### The Spec ✅
+- Rigorous JSON/Pydantic schema (similar to OpenAI Function Calling spec)
+- Defines inputs (ParameterSpec with strict types)
+- Defines outputs (return value specification)
+- Defines side effects (NONE, READ, WRITE, DELETE, NETWORK, FILESYSTEM)
+- Full type safety with Pydantic v2
+
+#### The Registry ✅
+- Lightweight lookup mechanism using local dictionary
+- Can be extended to use remote KV store
+- Methods: register_tool, get_tool, get_callable, list_tools, search_tools
+- Fast O(1) lookups by name
+- Filtered searches by tags, cost, side effects
+
+#### The Decorator ✅
+- Python decorator `@atr.register(name="scraper", cost="low")`
+- Instantly turns a Python function into a discoverable tool
+- Auto-extracts function signature
+- Validates type hints are present
+- Returns original function unchanged
+
+### 3. Dependency Rules ✅
+
+#### ✅ Allowed Dependencies
+- `pydantic>=2.0.0` - For schema validation
+- Python standard library (inspect, typing, enum)
+
+#### ❌ Strictly Forbidden (Verified Absent)
+- No `agent-control-plane` - Tools are standalone functions
+- No `mute-agent` - No specific agents hardcoded
+
+### 4. Anti-Patterns Avoided ✅
+
+#### ✅ Registry Does NOT Execute Tools
+- Verified with explicit tests
+- Registry only stores and returns functions
+- Agent Runtime (Control Plane) is responsible for execution
+
+#### ✅ No Magic Arguments
+- All tool inputs must be strictly typed
+- Decorator enforces type hints on all parameters
+- ValueError raised if type hints are missing
+- LLM knows exactly what to provide
+
+## Implementation Details
+
+### Package Structure
+```
+atr/
+├── __init__.py          # Main package exports
+├── schema.py            # Pydantic models
+├── registry.py          # Registry class
+└── decorator.py         # @register decorator
+
+tests/
+├── test_schema.py       # Schema tests (11 tests)
+├── test_registry.py     # Registry tests (19 tests)
+└── test_decorator.py    # Decorator tests (15 tests)
+
+examples/
+├── demo.py              # Working demo
+└── README.md            # Examples documentation
+```
+
+### Test Coverage
+- **Total Tests**: 45
+- **All Passing**: ✅
+- **Coverage Areas**:
+  - Schema validation and serialization
+  - Registry storage and retrieval
+  - Decorator functionality and type extraction
+  - OpenAI format conversion
+  - Anti-pattern prevention (no execution, no magic args)
+
+### Key Features
+
+1. **Strict Typing**: Every parameter must have a type annotation
+2. **Type Mapping**: Python types → ParameterType (str→STRING, int→INTEGER, etc.)
+3. **Complex Types**: Supports List[T], Dict[K,V], Optional[T]
+4. **Metadata Rich**: Tools have name, description, cost, tags, version, author, side effects
+5. **OpenAI Compatible**: One-line conversion to OpenAI function calling format
+6. **Search & Filter**: Find tools by name, description, tags, cost, side effects
+7. **Safe Design**: Registry never executes tools - only stores and returns them
+
+### PyPI Ready
+- `setup.py` configured for PyPI publication as `agent-tool-registry`
+- `pyproject.toml` with proper metadata
+- `requirements.txt` with minimal dependencies
+- Comprehensive README.md with examples
+- MIT License ready
+
+## Security
+
+- **CodeQL Analysis**: 0 vulnerabilities found
+- **No code execution in registry**: Explicitly tested and verified
+- **Input validation**: Pydantic ensures all data is validated
+- **Type safety**: Strong typing throughout prevents type confusion
+
+## Usage Example
+
+```python
+import atr
+
+# Register a tool
+@atr.register(name="scraper", cost="low", tags=["web"])
+def scrape_website(url: str, timeout: int = 30) -> str:
+    """Scrape content from a website."""
+    # Implementation here
+    pass
+
+# Discover tools
+tools = atr._global_registry.search_tools("scraper")
+
+# Get tool spec (doesn't execute!)
+spec = atr._global_registry.get_tool("scraper")
+
+# Convert to OpenAI format
+openai_schema = spec.to_openai_function_schema()
+
+# Agent Runtime executes (not the registry!)
+func = atr._global_registry.get_callable("scraper")
+result = func(url="https://example.com", timeout=10)
+```
+
+## Conclusion
+
+The Agent Tool Registry (ATR) has been fully implemented according to PRD 3 specifications. All requirements have been met, all tests pass, no security vulnerabilities exist, and the package is ready for PyPI publication as `agent-tool-registry`.
+
+**Status**: ✅ READY FOR PRODUCTION

modules/atr/README.md

@@ -0,0 +1,180 @@
+# ATR - Agent Tool Registry
+
+> **Part of [Agent OS](https://github.com/imran-siddique/agent-os)** - Kernel-level governance for AI agents
+
+[![PyPI version](https://badge.fury.io/py/agent-tool-registry.svg)](https://badge.fury.io/py/agent-tool-registry)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/imran-siddique/atr/test.yml?branch=main)](https://github.com/imran-siddique/atr/actions)
+
+**A type-safe, decentralized tool registry for autonomous agents. Part of the Agent OS ecosystem.**
+
+---
+
+## Why This Exists
+
+Most agent frameworks hardcode tools directly into their runtimes. This creates tight coupling: add a new capability, restart the entire system. Change a function signature, update dozens of agents. Scale by addition leads to fragility.
+
+**We built `atr` because tool registration should not require restarting your infrastructure.**  
+
+The Agent Tool Registry decouples tool providers from tool consumers. Agents discover capabilities at runtime through a standardized interface. We subtract the dependency between agent logic and tool implementation to add scale.
+
+This is **Scale by Subtraction** applied to the agent capability layer.
+
+---
+
+## Installation
+
+```bash
+pip install agent-tool-registry
+```
+
+For sandboxed execution with Docker:
+
+```bash
+pip install agent-tool-registry[sandbox]
+```
+
+---
+
+## Quick Start
+
+Register a tool in 5 lines:
+
+```python
+import atr
+
+@atr.register(name="calculator", tags=["math"])
+def add(a: int, b: int) -> int:
+    """Add two numbers."""
+    return a + b
+```
+
+Discover and execute:
+
+```python
+tool = atr.get_tool("calculator")
+schema = tool.to_openai_function_schema()  # OpenAI-compatible
+func = atr.get_callable("calculator")
+result = func(a=5, b=3)  # Returns 8
+
+# Or use sandboxed execution (recommended for untrusted code)
+from atr import DockerExecutor
+docker_exec = DockerExecutor()
+result = atr.execute_tool("calculator", {"a": 5, "b": 3}, executor=docker_exec)
+```
+
+---
+
+## Sandboxed Execution
+
+**NEW:** ATR now supports sandboxed execution using Docker containers. This is essential for running untrusted or agent-generated code safely.
+
+### Why Sandboxed Execution?
+
+SDLC agents and LLMs may generate Python or Bash scripts that you cannot safely run directly on your host machine. Sandboxed execution provides:
+
+- **Isolation**: Code runs in ephemeral containers, completely isolated from your host
+- **Security**: No network access, memory limits, automatic cleanup
+- **Safety**: Protects against malicious code, resource exhaustion, and unintended side effects
+
+### Usage
+
+```python
+import atr
+from atr import DockerExecutor
+
+# Register a tool
+@atr.register(name="processor", tags=["data"])
+def process_data(numbers: list) -> int:
+    """Process data safely in a sandbox."""
+    return sum(numbers)
+
+# Option 1: Direct execution (NOT sandboxed - trusted code only)
+result = atr.execute_tool("processor", {"numbers": [1, 2, 3, 4]})
+
+# Option 2: Sandboxed execution (RECOMMENDED for untrusted code)
+docker_exec = DockerExecutor()
+result = atr.execute_tool(
+    "processor",
+    {"numbers": [1, 2, 3, 4]},
+    executor=docker_exec,
+    timeout=30
+)
+```
+
+### Execution Modes
+
+| Feature | LocalExecutor | DockerExecutor |
+|---------|---------------|----------------|
+| Speed | Fast | Slower |
+| Security | No isolation | Full isolation |
+| Network | Full access | Disabled |
+| Use Case | Trusted code | Untrusted code |
+
+See `examples/sandbox_demo.py` for complete examples.
+
+---
+
+## Architecture
+
+`atr` sits in **Layer 2 (Infrastructure)** of the Agent OS stack.
+
+**Responsibility:** Tool registration, discovery, and schema generation.  
+**Not responsible for:** Tool execution (handled by the Agent Control Plane).
+
+### Design
+
+- **Registry:** In-memory dictionary-based lookup (local or distributed).
+- **Decorator:** `@atr.register()` extracts type signatures and validates strict typing.
+- **Spec:** Pydantic schema enforcing inputs, outputs, side effects, and metadata.
+- **Schema Export:** Converts to OpenAI, Anthropic, and other LLM function-calling formats.
+
+The registry stores specifications, not callables. Execution happens in the control plane with proper error handling and observability.
+
+---
+
+## The Ecosystem Map
+
+ATR is one component in a modular Agent OS. Each layer solves a specific problem:
+
+### Primitives (Layer 1)
+- **[caas](https://github.com/imran-siddique/caas)** - Context-as-a-Service: Manages agent memory and state.
+- **[cmvk](https://github.com/imran-siddique/cmvk)** - Context Merkle Verification Kit: Cryptographic verification of context integrity.
+- **[emk](https://github.com/imran-siddique/emk)** - Episodic Memory Kit: Long-term memory storage and retrieval.
+
+### Infrastructure (Layer 2)
+- **[iatp](https://github.com/imran-siddique/iatp)** - Inter-Agent Trust Protocol: Secure message authentication.
+- **[amb](https://github.com/imran-siddique/amb)** - Agent Message Bus: Decoupled event transport.
+- **[atr](https://github.com/imran-siddique/atr)** - Agent Tool Registry: Tool discovery and schema generation *(you are here)*.
+
+### Framework (Layer 3)
+- **[agent-control-plane](https://github.com/imran-siddique/agent-control-plane)** - The Core: Agent orchestration and lifecycle management.
+- **[scak](https://github.com/imran-siddique/scak)** - Self-Correction Agent Kit: Automated error recovery and learning.
+
+---
+
+## Citation
+
+If you use ATR in research, please cite:
+
+```bibtex
+@software{atr2024,
+  title={ATR: Agent Tool Registry},
+  author={Siddique, Imran},
+  year={2024},
+  url={https://github.com/imran-siddique/atr},
+  note={Part of the Agent OS ecosystem}
+}
+```
+
+---
+
+## License
+
+MIT License - See [LICENSE](LICENSE) for details.
+
+---
+
+**Repository:** https://github.com/imran-siddique/atr  
+**Documentation:** https://github.com/imran-siddique/atr#readme  
+**Issues:** https://github.com/imran-siddique/atr/issues