supervaizer 0.9.6__py3-none-any.whl

supervaizer/protocol/a2a/model.py

@@ -0,0 +1,227 @@
+# Copyright (c) 2024-2025 Alain Prasquier - Supervaize.com. All rights reserved.
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, you can obtain one at
+# https://mozilla.org/MPL/2.0/.
+
+from datetime import datetime
+from typing import Any, Dict, List
+
+from supervaizer.agent import Agent
+from supervaizer.job import EntityStatus, Jobs
+
+
+def create_agent_card(agent: Agent, base_url: str) -> Dict[str, Any]:
+    """
+    Create an A2A agent card for the given agent.
+
+    This follows the A2A protocol as defined in:
+    https://github.com/google/A2A/blob/main/specification/json/a2a.json
+
+    Args:
+        agent: The Agent instance
+        base_url: The base URL of the server
+
+    Returns:
+        A dictionary representing the agent card in A2A format
+    """
+    # Construct the agent URL
+    agent_url = f"{base_url}{agent.path}"
+
+    # Build API endpoints object with OpenAPI integration
+    api_endpoints = [
+        {
+            "type": "json",
+            "url": agent_url,
+            "name": "Supervaize API - A2A protocol support",
+            "description": f"RESTful API for {agent.name} agent",
+            "openapi_url": f"{base_url}/openapi.json",
+            "docs_url": f"{base_url}/docs",
+            "examples": [
+                {
+                    "name": "Get agent info",
+                    "description": "Retrieve information about the agent",
+                    "request": {"method": "GET", "url": agent_url},
+                },
+                {
+                    "name": "Start a job",
+                    "description": "Start a new job with this agent",
+                    "request": {"method": "POST", "url": f"{agent_url}/jobs"},
+                },
+            ],
+        }
+    ]
+
+    # Build the tools object based on agent methods
+    tools = []
+
+    # Add basic job tools
+    tools.append(
+        {
+            "name": "job_start",
+            "description": (
+                agent.methods.job_start.description if agent.methods else None
+            )
+            or f"Start a job with {agent.name}",
+            "input_schema": {
+                "type": "object",
+                "properties": {
+                    "job_fields": {"type": "object"},
+                    "job_context": {"type": "object"},
+                },
+            },
+        }
+    )
+
+    tools.append(
+        {
+            "name": "job_status",
+            "description": "Check the status of a job",
+            "input_schema": {
+                "type": "object",
+                "properties": {"job_id": {"type": "string"}},
+            },
+        }
+    )
+
+    # Add custom tools if available
+    if agent.methods and agent.methods.custom:
+        for name, method in agent.methods.custom.items():
+            tools.append(
+                {
+                    "name": name,
+                    "description": method.description
+                    or f"Execute {name} custom method",
+                    "input_schema": {
+                        "type": "object",
+                        "properties": {
+                            "method_name": {"type": "string", "const": name},
+                            "params": {"type": "object"},
+                        },
+                    },
+                }
+            )
+
+    # Build authentication object
+    authentication = {
+        "type": "none",
+        "description": "Authentication is handled at the Supervaize server level",
+    }
+
+    # Version information
+    version_info = {
+        "current": agent.version,
+        "latest": agent.version,
+        "changelog_url": f"{base_url}/changelog/{agent.slug}",
+    }
+
+    # Create the main agent card
+    agent_card = {
+        "name": agent.name,
+        "description": agent.description,
+        "developer": {
+            "name": agent.developer or agent.author or "Supervaize",
+            "url": "https://supervaize.com/",
+            "email": "info@supervaize.com",
+        },
+        "version": agent.version,
+        "version_info": version_info,
+        "logo_url": f"{base_url}/static/agents/{agent.slug}_logo.png",
+        "human_url": f"{base_url}/agents/{agent.slug}",
+        "contact_information": {"general": {"email": "support@supervaize.com"}},
+        "api_endpoints": api_endpoints,
+        "tools": tools,
+        "authentication": authentication,
+    }
+
+    return agent_card
+
+
+def create_agents_list(agents: List[Agent], base_url: str) -> Dict[str, Any]:
+    """
+    Create an A2A agents list for all available agents.
+
+    Args:
+        agents: List of Agent instances
+        base_url: The base URL of the server
+
+    Returns:
+        A dictionary representing the list of agent cards in A2A format
+    """
+    return {
+        "schema_version": "a2a_2023_v1",
+        "agents": [
+            {
+                "name": agent.name,
+                "description": agent.description,
+                "developer": agent.developer or agent.author or "Supervaize",
+                "version": agent.version,
+                "agent_card_url": f"{base_url}/.well-known/agents/v{agent.version}/{agent.slug}_agent.json",
+            }
+            for agent in agents
+        ],
+    }
+
+
+def create_health_data(agents: List[Agent]) -> Dict[str, Any]:
+    """
+    Create health data for all agents according to A2A protocol.
+
+    Args:
+        agents: List of Agent instances
+
+    Returns:
+        A dictionary with health information for all agents
+    """
+    jobs_registry = Jobs()
+
+    agents_health = {}
+    for agent in agents:
+        # Get agent jobs
+        agent_jobs = jobs_registry.get_agent_jobs(agent.name)
+
+        # Calculate job statistics
+        total_jobs = len(agent_jobs)
+        completed_jobs = sum(
+            1 for j in agent_jobs.values() if j.status == EntityStatus.COMPLETED
+        )
+        failed_jobs = sum(
+            1 for j in agent_jobs.values() if j.status == EntityStatus.FAILED
+        )
+        in_progress_jobs = sum(
+            1 for j in agent_jobs.values() if j.status == EntityStatus.IN_PROGRESS
+        )
+
+        # Set agent status based on health indicators
+        if total_jobs == 0:
+            status = "available"
+        elif failed_jobs > total_jobs / 2:  # If more than half are failing
+            status = "degraded"
+        elif in_progress_jobs > 0:
+            status = "busy"
+        else:
+            status = "available"
+
+        agents_health[agent.id] = {
+            "agent_id": agent.id,
+            "agent_server_id": agent.server_agent_id,
+            "name": agent.name,
+            "status": status,
+            "version": agent.version,
+            "statistics": {
+                "total_jobs": total_jobs,
+                "completed_jobs": completed_jobs,
+                "failed_jobs": failed_jobs,
+                "in_progress_jobs": in_progress_jobs,
+                "success_rate": (completed_jobs / total_jobs * 100)
+                if total_jobs > 0
+                else 100,
+            },
+        }
+
+    return {
+        "schema_version": "a2a_2023_v1",
+        "status": "operational",
+        "timestamp": str(datetime.now()),
+        "agents": agents_health,
+    }

