haive-hap 1.0.0__py3-none-any.whl

haive/hap/README.md

@@ -0,0 +1,118 @@
+# HAP (Haive Agent Protocol) Module
+
+This module implements the Haive Agent Protocol - a JSON-RPC 2.0 based protocol for agent communication and orchestration.
+
+## Overview
+
+HAP is the protocol layer that enables:
+- Agent discovery and registration
+- Resource management
+- Progress tracking
+- Authentication and authorization
+- Tool and prompt exposure
+
+## Components
+
+### Core Classes
+
+- **HAPContext**: Execution context with logging, progress, and resource access
+- **HAPServer**: JSON-RPC server for agent exposure
+- **HAPClient**: Client for interacting with HAP servers
+- **Resource Providers**: Pluggable resource access
+- **Auth Providers**: Authentication and authorization
+
+### Protocol Structure
+
+HAP follows JSON-RPC 2.0 with extensions for:
+- Progress notifications
+- Streaming responses
+- Resource URIs
+- Authentication tokens
+
+```python
+# Example HAP request
+{
+    "jsonrpc": "2.0",
+    "method": "agent/execute",
+    "params": {
+        "agent": "analyzer",
+        "input": {"text": "..."}
+    },
+    "id": "req-123"
+}
+```
+
+## Key Features
+
+### Context Management
+
+```python
+from haive.hap.hap import HAPContext
+
+context = HAPContext(request_id="req-123")
+await context.info("Starting agent execution")
+await context.report_progress(0, 100, "Initializing")
+```
+
+### Resource Access
+
+```python
+# Read resources through context
+data = await context.read_resource("file://data.json")
+config = await context.read_resource("config://agent/settings")
+```
+
+### Authentication
+
+```python
+from haive.hap.hap import SimpleAuthProvider
+
+auth = SimpleAuthProvider(user="alice", scopes=["execute", "read"])
+context = HAPContext(auth_provider=auth)
+
+if context.has_scope("execute"):
+    # Allowed to execute agents
+    pass
+```
+
+## Integration with AGP
+
+HAP provides the protocol layer for AGP:
+
+```python
+# Future implementation
+server = HAPServer()
+
+# Register HAP runtime
+server.register_runtime(agp_runtime)
+
+# Expose agents
+server.expose_agent("analyzer", analyzer_agent)
+server.expose_agent("writer", writer_agent)
+
+# Start server
+await server.start(port=8080)
+```
+
+## Protocol Methods
+
+### Standard Methods
+
+- `agent/list` - List available agents
+- `agent/execute` - Execute an agent
+- `agent/describe` - Get agent metadata
+- `resource/read` - Read a resource
+- `resource/list` - List available resources
+
+### Notifications
+
+- `progress` - Progress updates
+- `log` - Log messages
+- `state` - State changes
+
+## Future Development
+
+1. **Full Protocol Implementation**: Complete JSON-RPC server/client
+2. **MCP Compatibility**: Bridge between HAP and MCP
+3. **Discovery Service**: Agent discovery and registration
+4. **Distributed Execution**: Multi-server agent orchestration

haive/hap/__init__.py

