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

modules/atr/tests/test_integration_executor.py

@@ -0,0 +1,184 @@
+"""Integration tests for executor with ATR registry."""
+
+import pytest
+import atr
+from atr import DockerExecutor, LocalExecutor, ExecutorError
+
+
+def test_execute_tool_with_local_executor():
+    """Test execute_tool with LocalExecutor."""
+    # Register a test tool
+    @atr.register(name="test_add", tags=["math"])
+    def add(a: int, b: int) -> int:
+        """Add two numbers."""
+        return a + b
+    
+    # Execute with default (local) executor
+    result = atr.execute_tool("test_add", {"a": 10, "b": 5})
+    assert result == 15
+    
+    # Clean up
+    atr._global_registry.unregister_tool("test_add")
+
+
+def test_execute_tool_with_explicit_local_executor():
+    """Test execute_tool with explicit LocalExecutor."""
+    # Register a test tool
+    @atr.register(name="test_multiply", tags=["math"])
+    def multiply(a: int, b: int) -> int:
+        """Multiply two numbers."""
+        return a * b
+    
+    executor = LocalExecutor()
+    result = atr.execute_tool("test_multiply", {"a": 6, "b": 7}, executor=executor)
+    assert result == 42
+    
+    # Clean up
+    atr._global_registry.unregister_tool("test_multiply")
+
+
+def test_execute_tool_with_docker_executor():
+    """Test execute_tool with DockerExecutor."""
+    try:
+        executor = DockerExecutor(auto_pull=False)
+    except (ImportError, ExecutorError) as e:
+        pytest.skip(f"Docker not available: {str(e)}")
+    
+    # Register a test tool
+    @atr.register(name="test_subtract", tags=["math"])
+    def subtract(a: int, b: int) -> int:
+        """Subtract two numbers."""
+        return a - b
+    
+    result = atr.execute_tool("test_subtract", {"a": 20, "b": 8}, executor=executor, timeout=10)
+    assert result == 12
+    
+    # Clean up
+    atr._global_registry.unregister_tool("test_subtract")
+
+
+def test_execute_tool_with_string_operations():
+    """Test execute_tool with string operations."""
+    try:
+        executor = DockerExecutor(auto_pull=False)
+    except (ImportError, ExecutorError) as e:
+        pytest.skip(f"Docker not available: {str(e)}")
+    
+    @atr.register(name="test_upper", tags=["string"])
+    def to_upper(text: str) -> str:
+        """Convert text to uppercase."""
+        return text.upper()
+    
+    result = atr.execute_tool("test_upper", {"text": "hello world"}, executor=executor, timeout=10)
+    assert result == "HELLO WORLD"
+    
+    # Clean up
+    atr._global_registry.unregister_tool("test_upper")
+
+
+def test_execute_tool_with_list_operations():
+    """Test execute_tool with list operations."""
+    try:
+        executor = DockerExecutor(auto_pull=False)
+    except (ImportError, ExecutorError) as e:
+        pytest.skip(f"Docker not available: {str(e)}")
+    
+    @atr.register(name="test_reverse", tags=["list"])
+    def reverse_list(items: list) -> list:
+        """Reverse a list."""
+        return list(reversed(items))
+    
+    result = atr.execute_tool("test_reverse", {"items": [1, 2, 3, 4]}, executor=executor, timeout=10)
+    assert result == [4, 3, 2, 1]
+    
+    # Clean up
+    atr._global_registry.unregister_tool("test_reverse")
+
+
+def test_execute_tool_error_handling():
+    """Test execute_tool error handling."""
+    @atr.register(name="test_error", tags=["test"])
+    def error_func(x: int) -> int:
+        """Function that raises an error."""
+        raise ValueError("Intentional error")
+    
+    with pytest.raises(ExecutorError):
+        atr.execute_tool("test_error", {"x": 1})
+    
+    # Clean up
+    atr._global_registry.unregister_tool("test_error")
+
+
+def test_execute_tool_nonexistent():
+    """Test execute_tool with nonexistent tool."""
+    with pytest.raises(atr.ToolNotFoundError):
+        atr.execute_tool("nonexistent_tool", {})
+
+
+def test_execute_tool_with_defaults():
+    """Test execute_tool with default parameter values."""
+    @atr.register(name="test_greet", tags=["string"])
+    def greet(name: str = "World") -> str:
+        """Greet someone."""
+        return f"Hello, {name}!"
+    
+    # Test with default
+    result1 = atr.execute_tool("test_greet")
+    assert result1 == "Hello, World!"
+    
+    # Test with explicit value
+    result2 = atr.execute_tool("test_greet", {"name": "Alice"})
+    assert result2 == "Hello, Alice!"
+    
+    # Clean up
+    atr._global_registry.unregister_tool("test_greet")
+
+
+def test_execute_tool_sandboxed_vs_local():
+    """Compare sandboxed and local execution results."""
+    try:
+        docker_executor = DockerExecutor(auto_pull=False)
+    except (ImportError, ExecutorError) as e:
+        pytest.skip(f"Docker not available: {str(e)}")
+    
+    @atr.register(name="test_calc", tags=["math"])
+    def calculate(x: int, y: int) -> int:
+        """Calculate x squared plus y."""
+        return x * x + y
+    
+    # Execute locally
+    local_executor = LocalExecutor()
+    result_local = atr.execute_tool("test_calc", {"x": 5, "y": 3}, executor=local_executor)
+    
+    # Execute in Docker
+    result_docker = atr.execute_tool("test_calc", {"x": 5, "y": 3}, executor=docker_executor, timeout=10)
+    
+    # Results should be the same
+    assert result_local == result_docker == 28
+    
+    # Clean up
+    atr._global_registry.unregister_tool("test_calc")
+
+
+def test_execute_tool_complex_function():
+    """Test execute_tool with a more complex function."""
+    try:
+        executor = DockerExecutor(auto_pull=False)
+    except (ImportError, ExecutorError) as e:
+        pytest.skip(f"Docker not available: {str(e)}")
+    
+    @atr.register(name="test_complex", tags=["data"])
+    def process_data(numbers: list, multiplier: int = 2, add_value: int = 0) -> list:
+        """Process a list of numbers."""
+        return [n * multiplier + add_value for n in numbers]
+    
+    result = atr.execute_tool(
+        "test_complex",
+        {"numbers": [1, 2, 3, 4], "multiplier": 3, "add_value": 10},
+        executor=executor,
+        timeout=10
+    )
+    assert result == [13, 16, 19, 22]
+    
+    # Clean up
+    atr._global_registry.unregister_tool("test_complex")