supervaizer/protocol/a2a/routes.py

@@ -0,0 +1,99 @@
+# Copyright (c) 2024-2025 Alain Prasquier - Supervaize.com. All rights reserved.
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, you can obtain one at
+# https://mozilla.org/MPL/2.0/.
+
+from typing import TYPE_CHECKING, Any, Dict
+
+from fastapi import APIRouter
+
+from supervaizer.common import log
+from supervaizer.protocol.a2a.model import (
+    create_agent_card,
+    create_agents_list,
+    create_health_data,
+)
+from supervaizer.routes import handle_route_errors
+
+if TYPE_CHECKING:
+    from supervaizer.agent import Agent
+    from supervaizer.server import Server
+
+
+def create_routes(server: "Server") -> APIRouter:
+    """Create A2A protocol routes for the server."""
+    router = APIRouter(prefix="/.well-known", tags=["Protocol A2A"])
+    base_url = server.public_url or ""
+
+    @router.get(
+        "/agents.json",
+        summary="A2A Agents Discovery",
+        description="Returns a list of all agents according to A2A protocol specification",
+        response_model=Dict[str, Any],
+    )
+    @handle_route_errors()
+    async def get_a2a_agents() -> Dict[str, Any]:
+        """Get a list of all available agents in A2A format."""
+        log.info("[A2A] GET /.well-known/agents.json [Agent discovery]")
+        return create_agents_list(server.agents, base_url)
+
+    # Health endpoint
+    @router.get(
+        "/health",
+        summary="A2A Health Status",
+        description="Returns health information about the server and agents",
+        response_model=Dict[str, Any],
+    )
+    @handle_route_errors()
+    async def get_health() -> Dict[str, Any]:
+        """Get health information for the server and all agents."""
+        log.debug("[A2A] GET /.well-known/health [Health status]")
+        return create_health_data(server.agents)
+
+    # Create explicit routes for each agent in the versioned format
+    for agent in server.agents:
+        # V1 endpoints (current version)
+        def create_agent_route_versioned(current_agent: "Agent") -> None:
+            route_path = (
+                f"/agents/v{current_agent.version}/{current_agent.slug}_agent.json"
+            )
+
+            @router.get(
+                route_path,
+                summary=f"A2A Agent Card for {current_agent.name} (v1)",
+                description=f"Returns agent card for {current_agent.name} according to A2A protocol specification",
+                response_model=Dict[str, Any],
+            )
+            @handle_route_errors()
+            async def get_agent_card() -> Dict[str, Any]:
+                """Get an agent card in A2A format."""
+                log.info(
+                    f"[A2A] GET /.well-known/agents/v{current_agent.version}/"
+                    f"{current_agent.slug}_agent.json [Agent card]"
+                )
+                return create_agent_card(current_agent, base_url)
+
+        # Create routes for backward compatibility to current versions
+        def create_agent_route_legacy(current_agent: "Agent") -> None:
+            route_path = f"/agents/{current_agent.slug}_agent.json"
+
+            @router.get(
+                route_path,
+                summary=f"A2A Agent Card for {current_agent.name} (Legacy)",
+                description=f"Legacy endpoint for {current_agent.name} agent card",
+                response_model=Dict[str, Any],
+            )
+            @handle_route_errors()
+            async def get_agent_card_legacy() -> Dict[str, Any]:
+                """Get an agent card in A2A format (legacy endpoint)."""
+                log.info(
+                    f"[A2A] GET /.well-known/agents/{current_agent.slug}_agent.json [Legacy Agent card]"
+                )
+                return create_agent_card(current_agent, base_url)
+
+        # Call the closure function with the current agent
+        create_agent_route_versioned(agent)
+        create_agent_route_legacy(agent)
+
+    return router