@@ -0,0 +1,66 @@
+"""
+Haive Agent Protocol (HAP) - MCP-like server for agents and graphs.
+
+This module provides a standardized protocol for exposing Haive agents,
+graphs, and state schemas as servers with tools, resources, and prompts.
+"""
+
+# Core models
+from haive.hap.models.graph import HAPGraph, HAPNode
+from haive.hap.models.context import HAPContext
+
+# Protocol types from types package
+from haive.hap.types import (
+    HAPRequest,
+    HAPResponse, 
+    HAPError,
+    ErrorCode,
+    ToolInfo,
+    ResourceInfo,
+    PromptInfo,
+    PromptArgument,
+    AgentInfo,
+    GraphInfo,
+    NodeInfo,
+    EdgeInfo,
+    ServerRegistration,
+    ServerCapability,
+    AgentExecutionRequest,
+    AgentExecutionResult,
+    GraphExecutionRequest,
+    GraphExecutionResult,
+    BaseInfo,
+    # Aliases
+    AgentId,
+    Entrypoint, 
+    JSONMap
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Core models
+    "HAPGraph",
+    "HAPNode", 
+    "HAPContext",
+    # Protocol types
+    "HAPRequest",
+    "HAPResponse",
+    "HAPError", 
+    "ErrorCode",
+    "ToolInfo",
+    "ResourceInfo",
+    "PromptInfo",
+    "PromptArgument",
+    "AgentInfo",
+    "GraphInfo",
+    "NodeInfo",
+    "EdgeInfo", 
+    "ServerRegistration",
+    "ServerCapability",
+    "AgentExecutionRequest",
+    "AgentExecutionResult",
+    "GraphExecutionRequest", 
+    "GraphExecutionResult",
+    "BaseInfo"
+]

haive/hap/client/__init__.py

@@ -0,0 +1,5 @@
+from .base import HAPClientProtocol
+from .local import LocalClient
+from .http import HTTPClient
+
+__all__ = ["HAPClientProtocol", "LocalClient", "HTTPClient"]

haive/hap/client/base.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+from typing import Protocol, Mapping, Any
+from ..models.context import HAPContext
+from ..models.graph import AgentGraph
+
+class HAPClientProtocol(Protocol):
+    def run_agent(self, entrypoint: str, *, inputs: Mapping[str, Any] | None = None) -> HAPContext: ...
+    def run_graph(self, graph: AgentGraph, *, inputs: Mapping[str, Any] | None = None) -> HAPContext: ...

haive/hap/client/http.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+from typing import Mapping, Any
+import json
+import urllib.request
+from ..models.context import HAPContext
+from ..models.graph import AgentGraph
+
+class HTTPClient:
+    """Very small HTTP client for a future HAP server.
+
+    Expects a server that exposes /run-agent and /run-graph endpoints.
+
+    This is a placeholder you can wire to your FastAPI app later.
+    """
+    def __init__(self, base_url: str, *, timeout: float = 30.0):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _post_json(self, path: str, payload: dict) -> dict:
+        data = json.dumps(payload).encode("utf-8")
+        req = urllib.request.Request(self.base_url + path, data=data, headers={"Content-Type": "application/json"})
+        with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+
+    def run_agent(self, entrypoint: str, *, inputs: Mapping[str, Any] | None = None) -> HAPContext:
+        res = self._post_json("/run-agent", {"entrypoint": entrypoint, "inputs": dict(inputs or {})})
+        return HAPContext.model_validate(res)
+
+    def run_graph(self, graph: AgentGraph, *, inputs: Mapping[str, Any] | None = None) -> HAPContext:
+        res = self._post_json("/run-graph", {"graph": graph.model_dump(), "inputs": dict(inputs or {})})
+        return HAPContext.model_validate(res)

haive/hap/client/local.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+from typing import Mapping, Any
+from ..models.context import HAPContext
+from ..models.graph import AgentGraph
+from ..server.runtime import HAPRuntime
+import importlib
+from haive.agents.base.agent import Agent
+
+class LocalClient:
+    """Runs agents/graphs in-process using the local runtime."""
+
+    def run_agent(self, entrypoint: str, *, inputs: Mapping[str, Any] | None = None) -> HAPContext:
+        ctx = HAPContext(inputs=dict(inputs or {}))
+        # Build a trivial one-node graph for the single agent
+        from ..models.graph import AgentGraph, AgentNode
+        g = AgentGraph(nodes={"__single__": AgentNode(id="__single__", agent=entrypoint)}, entry="__single__")
+        return HAPRuntime(g).run(ctx)
+
+    def run_graph(self, graph: AgentGraph, *, inputs: Mapping[str, Any] | None = None) -> HAPContext:
+        ctx = HAPContext(inputs=dict(inputs or {}))
+        return HAPRuntime(graph).run(ctx)