modules/atr/tests/test_registry.py

@@ -0,0 +1,312 @@
+"""Tests for registry functionality."""
+
+import pytest
+from atr.registry import (
+    Registry,
+    ToolNotFoundError,
+    ToolAlreadyExistsError,
+)
+from atr.schema import (
+    ToolSpec,
+    ToolMetadata,
+    ParameterSpec,
+    ParameterType,
+    CostLevel,
+    SideEffect,
+)
+
+
+def create_sample_tool(name: str = "test_tool") -> ToolSpec:
+    """Helper to create a sample tool spec."""
+    metadata = ToolMetadata(
+        name=name,
+        description=f"Test tool: {name}",
+    )
+    return ToolSpec(metadata=metadata, parameters=[])
+
+
+def test_registry_initialization():
+    """Test registry initialization."""
+    registry = Registry()
+    assert len(registry) == 0
+
+
+def test_register_and_get_tool():
+    """Test registering and retrieving a tool."""
+    registry = Registry()
+    tool_spec = create_sample_tool("scraper")
+    
+    registry.register_tool(tool_spec)
+    
+    retrieved = registry.get_tool("scraper")
+    assert retrieved.metadata.name == "scraper"
+
+
+def test_register_duplicate_tool_fails():
+    """Test that registering duplicate tool raises error."""
+    registry = Registry()
+    tool_spec = create_sample_tool("duplicate")
+    
+    registry.register_tool(tool_spec)
+    
+    with pytest.raises(ToolAlreadyExistsError):
+        registry.register_tool(tool_spec)
+
+
+def test_register_duplicate_with_replace():
+    """Test that replace=True allows overwriting."""
+    registry = Registry()
+    tool_spec1 = create_sample_tool("replaceable")
+    tool_spec2 = create_sample_tool("replaceable")
+    tool_spec2.metadata.description = "Updated description"
+    
+    registry.register_tool(tool_spec1)
+    registry.register_tool(tool_spec2, replace=True)
+    
+    retrieved = registry.get_tool("replaceable")
+    assert retrieved.metadata.description == "Updated description"
+
+
+def test_get_nonexistent_tool_fails():
+    """Test that getting nonexistent tool raises error."""
+    registry = Registry()
+    
+    with pytest.raises(ToolNotFoundError):
+        registry.get_tool("nonexistent")
+
+
+def test_register_with_callable():
+    """Test registering a tool with a callable function."""
+    registry = Registry()
+    
+    def sample_func(x: int) -> int:
+        return x * 2
+    
+    tool_spec = create_sample_tool("doubler")
+    registry.register_tool(tool_spec, callable_func=sample_func)
+    
+    # Get the callable - registry returns it but doesn't execute
+    retrieved_callable = registry.get_callable("doubler")
+    assert retrieved_callable is sample_func
+    
+    # The Agent Runtime would execute it
+    result = retrieved_callable(5)
+    assert result == 10
+
+
+def test_get_callable_without_function_fails():
+    """Test that getting callable for tool without function raises error."""
+    registry = Registry()
+    tool_spec = create_sample_tool("no_callable")
+    
+    registry.register_tool(tool_spec)
+    
+    with pytest.raises(ValueError, match="has no callable function"):
+        registry.get_callable("no_callable")
+
+
+def test_list_tools():
+    """Test listing all tools."""
+    registry = Registry()
+    
+    registry.register_tool(create_sample_tool("tool1"))
+    registry.register_tool(create_sample_tool("tool2"))
+    registry.register_tool(create_sample_tool("tool3"))
+    
+    tools = registry.list_tools()
+    assert len(tools) == 3
+    assert any(t.metadata.name == "tool1" for t in tools)
+
+
+def test_list_tools_by_tag():
+    """Test filtering tools by tag."""
+    registry = Registry()
+    
+    tool1 = create_sample_tool("web_tool")
+    tool1.metadata.tags = ["web", "http"]
+    
+    tool2 = create_sample_tool("file_tool")
+    tool2.metadata.tags = ["file", "io"]
+    
+    tool3 = create_sample_tool("web_tool2")
+    tool3.metadata.tags = ["web", "scraping"]
+    
+    registry.register_tool(tool1)
+    registry.register_tool(tool2)
+    registry.register_tool(tool3)
+    
+    web_tools = registry.list_tools(tag="web")
+    assert len(web_tools) == 2
+    assert all("web" in t.metadata.tags for t in web_tools)
+
+
+def test_list_tools_by_cost():
+    """Test filtering tools by cost level."""
+    registry = Registry()
+    
+    tool1 = create_sample_tool("cheap_tool")
+    tool1.metadata.cost = CostLevel.LOW
+    
+    tool2 = create_sample_tool("expensive_tool")
+    tool2.metadata.cost = CostLevel.HIGH
+    
+    tool3 = create_sample_tool("free_tool")
+    tool3.metadata.cost = CostLevel.FREE
+    
+    registry.register_tool(tool1)
+    registry.register_tool(tool2)
+    registry.register_tool(tool3)
+    
+    low_cost_tools = registry.list_tools(cost=CostLevel.LOW)
+    assert len(low_cost_tools) == 1
+    assert low_cost_tools[0].metadata.name == "cheap_tool"
+
+
+def test_list_tools_by_side_effect():
+    """Test filtering tools by side effect."""
+    registry = Registry()
+    
+    tool1 = create_sample_tool("reader")
+    tool1.metadata.side_effects = [SideEffect.READ]
+    
+    tool2 = create_sample_tool("writer")
+    tool2.metadata.side_effects = [SideEffect.WRITE]
+    
+    tool3 = create_sample_tool("networker")
+    tool3.metadata.side_effects = [SideEffect.NETWORK, SideEffect.READ]
+    
+    registry.register_tool(tool1)
+    registry.register_tool(tool2)
+    registry.register_tool(tool3)
+    
+    read_tools = registry.list_tools(side_effect=SideEffect.READ)
+    assert len(read_tools) == 2
+    assert all(SideEffect.READ in t.metadata.side_effects for t in read_tools)
+
+
+def test_search_tools_by_name():
+    """Test searching tools by name."""
+    registry = Registry()
+    
+    registry.register_tool(create_sample_tool("web_scraper"))
+    registry.register_tool(create_sample_tool("file_reader"))
+    registry.register_tool(create_sample_tool("web_crawler"))
+    
+    results = registry.search_tools("web")
+    assert len(results) == 2
+    assert all("web" in t.metadata.name for t in results)
+
+
+def test_search_tools_by_description():
+    """Test searching tools by description."""
+    registry = Registry()
+    
+    tool1 = create_sample_tool("tool1")
+    tool1.metadata.description = "Scrapes web pages"
+    
+    tool2 = create_sample_tool("tool2")
+    tool2.metadata.description = "Reads local files"
+    
+    tool3 = create_sample_tool("tool3")
+    tool3.metadata.description = "Web API client"
+    
+    registry.register_tool(tool1)
+    registry.register_tool(tool2)
+    registry.register_tool(tool3)
+    
+    results = registry.search_tools("web")
+    assert len(results) == 2
+
+
+def test_search_tools_by_tag():
+    """Test searching tools by tag."""
+    registry = Registry()
+    
+    tool1 = create_sample_tool("tool1")
+    tool1.metadata.tags = ["database", "sql"]
+    
+    tool2 = create_sample_tool("tool2")
+    tool2.metadata.tags = ["api", "rest"]
+    
+    registry.register_tool(tool1)
+    registry.register_tool(tool2)
+    
+    results = registry.search_tools("database")
+    assert len(results) == 1
+    assert results[0].metadata.name == "tool1"
+
+
+def test_unregister_tool():
+    """Test unregistering a tool."""
+    registry = Registry()
+    tool_spec = create_sample_tool("to_remove")
+    
+    registry.register_tool(tool_spec)
+    assert len(registry) == 1
+    
+    registry.unregister_tool("to_remove")
+    assert len(registry) == 0
+
+
+def test_unregister_nonexistent_tool_fails():
+    """Test that unregistering nonexistent tool raises error."""
+    registry = Registry()
+    
+    with pytest.raises(ToolNotFoundError):
+        registry.unregister_tool("nonexistent")
+
+
+def test_clear_registry():
+    """Test clearing all tools from registry."""
+    registry = Registry()
+    
+    registry.register_tool(create_sample_tool("tool1"))
+    registry.register_tool(create_sample_tool("tool2"))
+    registry.register_tool(create_sample_tool("tool3"))
+    
+    assert len(registry) == 3
+    
+    registry.clear()
+    assert len(registry) == 0
+
+
+def test_contains_operator():
+    """Test 'in' operator for registry."""
+    registry = Registry()
+    tool_spec = create_sample_tool("exists")
+    
+    registry.register_tool(tool_spec)
+    
+    assert "exists" in registry
+    assert "nonexistent" not in registry
+
+
+def test_registry_does_not_execute_tools():
+    """Test that registry stores but doesn't execute tools."""
+    registry = Registry()
+    
+    # Track if function was called
+    call_count = [0]
+    
+    def counting_func(x: int) -> int:
+        call_count[0] += 1
+        return x * 2
+    
+    tool_spec = create_sample_tool("counter")
+    
+    # Register the tool - should NOT execute it
+    registry.register_tool(tool_spec, callable_func=counting_func)
+    assert call_count[0] == 0, "Registry should not execute the tool on registration"
+    
+    # Get the tool - should NOT execute it
+    retrieved = registry.get_tool("counter")
+    assert call_count[0] == 0, "Registry should not execute the tool on retrieval"
+    
+    # Get the callable - should NOT execute it
+    func = registry.get_callable("counter")
+    assert call_count[0] == 0, "Registry should not execute the tool when getting callable"
+    
+    # Only when the Agent Runtime explicitly calls it
+    result = func(5)
+    assert call_count[0] == 1, "Function should only execute when explicitly called"
+    assert result == 10