supervaizer/protocol/acp/__init__.py

@@ -0,0 +1,21 @@
+# Copyright (c) 2024-2025 Alain Prasquier - Supervaize.com. All rights reserved.
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, you can obtain one at
+# https://mozilla.org/MPL/2.0/.
+
+"""ACP protocol implementation for SUPERVAIZER."""
+
+from supervaizer.protocol.acp.model import (
+    create_agent_detail,
+    create_health_data,
+    list_agents,
+)
+from supervaizer.protocol.acp.routes import create_routes
+
+__all__ = [
+    "create_agent_detail",
+    "list_agents",
+    "create_health_data",
+    "create_routes",
+]

supervaizer/protocol/acp/model.py

@@ -0,0 +1,198 @@
+# Copyright (c) 2024-2025 Alain Prasquier - Supervaize.com. All rights reserved.
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, you can obtain one at
+# https://mozilla.org/MPL/2.0/.
+
+from datetime import datetime
+from typing import Any, Dict, List
+
+from supervaizer.agent import Agent
+from supervaizer.job import EntityStatus, Jobs
+
+
+def create_agent_detail(agent: Agent, base_url: str) -> Dict[str, Any]:
+    """
+    Create an ACP agent detail for the given agent.
+
+    This follows the ACP protocol as defined in:
+    https://docs.beeai.dev/acp/spec/concepts/discovery
+
+    Args:
+        agent: The Agent instance
+        base_url: The base URL of the server
+
+    Returns:
+        A dictionary representing the agent detail in ACP format
+    """
+    # Build the interfaces object
+    interfaces = {
+        "input": "chat",
+        "output": "chat",
+        "awaits": [{"name": "user_response", "request": {}, "response": {}}],
+    }
+
+    # Build the metadata object
+    metadata = {
+        "documentation": agent.description or f"Documentation for {agent.name} agent",
+        "license": "MPL-2.0",
+        "programmingLanguage": "Python",
+        "naturalLanguages": ["en"],
+        "framework": "SUPERVAIZER",
+        "useCases": [f"Agent services provided by {agent.name}"],
+        "examples": [
+            {
+                "prompt": f"Example interaction with {agent.name}",
+                "response": "Example response",
+            }
+        ],
+        "tags": [agent.slug] + (agent.tags or []),
+        "createdAt": datetime.now().strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "updatedAt": datetime.now().strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "author": {
+            "name": agent.author or agent.developer or "SUPERVAIZER",
+            "email": "info@supervaize.com",
+            "url": "https://supervaize.com/",
+        },
+        "contributors": [
+            {
+                "name": agent.maintainer
+                or agent.author
+                or agent.developer
+                or "SUPERVAIZER",
+                "email": "info@supervaize.com",
+                "url": "https://supervaize.com/",
+            }
+        ],
+        "links": [
+            {"type": "homepage", "url": f"{base_url}/agents/{agent.slug}"},
+            {"type": "documentation", "url": f"{base_url}/docs"},
+            {"type": "source-code", "url": "https://github.com/supervaize/supervaizer"},
+        ],
+        "dependencies": [{"type": "tool", "name": "supervaizer-core"}],
+        "recommendedModels": ["gpt-4", "claude-3-opus"],
+    }
+
+    # Get job statistics for status data
+    jobs_registry = Jobs()
+    agent_jobs = jobs_registry.get_agent_jobs(agent.name)
+
+    total_jobs = len(agent_jobs)
+    completed_jobs = sum(
+        1 for j in agent_jobs.values() if j.status == EntityStatus.COMPLETED
+    )
+
+    # Calculate average runtime and success rate for status
+    avg_run_time = 0.0
+    if total_jobs > 0:
+        success_rate = (completed_jobs / total_jobs) * 100
+
+        # Calculate average runtime in seconds
+        runtimes = []
+        for job in agent_jobs.values():
+            if (
+                job.created_at
+                and job.finished_at
+                and job.status == EntityStatus.COMPLETED
+            ):
+                runtime = (job.finished_at - job.created_at).total_seconds()
+                runtimes.append(runtime)
+
+        if runtimes:
+            avg_run_time = sum(runtimes) / len(runtimes)
+    else:
+        success_rate = 100  # If no jobs, assume 100% success rate
+
+    # Build the status object
+    status = {
+        "avgRunTokens": 0,  # Placeholder, actual token count if available
+        "avgRunTimeSeconds": avg_run_time,
+        "successRate": success_rate,
+    }
+
+    # Create the main agent detail
+    agent_detail = {
+        "name": agent.name,
+        "description": agent.description,
+        "interfaces": interfaces,
+        "metadata": metadata,
+        "status": status,
+    }
+
+    return agent_detail
+
+
+def list_agents(agents: List[Agent], base_url: str) -> List[Dict[str, Any]]:
+    """
+    Create a list of ACP agent details for all available agents.
+
+    Args:
+        agents: List of Agent instances
+        base_url: The base URL of the server
+
+    Returns:
+        A list of dictionaries representing agent details in ACP format
+    """
+    return [create_agent_detail(agent, base_url) for agent in agents]
+
+
+def create_health_data(agents: List[Agent]) -> Dict[str, Any]:
+    """
+    Create health data for all agents according to ACP protocol.
+
+    Args:
+        agents: List of Agent instances
+
+    Returns:
+        A dictionary with health information for all agents
+    """
+    jobs_registry = Jobs()
+
+    agents_health = {}
+    for agent in agents:
+        # Get agent jobs
+        agent_jobs = jobs_registry.get_agent_jobs(agent.name)
+
+        # Calculate job statistics
+        total_jobs = len(agent_jobs)
+        completed_jobs = sum(
+            1 for j in agent_jobs.values() if j.status == EntityStatus.COMPLETED
+        )
+        failed_jobs = sum(
+            1 for j in agent_jobs.values() if j.status == EntityStatus.FAILED
+        )
+        in_progress_jobs = sum(
+            1 for j in agent_jobs.values() if j.status == EntityStatus.IN_PROGRESS
+        )
+
+        # Set agent status based on health indicators
+        if total_jobs == 0:
+            status = "available"
+        elif failed_jobs > total_jobs / 2:  # If more than half are failing
+            status = "degraded"
+        elif in_progress_jobs > 0:
+            status = "busy"
+        else:
+            status = "available"
+
+        agents_health[agent.id] = {
+            "agent_id": agent.id,
+            "name": agent.name,
+            "status": status,
+            "version": agent.version,
+            "statistics": {
+                "total_jobs": total_jobs,
+                "completed_jobs": completed_jobs,
+                "failed_jobs": failed_jobs,
+                "in_progress_jobs": in_progress_jobs,
+                "success_rate": (completed_jobs / total_jobs * 100)
+                if total_jobs > 0
+                else 100,
+            },
+        }
+
+    return {
+        "status": "operational",
+        "timestamp": str(datetime.now()),
+        "agents": agents_health,
+    }