haive/hap/context.py

@@ -0,0 +1,295 @@
+"""
+Context system for HAP, providing execution context for tools and resources.
+
+Similar to MCP's context, this allows tools to:
+- Log messages at different levels
+- Report progress
+- Access resources
+- Get authentication info
+"""
+
+from typing import Optional, Any, Dict, List, Callable, Protocol
+from datetime import datetime
+import asyncio
+from enum import Enum
+
+
+class LogLevel(str, Enum):
+    """Log levels for context messages."""
+    DEBUG = "debug"
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+
+
+class ProgressState(Enum):
+    """Progress reporting state."""
+    STARTED = "started"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class IResourceProvider(Protocol):
+    """Interface for resource providers."""
+    
+    async def read_resource(self, uri: str) -> Any:
+        """Read a resource by URI."""
+        ...
+
+
+class IAuthProvider(Protocol):
+    """Interface for authentication providers."""
+    
+    def get_current_user(self) -> Optional[str]:
+        """Get the current authenticated user."""
+        ...
+    
+    def get_user_scopes(self) -> List[str]:
+        """Get the current user's scopes."""
+        ...
+
+
+class HAPContext:
+    """
+    Execution context for HAP tools and resources.
+    
+    Provides utilities for logging, progress reporting, resource access,
+    and authentication info during execution.
+    """
+    
+    def __init__(
+        self,
+        request_id: str | int,
+        resource_provider: Optional[IResourceProvider] = None,
+        auth_provider: Optional[IAuthProvider] = None,
+        log_handler: Optional[Callable[[str, LogLevel, dict], None]] = None,
+        progress_handler: Optional[Callable[[int, int, str, ProgressState], None]] = None,
+    ):
+        self.request_id = request_id
+        self._resource_provider = resource_provider
+        self._auth_provider = auth_provider
+        self._log_handler = log_handler
+        self._progress_handler = progress_handler
+        
+        # Track progress for nested operations
+        self._progress_stack: List[tuple[int, str]] = []
+        
+        # Store context data
+        self._data: Dict[str, Any] = {}
+    
+    # Logging Methods
+    
+    async def debug(self, message: str, **kwargs):
+        """Log debug message."""
+        await self._log(LogLevel.DEBUG, message, kwargs)
+    
+    async def info(self, message: str, **kwargs):
+        """Log info message."""
+        await self._log(LogLevel.INFO, message, kwargs)
+    
+    async def warning(self, message: str, **kwargs):
+        """Log warning message."""
+        await self._log(LogLevel.WARNING, message, kwargs)
+    
+    async def error(self, message: str, **kwargs):
+        """Log error message."""
+        await self._log(LogLevel.ERROR, message, kwargs)
+    
+    async def _log(self, level: LogLevel, message: str, data: dict):
+        """Internal logging method."""
+        if self._log_handler:
+            log_entry = {
+                "timestamp": datetime.now().isoformat(),
+                "level": level.value,
+                "message": message,
+                "request_id": self.request_id,
+                **data
+            }
+            # Run in background to not block
+            asyncio.create_task(
+                asyncio.to_thread(self._log_handler, message, level, log_entry)
+            )
+    
+    # Progress Reporting
+    
+    async def report_progress(
+        self,
+        current: int,
+        total: int,
+        message: str = "",
+        state: Optional[ProgressState] = None
+    ):
+        """
+        Report progress for the current operation.
+        
+        Args:
+            current: Current progress value
+            total: Total expected value
+            message: Optional progress message
+            state: Optional progress state
+        """
+        if not state:
+            if current == 0:
+                state = ProgressState.STARTED
+            elif current >= total:
+                state = ProgressState.COMPLETED
+            else:
+                state = ProgressState.IN_PROGRESS
+        
+        if self._progress_handler:
+            asyncio.create_task(
+                asyncio.to_thread(
+                    self._progress_handler,
+                    current,
+                    total,
+                    message,
+                    state
+                )
+            )
+    
+    def start_nested_progress(self, total: int, description: str = ""):
+        """Start a nested progress operation."""
+        self._progress_stack.append((total, description))
+    
+    async def update_nested_progress(self, current: int, message: str = ""):
+        """Update the current nested progress."""
+        if self._progress_stack:
+            total, description = self._progress_stack[-1]
+            full_message = f"{description}: {message}" if description else message
+            await self.report_progress(current, total, full_message)
+    
+    def end_nested_progress(self):
+        """End the current nested progress operation."""
+        if self._progress_stack:
+            total, description = self._progress_stack.pop()
+            asyncio.create_task(
+                self.report_progress(total, total, f"{description} completed")
+            )
+    
+    # Resource Access
+    
+    async def read_resource(self, uri: str) -> Any:
+        """
+        Read a resource by URI.
+        
+        Args:
+            uri: Resource URI (e.g., "agent://my-agent/state")
+            
+        Returns:
+            Resource content
+            
+        Raises:
+            ResourceNotFoundError: If resource doesn't exist
+            PermissionError: If access is denied
+        """
+        if not self._resource_provider:
+            raise RuntimeError("No resource provider configured")
+        
+        await self.debug(f"Reading resource: {uri}")
+        try:
+            result = await self._resource_provider.read_resource(uri)
+            await self.debug(f"Successfully read resource: {uri}")
+            return result
+        except Exception as e:
+            await self.error(f"Failed to read resource {uri}: {str(e)}")
+            raise
+    
+    # Authentication
+    
+    def get_auth_user(self) -> Optional[str]:
+        """Get the current authenticated user."""
+        if not self._auth_provider:
+            return None
+        return self._auth_provider.get_current_user()
+    
+    def get_auth_scopes(self) -> List[str]:
+        """Get the current user's scopes."""
+        if not self._auth_provider:
+            return []
+        return self._auth_provider.get_user_scopes()
+    
+    def has_scope(self, scope: str) -> bool:
+        """Check if the current user has a specific scope."""
+        return scope in self.get_auth_scopes()
+    
+    # Context Data
+    
+    def set_data(self, key: str, value: Any):
+        """Store data in the context."""
+        self._data[key] = value
+    
+    def get_data(self, key: str, default: Any = None) -> Any:
+        """Retrieve data from the context."""
+        return self._data.get(key, default)
+    
+    def update_data(self, data: dict):
+        """Update context data with a dictionary."""
+        self._data.update(data)
+    
+    # Utilities
+    
+    async def with_progress(
+        self,
+        operation: Callable,
+        total: int,
+        description: str = "Processing"
+    ):
+        """
+        Execute an operation with automatic progress tracking.
+        
+        Args:
+            operation: Async callable that accepts (current, context) args
+            total: Total number of items
+            description: Progress description
+        """
+        self.start_nested_progress(total, description)
+        try:
+            for i in range(total):
+                await self.update_nested_progress(i, f"Item {i+1}/{total}")
+                await operation(i, self)
+        finally:
+            self.end_nested_progress()
+    
+    def create_child_context(self, **overrides) -> "HAPContext":
+        """Create a child context with optional overrides."""
+        return HAPContext(
+            request_id=overrides.get("request_id", f"{self.request_id}.child"),
+            resource_provider=overrides.get("resource_provider", self._resource_provider),
+            auth_provider=overrides.get("auth_provider", self._auth_provider),
+            log_handler=overrides.get("log_handler", self._log_handler),
+            progress_handler=overrides.get("progress_handler", self._progress_handler),
+        )
+
+
+class SimpleResourceProvider:
+    """Simple in-memory resource provider for testing."""
+    
+    def __init__(self):
+        self.resources: Dict[str, Any] = {}
+    
+    def add_resource(self, uri: str, content: Any):
+        """Add a resource."""
+        self.resources[uri] = content
+    
+    async def read_resource(self, uri: str) -> Any:
+        """Read a resource."""
+        if uri not in self.resources:
+            raise KeyError(f"Resource not found: {uri}")
+        return self.resources[uri]
+
+
+class SimpleAuthProvider:
+    """Simple auth provider for testing."""
+    
+    def __init__(self, user: Optional[str] = None, scopes: Optional[List[str]] = None):
+        self.user = user
+        self.scopes = scopes or []
+    
+    def get_current_user(self) -> Optional[str]:
+        """Get current user."""
+        return self.user
+    
+    def get_user_scopes(self) -> List[str]:
+        """Get user scopes."""
+        return self.scopes

