agentex-sdk 0.1.0a6__py3-none-any.whl

agentex/lib/sdk/fastacp/impl/temporal_acp.py

@@ -0,0 +1,97 @@
+from contextlib import asynccontextmanager
+from typing import AsyncGenerator, Callable
+
+from fastapi import FastAPI
+
+from agentex.lib.core.clients.temporal.temporal_client import TemporalClient
+from agentex.lib.core.temporal.services.temporal_task_service import TemporalTaskService
+from agentex.lib.environment_variables import EnvironmentVariables
+from agentex.lib.sdk.fastacp.base.base_acp_server import BaseACPServer
+from agentex.lib.types.acp import (
+    CancelTaskParams,
+    CreateTaskParams,
+    SendEventParams,
+)
+from agentex.lib.utils.logging import make_logger
+
+logger = make_logger(__name__)
+
+
+class TemporalACP(BaseACPServer):
+    """
+    Temporal-specific implementation of AsyncAgentACP.
+    Uses TaskService to forward operations to temporal workflows.
+    """
+
+    def __init__(
+        self, temporal_address: str, temporal_task_service: TemporalTaskService | None = None
+    ):
+        super().__init__()
+        self._temporal_task_service = temporal_task_service
+        self._temporal_address = temporal_address
+
+    @classmethod
+    def create(cls, temporal_address: str) -> "TemporalACP":
+        logger.info("Initializing TemporalACP instance")
+
+        # Create instance without temporal client initially
+        temporal_acp = cls(temporal_address=temporal_address)
+        temporal_acp._setup_handlers()
+        logger.info("TemporalACP instance initialized now")
+        return temporal_acp
+
+    # This is to override the lifespan function of the base
+    def get_lifespan_function(self) -> Callable[[FastAPI], AsyncGenerator[None, None]]:
+        @asynccontextmanager
+        async def lifespan(app: FastAPI):
+            # Create temporal client during startup
+            if self._temporal_address is None:
+                raise ValueError("Temporal address is not set")
+
+            if self._temporal_task_service is None:
+                env_vars = EnvironmentVariables.refresh()
+                temporal_client = await TemporalClient.create(
+                    temporal_address=self._temporal_address
+                )
+                self._temporal_task_service = TemporalTaskService(
+                    temporal_client=temporal_client,
+                    env_vars=env_vars,
+                )
+
+            # Call parent lifespan for agent registration
+            async with super().get_lifespan_function()(app):
+                yield
+
+        return lifespan
+
+    def _setup_handlers(self):
+        """Set up the handlers for temporal workflow operations"""
+
+        @self.on_task_create
+        async def handle_task_create(params: CreateTaskParams) -> None:
+            """Default create task handler - logs the task"""
+            logger.info(f"TemporalACP received task create rpc call for task {params.task.id}")
+            await self._temporal_task_service.submit_task(agent=params.agent, task=params.task)
+
+        @self.on_task_event_send
+        async def handle_event_send(params: SendEventParams) -> None:
+            """Forward messages to running workflows via TaskService"""
+            try:
+                await self._temporal_task_service.send_event(
+                    agent=params.agent,
+                    task=params.task,
+                    event=params.event,
+                )
+
+            except Exception as e:
+                logger.error(f"Failed to send message: {e}")
+                raise
+
+        @self.on_task_cancel
+        async def handle_cancel(params: CancelTaskParams) -> None:
+            """Cancel running workflows via TaskService"""
+            try:
+                await self._temporal_task_service.cancel(task_id=params.task.id)
+            except Exception as e:
+                logger.error(f"Failed to cancel task: {e}")
+                raise

agentex/lib/sdk/fastacp/tests/README.md