supervaizer/protocol/acp/routes.py

@@ -0,0 +1,74 @@
+# Copyright (c) 2024-2025 Alain Prasquier - Supervaize.com. All rights reserved.
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, you can obtain one at
+# https://mozilla.org/MPL/2.0/.
+
+from typing import TYPE_CHECKING, Any, Dict, List
+
+from fastapi import APIRouter
+
+from supervaizer.common import log
+from supervaizer.protocol.acp.model import (
+    create_agent_detail,
+    create_health_data,
+    list_agents,
+)
+from supervaizer.routes import handle_route_errors
+
+if TYPE_CHECKING:
+    from supervaizer.agent import Agent
+    from supervaizer.server import Server
+
+
+def create_routes(server: "Server") -> APIRouter:
+    """Create ACP protocol routes for the server."""
+    router = APIRouter(prefix="/agents", tags=["Protocol ACP"])
+    base_url = server.public_url or ""
+
+    @router.get(
+        "",
+        summary="ACP Agents Discovery",
+        description="Returns a list of all agents according to ACP protocol specification",
+        response_model=List[Dict[str, Any]],
+    )
+    @handle_route_errors()
+    async def get_acp_agents() -> List[Dict[str, Any]]:
+        """Get a list of all available agents in ACP format."""
+        log.info("[ACP] GET /agents [Agent discovery]")
+        return list_agents(server.agents, base_url)
+
+    # Create explicit routes for each agent
+    for agent in server.agents:
+
+        def create_agent_route(current_agent: "Agent") -> None:
+            route_path = f"/{current_agent.slug}"
+
+            @router.get(
+                route_path,
+                summary=f"ACP Agent Detail for {current_agent.name}",
+                description=f"Returns details for agent {current_agent.name} according to ACP protocol specification",
+                response_model=Dict[str, Any],
+            )
+            @handle_route_errors()
+            async def get_agent_detail() -> Dict[str, Any]:
+                """Get details for a specific agent in ACP format."""
+                log.info(f"[ACP] GET /agents/{current_agent.slug} [Agent detail]")
+                return create_agent_detail(current_agent, base_url)
+
+        # Call the closure function with the current agent
+        create_agent_route(agent)
+
+    @router.get(
+        "/health",
+        summary="ACP Health Status",
+        description="Returns health information about the server and agents",
+        response_model=Dict[str, Any],
+    )
+    @handle_route_errors()
+    async def get_acp_health() -> Dict[str, Any]:
+        """Get health information for the server and all agents."""
+        log.info("[ACP] GET /agents/health [Health status]")
+        return create_health_data(server.agents)
+
+    return router

supervaizer/py.typed

@@ -0,0 +1 @@
+# This file indicates that the supervaizer package supports type checking