haive/hap/models/README.md

@@ -0,0 +1,86 @@
+# AGP Models Module
+
+This module contains the core data models for the Haive Agent Protocol (AGP).
+
+## Overview
+
+The models module provides the fundamental building blocks for AGP:
+- **HAPContext**: State management with execution tracking
+- **HAPGraph**: Graph structure for agent workflows
+- **HAPNode**: Individual nodes in the graph
+
+## Components
+
+### HAPContext
+
+The `HAPContext` class extends Haive's `StateSchema` to provide:
+- Execution path tracking
+- Agent metadata storage
+- Graph context management
+- Backward compatibility with AGP v1 properties
+
+```python
+from haive.hap.models.context import HAPContext
+
+context = HAPContext()
+context.execution_path.append("node1")
+context.agent_metadata["node1"] = {"status": "complete"}
+```
+
+### HAPGraph
+
+The `HAPGraph` class manages the workflow structure:
+- Node management (add, remove, connect)
+- Topological ordering for execution
+- Entry point configuration
+
+```python
+from haive.hap.models.graph import HAPGraph
+
+graph = HAPGraph()
+graph.add_agent_node("step1", agent1, next_nodes=["step2"])
+graph.add_agent_node("step2", agent2)
+graph.entry_node = "step1"
+```
+
+### HAPNode
+
+Individual nodes in the graph that can contain:
+- Agent instances
+- Agent entrypoints (module:class format)
+- Connections to other nodes
+
+## Backward Compatibility
+
+The module maintains backward compatibility with AGP v1:
+- `HAPContext` supports `inputs`, `outputs`, `state`, `meta` properties
+- `AgentGraph` and `AgentNode` are aliases for the AGP classes
+
+## Usage Example
+
+```python
+from haive.hap.models import HAPGraph, HAPContext
+from haive.agents.simple.agent import SimpleAgent
+
+# Create context
+context = HAPContext()
+
+# Build graph
+graph = HAPGraph()
+agent = SimpleAgent(name="worker", engine=config)
+graph.add_agent_node("worker_node", agent)
+
+# Track execution
+context.execution_path.append("worker_node")
+context.agent_metadata["worker_node"] = {
+    "start_time": time.time(),
+    "status": "running"
+}
+```
+
+## Design Principles
+
+1. **StateSchema Integration**: HAPContext inherits from StateSchema for proper Haive integration
+2. **Simplicity**: Uses BaseModel instead of complex inheritance chains
+3. **Flexibility**: Supports both agent instances and entrypoint strings
+4. **Compatibility**: Maintains all AGP v1 interfaces

haive/hap/models/__init__.py

@@ -0,0 +1,12 @@
+"""HAP models for agent graphs and contexts."""
+
+from .context import HAPContext
+from .graph import HAPGraph, HAPNode, AgentGraph, AgentNode
+
+__all__ = [
+    "HAPContext",
+    "HAPGraph", 
+    "HAPNode",
+    "AgentGraph",  # Backward compatibility
+    "AgentNode",   # Backward compatibility
+]