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

modules/atr/docs/PYPI_SETUP.md

@@ -0,0 +1,113 @@
+# PyPI Publishing Setup Guide
+
+This guide explains how to configure **Trusted Publishing** (OIDC) for automatic PyPI releases.
+
+## Prerequisites
+
+1. A PyPI account at [pypi.org](https://pypi.org)
+2. Repository owner/admin access on GitHub
+
+## Step 1: Reserve the Package Name on PyPI (First Time Only)
+
+If this is a new package, do an initial publish manually:
+
+```bash
+# Build the package
+python -m build
+
+# Upload to TestPyPI first (recommended)
+python -m twine upload --repository testpypi dist/*
+
+# Then upload to PyPI
+python -m twine upload dist/*
+```
+
+## Step 2: Configure Trusted Publishing on PyPI
+
+1. Go to [pypi.org](https://pypi.org) and log in
+2. Navigate to your project: **Your projects** → **agent-tool-registry**
+3. Go to **Settings** → **Publishing**
+4. Under "Add a new pending publisher" or "Add a new trusted publisher":
+
+   | Field | Value |
+   |-------|-------|
+   | **Owner** | `imran-siddique` |
+   | **Repository name** | `atr` |
+   | **Workflow name** | `publish.yml` |
+   | **Environment name** | `pypi` |
+
+5. Click **Add**
+
+## Step 3: Configure TestPyPI (Optional but Recommended)
+
+Repeat the same steps on [test.pypi.org](https://test.pypi.org):
+
+| Field | Value |
+|-------|-------|
+| **Owner** | `imran-siddique` |
+| **Repository name** | `atr` |
+| **Workflow name** | `publish.yml` |
+| **Environment name** | `testpypi` |
+
+## Step 4: Create GitHub Environments
+
+1. Go to your GitHub repository: `github.com/imran-siddique/atr`
+2. Navigate to **Settings** → **Environments**
+3. Create two environments:
+
+### Environment: `pypi`
+- Click **New environment**
+- Name: `pypi`
+- Add protection rules (recommended):
+  - ✅ Required reviewers (optional, for manual approval)
+  - ✅ Deployment branches: `main` only
+
+### Environment: `testpypi`
+- Click **New environment**
+- Name: `testpypi`
+- No protection rules needed (for testing)
+
+## Step 5: Create a Release
+
+1. Go to **Releases** → **Create a new release**
+2. Create a new tag: `v0.1.0`
+3. Set the release title: `v0.1.0 - Initial Release`
+4. Write release notes
+5. Click **Publish release**
+
+The GitHub Action will automatically:
+1. Run tests
+2. Build the package
+3. Publish to PyPI using OIDC (no tokens needed!)
+
+## Troubleshooting
+
+### "Trusted publisher not found"
+- Verify the workflow filename matches exactly (`publish.yml`)
+- Verify the environment name matches exactly (`pypi`)
+- Check that the GitHub repository owner/name match
+
+### "Permission denied"
+- Ensure `id-token: write` permission is set in the workflow
+- Verify the environment is created in GitHub
+
+## Manual Publishing (Fallback)
+
+If OIDC fails, you can use API tokens:
+
+1. Create an API token on PyPI (Account Settings → API tokens)
+2. Add it as a GitHub secret: `PYPI_API_TOKEN`
+3. Modify the workflow to use the token:
+
+```yaml
+- name: Publish to PyPI
+  uses: pypa/gh-action-pypi-publish@release/v1
+  with:
+    password: ${{ secrets.PYPI_API_TOKEN }}
+```
+
+## References
+
+- [PyPI Trusted Publishers](https://docs.pypi.org/trusted-publishers/)
+- [GitHub OIDC](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+- [pypa/gh-action-pypi-publish](https://github.com/pypa/gh-action-pypi-publish)

modules/atr/examples/README.md

@@ -0,0 +1,27 @@
+# Examples
+
+This directory contains examples demonstrating how to use the ATR (Agent Tool Registry).
+
+## demo.py
+
+A comprehensive demonstration of ATR features including:
+
+- Tool registration with the `@atr.register()` decorator
+- Tool discovery and search capabilities
+- Tool specification retrieval
+- OpenAI function calling format conversion
+- Tool execution (by the Agent Runtime)
+
+### Running the Demo
+
+```bash
+python examples/demo.py
+```
+
+## Key Concepts Demonstrated
+
+1. **No Magic Arguments**: All parameters must have type hints
+2. **Registry doesn't execute**: Tools are stored and returned, execution is separate
+3. **Strict typing**: Full type safety with Pydantic validation
+4. **OpenAI compatibility**: Easy conversion to OpenAI function calling format
+5. **Metadata-rich**: Tools have cost, tags, side effects, and more

modules/atr/examples/demo.py

@@ -0,0 +1,144 @@
+"""
+Example usage of the ATR (Agent Tool Registry).
+
+This example demonstrates how to register tools, discover them, and execute them.
+"""
+
+import atr
+from typing import List
+
+
+# Example 1: Simple web scraper tool
+@atr.register(name="web_scraper", cost="low", tags=["web", "scraping"], side_effects=["network"])
+def scrape_website(url: str, timeout: int = 30) -> str:
+    """Scrape content from a website.
+    
+    Args:
+        url: The URL to scrape
+        timeout: Request timeout in seconds
+    """
+    # Simulated implementation
+    return f"Content from {url} (timeout: {timeout}s)"
+
+
+# Example 2: File reader with side effects
+@atr.register(
+    name="file_reader",
+    cost="low",
+    side_effects=["read", "filesystem"],
+    tags=["file", "io"]
+)
+def read_file(path: str, encoding: str = "utf-8") -> str:
+    """Read a file from disk."""
+    # Simulated implementation
+    return f"Content of {path} (encoding: {encoding})"
+
+
+# Example 3: Calculator tool
+@atr.register(name="calculator", tags=["math"])
+def calculate(operation: str, a: float, b: float) -> float:
+    """Perform basic arithmetic operations.
+    
+    Args:
+        operation: The operation (add, subtract, multiply, divide)
+        a: First number
+        b: Second number
+    """
+    if operation == "add":
+        return a + b
+    elif operation == "subtract":
+        return a - b
+    elif operation == "multiply":
+        return a * b
+    elif operation == "divide":
+        return a / b if b != 0 else 0
+    return 0
+
+
+# Example 4: Complex types
+@atr.register(name="list_processor", tags=["data"])
+def process_items(items: List[str], reverse: bool = False) -> List[str]:
+    """Process a list of items.
+    
+    Args:
+        items: List of strings to process
+        reverse: Whether to reverse the list
+    """
+    result = [item.upper() for item in items]
+    if reverse:
+        result.reverse()
+    return result
+
+
+def main():
+    """Demonstrate ATR usage."""
+    print("=" * 60)
+    print("ATR - Agent Tool Registry Demo")
+    print("=" * 60)
+    
+    # Discover tools
+    print("\n1. Listing all registered tools:")
+    print("-" * 60)
+    all_tools = atr._global_registry.list_tools()
+    for tool in all_tools:
+        print(f"  - {tool.metadata.name}: {tool.metadata.description[:50]}...")
+    
+    # Search for tools
+    print("\n2. Searching for 'web' tools:")
+    print("-" * 60)
+    web_tools = atr._global_registry.search_tools("web")
+    for tool in web_tools:
+        print(f"  - {tool.metadata.name}: {tool.metadata.description[:50]}...")
+    
+    # Filter by tags
+    print("\n3. Filtering tools by tag 'file':")
+    print("-" * 60)
+    file_tools = atr._global_registry.list_tools(tag="file")
+    for tool in file_tools:
+        print(f"  - {tool.metadata.name}: {tool.metadata.description[:50]}...")
+    
+    # Get a specific tool
+    print("\n4. Getting tool specification:")
+    print("-" * 60)
+    scraper_spec = atr._global_registry.get_tool("web_scraper")
+    print(f"  Name: {scraper_spec.metadata.name}")
+    print(f"  Description: {scraper_spec.metadata.description}")
+    print(f"  Cost: {scraper_spec.metadata.cost}")
+    print(f"  Side Effects: {scraper_spec.metadata.side_effects}")
+    print(f"  Tags: {scraper_spec.metadata.tags}")
+    print(f"  Parameters:")
+    for param in scraper_spec.parameters:
+        required = "required" if param.required else f"optional (default: {param.default})"
+        print(f"    - {param.name} ({param.type.value}): {required}")
+    
+    # Convert to OpenAI format
+    print("\n5. Converting to OpenAI function calling format:")
+    print("-" * 60)
+    openai_schema = scraper_spec.to_openai_function_schema()
+    import json
+    print(json.dumps(openai_schema, indent=2))
+    
+    # Execute a tool (this is what the Agent Runtime would do)
+    print("\n6. Executing tools (Agent Runtime responsibility):")
+    print("-" * 60)
+    
+    # Get the callable and execute
+    scraper_func = atr._global_registry.get_callable("web_scraper")
+    result = scraper_func(url="https://example.com", timeout=10)
+    print(f"  Scraper result: {result}")
+    
+    calc_func = atr._global_registry.get_callable("calculator")
+    result = calc_func("multiply", 7, 6)
+    print(f"  Calculator result: {result}")
+    
+    processor_func = atr._global_registry.get_callable("list_processor")
+    result = processor_func(["hello", "world"], reverse=True)
+    print(f"  Processor result: {result}")
+    
+    print("\n" + "=" * 60)
+    print("Demo complete!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

modules/atr/examples/sandbox_demo.py

@@ -0,0 +1,218 @@
+"""
+Example demonstrating sandboxed execution with ATR.
+
+This example shows how to use Docker-based sandboxed execution
+to safely run untrusted code in isolated containers.
+"""
+
+import atr
+from typing import List
+
+
+# Register some example tools
+@atr.register(name="safe_calculator", cost="free", tags=["math", "sandbox"])
+def safe_calculate(operation: str, a: float, b: float) -> float:
+    """Perform basic arithmetic operations in a sandboxed environment.
+    
+    Args:
+        operation: The operation (add, subtract, multiply, divide)
+        a: First number
+        b: Second number
+    """
+    if operation == "add":
+        return a + b
+    elif operation == "subtract":
+        return a - b
+    elif operation == "multiply":
+        return a * b
+    elif operation == "divide":
+        return a / b if b != 0 else 0
+    return 0
+
+
+@atr.register(name="text_processor", cost="low", tags=["text", "sandbox"])
+def process_text(text: str, operation: str = "upper") -> str:
+    """Process text with various operations.
+    
+    Args:
+        text: The text to process
+        operation: The operation (upper, lower, reverse, title)
+    """
+    if operation == "upper":
+        return text.upper()
+    elif operation == "lower":
+        return text.lower()
+    elif operation == "reverse":
+        return text[::-1]
+    elif operation == "title":
+        return text.title()
+    return text
+
+
+@atr.register(name="list_analyzer", cost="low", tags=["data", "sandbox"])
+def analyze_list(numbers: List[float]) -> dict:
+    """Analyze a list of numbers and return statistics.
+    
+    Args:
+        numbers: List of numbers to analyze
+    """
+    if not numbers:
+        return {"count": 0, "sum": 0, "min": 0, "max": 0, "avg": 0}
+    
+    return {
+        "count": len(numbers),
+        "sum": sum(numbers),
+        "min": min(numbers),
+        "max": max(numbers),
+        "avg": sum(numbers) / len(numbers),
+    }
+
+
+def main():
+    """Demonstrate sandboxed execution."""
+    print("=" * 70)
+    print("ATR - Sandboxed Execution Demo")
+    print("=" * 70)
+    
+    # Example 1: Local execution (NOT sandboxed - use only with trusted code)
+    print("\n1. Local Execution (Not Sandboxed):")
+    print("-" * 70)
+    print("WARNING: Local execution runs code directly on the host machine.")
+    print("Only use this with trusted code!")
+    print()
+    
+    result = atr.execute_tool("safe_calculator", {
+        "operation": "multiply",
+        "a": 7,
+        "b": 6
+    })
+    print(f"Calculator result (local): {result}")
+    
+    # Example 2: Docker sandboxed execution (SAFE for untrusted code)
+    print("\n2. Docker Sandboxed Execution (Safe):")
+    print("-" * 70)
+    print("Docker execution runs code in isolated containers with:")
+    print("  - No network access")
+    print("  - Memory limits")
+    print("  - Automatic cleanup")
+    print("  - Complete isolation from host")
+    print()
+    
+    try:
+        # Create Docker executor
+        docker_executor = atr.DockerExecutor(
+            image="python:3.9-slim",
+            auto_pull=True
+        )
+        print("✓ Docker executor initialized")
+        
+        # Execute calculator in Docker
+        print("\nExecuting calculator in Docker container...")
+        result = atr.execute_tool(
+            "safe_calculator",
+            {
+                "operation": "add",
+                "a": 42,
+                "b": 8
+            },
+            executor=docker_executor,
+            timeout=30
+        )
+        print(f"  Result: {result}")
+        
+        # Execute text processor in Docker
+        print("\nExecuting text processor in Docker container...")
+        result = atr.execute_tool(
+            "text_processor",
+            {
+                "text": "hello world from docker",
+                "operation": "title"
+            },
+            executor=docker_executor,
+            timeout=30
+        )
+        print(f"  Result: {result}")
+        
+        # Execute list analyzer in Docker
+        print("\nExecuting list analyzer in Docker container...")
+        result = atr.execute_tool(
+            "list_analyzer",
+            {
+                "numbers": [10, 20, 30, 40, 50]
+            },
+            executor=docker_executor,
+            timeout=30
+        )
+        print(f"  Result: {result}")
+        
+        print("\n✓ All sandboxed executions completed successfully!")
+        
+    except ImportError:
+        print("✗ Docker SDK not installed. Install with: pip install docker")
+        print("  Skipping sandboxed execution examples.")
+    except atr.ExecutorError as e:
+        print(f"✗ Docker execution error: {e}")
+        print("  Make sure Docker is installed and running.")
+    
+    # Example 3: Execution with timeout
+    print("\n3. Execution with Timeout:")
+    print("-" * 70)
+    print("Timeouts prevent long-running or malicious code from hanging.")
+    print()
+    
+    try:
+        docker_executor = atr.DockerExecutor(auto_pull=True)
+        
+        # Quick execution with short timeout
+        result = atr.execute_tool(
+            "safe_calculator",
+            {"operation": "divide", "a": 100, "b": 4},
+            executor=docker_executor,
+            timeout=10  # 10 second timeout
+        )
+        print(f"Quick calculation completed: {result}")
+        
+    except atr.ExecutionTimeoutError:
+        print("✗ Execution exceeded timeout limit")
+    except (ImportError, atr.ExecutorError) as e:
+        print(f"Skipping timeout example: {e}")
+    
+    # Example 4: Comparison of execution modes
+    print("\n4. Comparison of Execution Modes:")
+    print("-" * 70)
+    
+    import textwrap
+    comparison = textwrap.dedent("""
+        | Feature              | Local Executor    | Docker Executor       |
+        |---------------------|-------------------|-----------------------|
+        | Speed               | Fast              | Slower (containerized)|
+        | Security            | No isolation      | Full isolation        |
+        | Network Access      | Full access       | Disabled              |
+        | Resource Limits     | None              | Configurable          |
+        | Cleanup             | N/A               | Automatic             |
+        | Use Case            | Trusted code only | Untrusted code        |
+    """)
+    print(comparison)
+    
+    # Example 5: Best practices
+    print("\n5. Best Practices:")
+    print("-" * 70)
+    
+    import textwrap
+    best_practices = textwrap.dedent("""
+        1. Always use DockerExecutor for untrusted or agent-generated code
+        2. Set appropriate timeouts to prevent hanging executions
+        3. Use LocalExecutor only for trusted, pre-vetted code
+        4. Monitor Docker resource usage in production
+        5. Consider using custom Docker images with minimal dependencies
+        6. Test your tools in Docker before deploying to production
+    """)
+    print(best_practices)
+    
+    print("\n" + "=" * 70)
+    print("Demo complete!")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()

modules/atr/experiments/README.md

@@ -0,0 +1,69 @@
+# ATR Experiments
+
+This folder contains reproducibility scripts and experiment results for the Agent Tool Registry.
+
+## Structure
+
+```
+experiments/
+├── README.md                 # This file
+├── reproduce_results.py      # Main reproducibility script
+├── results/                  # Output directory for experiment results
+│   └── .gitkeep
+└── configs/                  # Experiment configurations
+    └── default.json
+```
+
+## Running Experiments
+
+### Quick Start
+
+```bash
+# Run default experiment suite
+python experiments/reproduce_results.py
+
+# Run with custom seed for reproducibility
+python experiments/reproduce_results.py --seed 42
+
+# Run specific experiment
+python experiments/reproduce_results.py --experiment registration_benchmark
+
+# Save results to custom location
+python experiments/reproduce_results.py --output experiments/results/my_run.json
+```
+
+### Available Experiments
+
+1. **registration_benchmark**: Measures tool registration latency
+2. **discovery_benchmark**: Measures tool discovery/search performance
+3. **schema_conversion**: Tests OpenAI/Anthropic schema generation
+4. **full_suite**: Runs all experiments
+
+## Results Format
+
+Results are saved as JSON with the following structure:
+
+```json
+{
+  "metadata": {
+    "timestamp": "2026-01-23T10:00:00Z",
+    "atr_version": "0.1.0",
+    "python_version": "3.11.0",
+    "seed": 42
+  },
+  "experiments": {
+    "registration_benchmark": {
+      "metrics": {...},
+      "duration_seconds": 1.23
+    }
+  }
+}
+```
+
+## Reproducing Paper Results
+
+To reproduce the results from the paper:
+
+```bash
+python experiments/reproduce_results.py --seed 42 --experiment full_suite
+```