modules/atr/tests/test_schema.py

@@ -0,0 +1,182 @@
+"""Tests for schema definitions."""
+
+import pytest
+from atr.schema import (
+    ToolSpec,
+    ToolMetadata,
+    ParameterSpec,
+    ParameterType,
+    SideEffect,
+    CostLevel,
+)
+
+
+def test_parameter_spec_basic():
+    """Test basic parameter specification."""
+    param = ParameterSpec(
+        name="url",
+        type=ParameterType.STRING,
+        description="The URL to process",
+        required=True,
+    )
+    
+    assert param.name == "url"
+    assert param.type == ParameterType.STRING
+    assert param.description == "The URL to process"
+    assert param.required is True
+    assert param.default is None
+
+
+def test_parameter_spec_with_default():
+    """Test parameter with default value."""
+    param = ParameterSpec(
+        name="timeout",
+        type=ParameterType.INTEGER,
+        description="Timeout in seconds",
+        required=False,
+        default=30,
+    )
+    
+    assert param.required is False
+    assert param.default == 30
+
+
+def test_parameter_spec_default_on_required_fails():
+    """Test that default on required parameter raises error."""
+    with pytest.raises(ValueError, match="Cannot set default value for required parameter"):
+        ParameterSpec(
+            name="bad_param",
+            type=ParameterType.STRING,
+            description="Bad parameter",
+            required=True,
+            default="should fail",
+        )
+
+
+def test_tool_metadata():
+    """Test tool metadata."""
+    metadata = ToolMetadata(
+        name="test_tool",
+        description="A test tool",
+        version="1.0.0",
+        cost=CostLevel.LOW,
+        side_effects=[SideEffect.READ, SideEffect.NETWORK],
+        tags=["test", "example"],
+    )
+    
+    assert metadata.name == "test_tool"
+    assert metadata.cost == CostLevel.LOW
+    assert SideEffect.READ in metadata.side_effects
+    assert "test" in metadata.tags
+
+
+def test_tool_spec_basic():
+    """Test basic tool specification."""
+    metadata = ToolMetadata(
+        name="scraper",
+        description="Web scraper tool",
+    )
+    
+    param = ParameterSpec(
+        name="url",
+        type=ParameterType.STRING,
+        description="URL to scrape",
+        required=True,
+    )
+    
+    spec = ToolSpec(
+        metadata=metadata,
+        parameters=[param],
+    )
+    
+    assert spec.metadata.name == "scraper"
+    assert len(spec.parameters) == 1
+    assert spec.parameters[0].name == "url"
+
+
+def test_tool_spec_to_openai_schema():
+    """Test conversion to OpenAI function calling format."""
+    metadata = ToolMetadata(
+        name="calculator",
+        description="Perform calculations",
+    )
+    
+    params = [
+        ParameterSpec(
+            name="operation",
+            type=ParameterType.STRING,
+            description="The operation to perform",
+            required=True,
+            enum=["add", "subtract", "multiply", "divide"],
+        ),
+        ParameterSpec(
+            name="a",
+            type=ParameterType.NUMBER,
+            description="First number",
+            required=True,
+        ),
+        ParameterSpec(
+            name="b",
+            type=ParameterType.NUMBER,
+            description="Second number",
+            required=True,
+        ),
+    ]
+    
+    spec = ToolSpec(metadata=metadata, parameters=params)
+    openai_schema = spec.to_openai_function_schema()
+    
+    assert openai_schema["name"] == "calculator"
+    assert openai_schema["description"] == "Perform calculations"
+    assert "parameters" in openai_schema
+    assert openai_schema["parameters"]["type"] == "object"
+    assert "operation" in openai_schema["parameters"]["properties"]
+    assert "a" in openai_schema["parameters"]["properties"]
+    assert "b" in openai_schema["parameters"]["properties"]
+    assert set(openai_schema["parameters"]["required"]) == {"operation", "a", "b"}
+    assert openai_schema["parameters"]["properties"]["operation"]["enum"] == ["add", "subtract", "multiply", "divide"]
+
+
+def test_tool_spec_optional_parameters():
+    """Test tool spec with optional parameters."""
+    metadata = ToolMetadata(
+        name="fetcher",
+        description="Fetch data",
+    )
+    
+    params = [
+        ParameterSpec(
+            name="url",
+            type=ParameterType.STRING,
+            description="URL to fetch",
+            required=True,
+        ),
+        ParameterSpec(
+            name="timeout",
+            type=ParameterType.INTEGER,
+            description="Timeout in seconds",
+            required=False,
+            default=30,
+        ),
+    ]
+    
+    spec = ToolSpec(metadata=metadata, parameters=params)
+    openai_schema = spec.to_openai_function_schema()
+    
+    # Only required params should be in 'required' list
+    assert openai_schema["parameters"]["required"] == ["url"]
+    assert "timeout" in openai_schema["parameters"]["properties"]
+
+
+def test_tool_spec_serialization():
+    """Test that tool spec can be serialized to JSON."""
+    metadata = ToolMetadata(
+        name="test",
+        description="Test tool",
+    )
+    
+    spec = ToolSpec(metadata=metadata, parameters=[])
+    
+    # Should serialize without error (private attrs are auto-excluded)
+    json_str = spec.model_dump_json()
+    assert json_str is not None