@@ -0,0 +1,297 @@
+# BaseACPServer Test Suite
+
+This directory contains comprehensive tests for the `BaseACPServer` and its implementations (`SyncACP`, `AgenticBaseACP`, and `TemporalACP`).
+
+## Test Structure
+
+The test suite is organized into several categories:
+
+### 1. Core Unit Tests (`test_base_acp_server.py`)
+- **TestBaseACPServerInitialization**: Server initialization and setup
+- **TestHealthCheckEndpoint**: Health check endpoint functionality
+- **TestJSONRPCEndpointCore**: Basic JSON-RPC endpoint functionality
+- **TestHandlerRegistration**: Handler registration and management
+- **TestBackgroundProcessing**: Background task processing
+- **TestErrorHandling**: Basic error handling scenarios
+
+### 2. JSON-RPC Endpoint Tests (`test_json_rpc_endpoints.py`)
+- **TestJSONRPCMethodHandling**: Method routing and execution
+- **TestJSONRPCParameterValidation**: Parameter parsing and validation
+- **TestJSONRPCResponseFormat**: Response formatting compliance
+- **TestJSONRPCErrorCodes**: JSON-RPC 2.0 error code compliance
+- **TestJSONRPCConcurrency**: Concurrent request handling
+
+### 3. Integration Tests (`test_server_integration.py`)
+- **TestServerLifecycle**: Server startup, running, and shutdown
+- **TestHTTPClientIntegration**: Real HTTP client interactions
+- **TestHandlerExecutionIntegration**: Handler execution in server environment
+- **TestServerPerformance**: Performance characteristics
+
+### 4. Implementation Tests (`test_implementations.py`)
+- **TestSyncACP**: SyncACP-specific functionality
+- **TestAgenticBaseACP**: AgenticBaseACP-specific functionality
+- **TestTemporalACP**: TemporalACP-specific functionality
+- **TestImplementationComparison**: Differences between implementations
+- **TestImplementationErrorHandling**: Implementation-specific error handling
+
+### 5. Error Handling Tests (`test_error_handling.py`)
+- **TestMalformedRequestHandling**: Invalid and malformed requests
+- **TestHandlerErrorHandling**: Handler-level error scenarios
+- **TestServerErrorHandling**: Server-level error handling
+- **TestEdgeCases**: Edge cases and boundary conditions
+
+## Running Tests
+
+### Prerequisites
+
+Install test dependencies:
+```bash
+pip install pytest pytest-asyncio httpx pytest-cov pytest-xdist
+```
+
+### Basic Usage
+
+Run all tests:
+```bash
+python run_tests.py
+```
+
+Run specific test categories:
+```bash
+python run_tests.py --category unit
+python run_tests.py --category integration
+python run_tests.py --category implementations
+python run_tests.py --category error
+```
+
+### Advanced Options
+
+Run with coverage:
+```bash
+python run_tests.py --coverage
+```
+
+Run in parallel:
+```bash
+python run_tests.py --parallel 4
+```
+
+Run with increased verbosity:
+```bash
+python run_tests.py -vv
+```
+
+Stop on first failure:
+```bash
+python run_tests.py --failfast
+```
+
+Run only failed tests from last run:
+```bash
+python run_tests.py --lf
+```
+
+### Quick Test Options
+
+For development, use these quick test commands:
+
+```bash
+# Quick smoke tests
+python run_tests.py smoke
+
+# Quick development tests
+python run_tests.py quick
+
+# Performance tests only
+python run_tests.py perf
+```
+
+### Direct pytest Usage
+
+You can also run tests directly with pytest:
+
+```bash
+# Run all tests
+pytest
+
+# Run specific test file
+pytest test_base_acp_server.py
+
+# Run specific test class
+pytest test_base_acp_server.py::TestBaseACPServerInitialization
+
+# Run specific test method
+pytest test_base_acp_server.py::TestBaseACPServerInitialization::test_base_acp_server_init
+
+# Run with markers
+pytest -m "not slow"
+```
+
+## Test Configuration
+
+### Fixtures (`conftest.py`)
+
+The test suite uses several fixtures:
+
+- **`free_port`**: Provides a free port for testing
+- **`sample_task`**, **`sample_message`**: Sample data objects
+- **`base_acp_server`**, **`sync_acp`**, **`agentic_base_acp`**, **`mock_temporal_acp`**: Server instances
+- **`test_server_runner`**: Manages server lifecycle for integration tests
+- **`jsonrpc_client_factory`**: Creates JSON-RPC test clients
+- **`mock_env_vars`**: Mocked environment variables
+
+### Test Utilities
+
+- **`TestServerRunner`**: Manages server startup/shutdown for integration tests
+- **`JSONRPCTestClient`**: Simplified JSON-RPC client for testing
+- **`find_free_port()`**: Utility to find available ports
+
+## Test Categories Explained
+
+### Unit Tests
+Focus on individual components in isolation:
+- Server initialization
+- Handler registration
+- Basic endpoint functionality
+- Parameter validation
+
+### Integration Tests
+Test components working together:
+- Full server lifecycle
+- Real HTTP requests
+- Handler execution in server context
+- Performance characteristics
+
+### Implementation Tests
+Test specific ACP implementations:
+- SyncACP behavior
+- AgenticBaseACP send_event functionality
+- TemporalACP workflow integration
+- Implementation differences
+
+### Error Handling Tests
+Comprehensive error scenarios:
+- Malformed JSON-RPC requests
+- Handler exceptions
+- Server error recovery
+- Edge cases and boundary conditions
+
+## Writing New Tests
+
+### Test Naming Convention
+- Test files: `test_*.py`
+- Test classes: `Test*`
+- Test methods: `test_*`
+
+### Async Test Example
+```python
+@pytest.mark.asyncio
+async def test_my_async_functionality(self, base_acp_server):
+    # Your async test code here
+    result = await some_async_operation()
+    assert result is not None
+```
+
+### Integration Test Example
+```python
+@pytest.mark.asyncio
+async def test_server_integration(self, base_acp_server, free_port, test_server_runner):
+    runner = test_server_runner(base_acp_server, free_port)
+    await runner.start()
+    
+    try:
+        # Test server functionality
+        async with httpx.AsyncClient() as client:
+            response = await client.get(f"http://127.0.0.1:{free_port}/healthz")
+            assert response.status_code == 200
+    finally:
+        await runner.stop()
+```
+
+### Handler Test Example
+```python
+@pytest.mark.asyncio
+async def test_custom_handler(self, base_acp_server):
+    handler_called = False
+    
+    @base_acp_server.on_task_event_send
+    async def test_handler(params: SendEventParams):
+        nonlocal handler_called
+        handler_called = True
+        return {"handled": True}
+    
+    # Test handler execution
+    params = SendEventParams(...)
+    result = await base_acp_server._handlers[RPCMethod.EVENT_SEND](params)
+    
+    assert handler_called is True
+    assert result["handled"] is True
+```
+
+## Continuous Integration
+
+The test suite is designed to work well in CI environments:
+
+- Tests are isolated and don't interfere with each other
+- Ports are dynamically allocated to avoid conflicts
+- Background tasks are properly cleaned up
+- Timeouts are reasonable for CI environments
+
+### CI Configuration Example
+
+```yaml
+# .github/workflows/test.yml
+name: Tests
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: '3.9'
+      - run: pip install -r requirements.txt
+      - run: pip install pytest pytest-asyncio httpx pytest-cov
+      - run: cd agentex/sdk/fastacp/tests && python run_tests.py --coverage
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Port conflicts**: Tests use dynamic port allocation, but if you see port conflicts, try running tests sequentially:
+   ```bash
+   python run_tests.py --parallel 1
+   ```
+
+2. **Async test failures**: Make sure all async tests are marked with `@pytest.mark.asyncio`
+
+3. **Handler not found errors**: Ensure handlers are properly registered before testing
+
+4. **Timeout issues**: Some tests have built-in delays for background processing. If tests are flaky, increase sleep times in test code.
+
+### Debug Mode
+
+Run tests with maximum verbosity and no capture:
+```bash
+pytest -vvv -s --tb=long
+```
+
+### Memory Issues
+
+If you encounter memory issues with large tests:
+```bash
+python run_tests.py --markers "not memory_intensive"
+```
+
+## Contributing
+
+When adding new tests:
+
+1. Follow the existing test structure and naming conventions
+2. Add appropriate docstrings explaining what the test does
+3. Use fixtures for common setup
+4. Clean up resources properly (especially in integration tests)
+5. Add tests to the appropriate category in `run_tests.py`
+6. Update this README if adding new test categories or significant functionality 

agentex/lib/sdk/fastacp/tests/conftest.py

@@ -0,0 +1,307 @@
+import asyncio
+import socket
+import time
+from typing import Any
+from unittest.mock import AsyncMock, patch
+
+import httpx
+import pytest
+import pytest_asyncio
+import uvicorn
+
+from agentex.lib.sdk.fastacp.base.base_acp_server import BaseACPServer
+from agentex.lib.sdk.fastacp.impl.agentic_base_acp import AgenticBaseACP
+from agentex.lib.sdk.fastacp.impl.sync_acp import SyncACP
+from agentex.lib.sdk.fastacp.impl.temporal_acp import TemporalACP
+from agentex.lib.types.acp import (
+    CancelTaskParams,
+    CreateTaskParams,
+    SendMessageParams,
+)
+from agentex.lib.types.json_rpc import JSONRPCRequest
+from agentex.types.agent import Agent
+from agentex.types.task_message import TaskMessageContent
+from agentex.types.task_message_content import TextContent
+from agentex.types.task import Task
+
+# Configure pytest-asyncio
+pytest_plugins = ("pytest_asyncio",)
+
+
+def find_free_port() -> int:
+    """Find a free port for testing"""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("", 0))
+        s.listen(1)
+        port = s.getsockname()[1]
+    return port
+
+
+@pytest.fixture
+def free_port() -> int:
+    """Fixture that provides a free port for testing"""
+    return find_free_port()
+
+
+@pytest.fixture
+def sample_task() -> Task:
+    """Fixture that provides a sample Task object"""
+    return Task(
+        id="test-task-123", agent_id="test-agent-456", status=TaskStatus.RUNNING
+    )
+
+
+@pytest.fixture
+def sample_message_content() -> TaskMessageContent:
+    """Fixture that provides a sample TaskMessage object"""
+    return TextContent(
+        type="text",
+        author="user",
+        content="Hello, this is a test message",
+    )
+
+
+@pytest.fixture
+def sample_send_message_params(
+    sample_task: Task, sample_message_content: TaskMessageContent
+) -> SendMessageParams:
+    """Fixture that provides sample SendMessageParams"""
+    return SendMessageParams(
+        agent=Agent(
+            id="test-agent-456",
+            name="test-agent",
+            description="test-agent",
+            acp_type="sync",
+        ),
+        task=sample_task,
+        content=sample_message_content,
+        stream=False,
+    )
+
+
+@pytest.fixture
+def sample_cancel_task_params() -> CancelTaskParams:
+    """Fixture that provides sample CancelTaskParams"""
+    return CancelTaskParams(
+        agent=Agent(id="test-agent-456", name="test-agent", description="test-agent", acp_type="sync"),
+        task=Task(id="test-task-123", agent_id="test-agent-456", status="running"),
+    )
+
+
+@pytest.fixture
+def sample_create_task_params(sample_task: Task) -> CreateTaskParams:
+    """Fixture that provides sample CreateTaskParams"""
+    return CreateTaskParams(
+        agent=Agent(id="test-agent-456", name="test-agent", description="test-agent", acp_type="sync"),
+        task=sample_task,
+        params={},
+    )
+
+
+class TestServerRunner:
+    """Utility class for running test servers"""
+
+    def __init__(self, app: BaseACPServer, port: int):
+        self.app = app
+        self.port = port
+        self.server = None
+        self.server_task = None
+
+    async def start(self):
+        """Start the server in a background task"""
+        config = uvicorn.Config(
+            app=self.app,
+            host="127.0.0.1",
+            port=self.port,
+            log_level="error",  # Reduce noise in tests
+        )
+        self.server = uvicorn.Server(config)
+        self.server_task = asyncio.create_task(self.server.serve())
+
+        # Wait for server to be ready
+        await self._wait_for_server()
+
+    async def stop(self):
+        """Stop the server"""
+        if self.server:
+            self.server.should_exit = True
+        if self.server_task:
+            try:
+                await asyncio.wait_for(self.server_task, timeout=5.0)
+            except TimeoutError:
+                self.server_task.cancel()
+                try:
+                    await self.server_task
+                except asyncio.CancelledError:
+                    pass
+
+    async def _wait_for_server(self, timeout: float = 10.0):
+        """Wait for server to be ready to accept connections"""
+        start_time = time.time()
+        while time.time() - start_time < timeout:
+            try:
+                async with httpx.AsyncClient() as client:
+                    response = await client.get(f"http://127.0.0.1:{self.port}/healthz")
+                    if response.status_code == 200:
+                        return
+            except (httpx.ConnectError, httpx.ConnectTimeout):
+                await asyncio.sleep(0.1)
+        raise TimeoutError(f"Server did not start within {timeout} seconds")
+
+
+@pytest_asyncio.fixture
+async def test_server_runner():
+    """Fixture that provides a TestServerRunner factory"""
+    runners = []
+
+    def create_runner(app: BaseACPServer, port: int) -> TestServerRunner:
+        runner = TestServerRunner(app, port)
+        runners.append(runner)
+        return runner
+
+    yield create_runner
+
+    # Cleanup all runners
+    for runner in runners:
+        await runner.stop()
+
+
+@pytest.fixture
+def base_acp_server():
+    """Fixture that provides a BaseACPServer instance for sync tests"""
+    with patch.dict(
+        "os.environ", {"AGENTEX_BASE_URL": ""}
+    ):  # Disable agent registration
+        server = BaseACPServer()
+        return server
+
+
+@pytest_asyncio.fixture
+async def async_base_acp_server():
+    """Fixture that provides a BaseACPServer instance for async tests"""
+    with patch.dict(
+        "os.environ", {"AGENTEX_BASE_URL": ""}
+    ):  # Disable agent registration
+        server = BaseACPServer.create()
+        return server
+
+
+@pytest.fixture
+def sync_acp_server():
+    """Fixture that provides a SyncACP instance for sync tests"""
+    with patch.dict(
+        "os.environ", {"AGENTEX_BASE_URL": ""}
+    ):  # Disable agent registration
+        server = SyncACP()
+        return server
+
+
+@pytest_asyncio.fixture
+async def async_sync_acp_server():
+    """Fixture that provides a SyncACP instance for async tests"""
+    with patch.dict(
+        "os.environ", {"AGENTEX_BASE_URL": ""}
+    ):  # Disable agent registration
+        server = await SyncACP.create()
+        return server
+
+
+@pytest.fixture
+def agentic_base_acp_server():
+    """Fixture that provides an AgenticBaseACP instance for sync tests"""
+    with patch.dict(
+        "os.environ", {"AGENTEX_BASE_URL": ""}
+    ):  # Disable agent registration
+        server = AgenticBaseACP()
+        return server
+
+
+@pytest_asyncio.fixture
+async def async_agentic_base_acp_server():
+    """Fixture that provides an AgenticBaseACP instance for async tests"""
+    with patch.dict(
+        "os.environ", {"AGENTEX_BASE_URL": ""}
+    ):  # Disable agent registration
+        server = await AgenticBaseACP.create()
+        return server
+
+
+@pytest_asyncio.fixture
+async def mock_temporal_acp_server():
+    """Fixture that provides a mocked TemporalACP instance"""
+    with patch.dict(
+        "os.environ", {"AGENTEX_BASE_URL": ""}
+    ):  # Disable agent registration
+        with patch(
+            "agentex.sdk.fastacp.impl.temporal_acp.TemporalClient"
+        ) as mock_temporal_client:
+            with patch(
+                "agentex.sdk.fastacp.impl.temporal_acp.AsyncAgentexClient"
+            ) as mock_agentex_client:
+                # Mock the temporal client creation
+                mock_temporal_client.create.return_value = AsyncMock()
+                mock_agentex_client.return_value = AsyncMock()
+
+                server = await TemporalACP.create(temporal_address="localhost:7233")
+                return server
+
+
+class JSONRPCTestClient:
+    """Test client for making JSON-RPC requests"""
+
+    def __init__(self, base_url: str):
+        self.base_url = base_url
+
+    async def call_method(
+        self, method: str, params: dict[str, Any], request_id: str | None = "test-1"
+    ) -> dict[str, Any]:
+        """Make a JSON-RPC method call"""
+        request = JSONRPCRequest(method=method, params=params, id=request_id)
+
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                f"{self.base_url}/api",
+                json=request.model_dump(),
+                headers={"Content-Type": "application/json"},
+            )
+            return response.json()
+
+    async def send_notification(
+        self, method: str, params: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Send a JSON-RPC notification (no ID)"""
+        return await self.call_method(method, params, request_id=None)
+
+    async def health_check(self) -> dict[str, Any]:
+        """Check server health"""
+        async with httpx.AsyncClient() as client:
+            response = await client.get(f"{self.base_url}/healthz")
+            return response.json()
+
+
+@pytest.fixture
+def jsonrpc_client_factory():
+    """Fixture that provides a JSONRPCTestClient factory"""
+
+    def create_client(base_url: str) -> JSONRPCTestClient:
+        return JSONRPCTestClient(base_url)
+
+    return create_client
+
+
+# Mock environment variables for testing
+@pytest.fixture
+def mock_env_vars():
+    """Fixture that mocks environment variables"""
+    env_vars = {
+        "AGENTEX_BASE_URL": "",  # Disable agent registration by default
+        "AGENT_NAME": "test-agent",
+        "AGENT_DESCRIPTION": "Test agent description",
+        "ACP_URL": "http://localhost",
+        "ACP_PORT": "8000",
+        "WORKFLOW_NAME": "test-workflow",
+        "WORKFLOW_TASK_QUEUE": "test-queue",
+    }
+
+    with patch.dict("os.environ", env_vars):
+        yield env_vars

agentex/lib/sdk/fastacp/tests/pytest.ini

@@ -0,0 +1,10 @@
+[tool:pytest]
+asyncio_mode = auto
+addopts = -v --tb=short
+testpaths = .
+python_files = test_*.py
+python_classes = Test*
+python_functions = test_*
+filterwarnings =
+    ignore::DeprecationWarning
+    ignore::PytestDeprecationWarning