aigency 0.0.1rc15474277__py3-none-any.whl → 0.0.1rc62012314__py3-none-any.whl

aigency/schemas/agent/skills.py

@@ -0,0 +1,42 @@
+"""Agent skill definition and configuration schema.
+
+This module defines the Skill Pydantic model for representing specific capabilities
+or skills that an agent possesses within the Aigency framework. Skills define
+what an agent can do and provide structured metadata about the agent's abilities.
+
+Skills serve as descriptive components that help categorize and communicate an
+agent's capabilities to other agents and systems in the A2A ecosystem.
+
+Example:
+    Defining agent skills:
+
+    >>> skill = Skill(
+    ...     name="data_analysis",
+    ...     description="Analyze datasets and generate insights",
+    ...     tags=["analytics"]
+    ... )
+
+Attributes:
+    None: This module contains only Pydantic model definitions.
+"""
+
+from pydantic import BaseModel
+from typing import List
+
+
+class Skill(BaseModel):
+    """Define a specific skill of the agent.
+
+    Attributes:
+        id (str): Unique identifier for the skill.
+        name (str): Human-readable name of the skill.
+        description (str): Detailed description of what the skill does.
+        tags (List[str]): List of tags for categorizing the skill.
+        examples (List[str]): List of usage examples for the skill.
+    """
+
+    id: str
+    name: str
+    description: str
+    tags: List[str]
+    examples: List[str]

aigency/schemas/agent/tools.py

@@ -0,0 +1,126 @@
+"""Tool configuration schemas for agent capabilities.
+
+This module defines comprehensive Pydantic models for configuring various types
+of tools that agents can use within the Aigency framework. It supports multiple
+tool types including MCP (Model Context Protocol) tools and function-based tools,
+with specific configuration schemas for each type.
+
+The module provides a flexible and extensible tool configuration system that
+allows agents to integrate with different tool providers and execution environments,
+enabling rich agent capabilities through external tool integration.
+
+Example:
+    Configuring different tool types:
+
+    >>> function_tool = FunctionTool(
+    ...     type=ToolType.FUNCTION,
+    ...     name="calculator",
+    ...     module_path="math_tools",
+    ...     function_name="add"
+    ... )
+    >>> mcp_tool = McpTool(
+    ...     type=ToolType.MCP,
+    ...     name="file_manager",
+    ...     mcp_config=McpTypeStdio(command="file-server")
+    ... )
+
+Attributes:
+    None: This module contains only Pydantic model definitions and enums.
+"""
+
+from enum import Enum
+from typing import Dict, List, Optional, TypeAlias
+
+from pydantic import BaseModel
+
+
+class ToolType(str, Enum):
+    """Enum for tool types.
+
+    Defines the available types of tools that can be used by agents.
+
+    Attributes:
+        MCP: MCP (Model Context Protocol) based tools.
+        FUNCTION: Function-based tools loaded from Python modules.
+    """
+
+    MCP = "mcp"
+    FUNCTION = "function"
+
+
+class BaseTool(BaseModel):
+    """Define an external tool that the agent can use.
+
+    Base class for all tool configurations containing common attributes.
+
+    Attributes:
+        type (ToolType): The type of tool (MCP or FUNCTION).
+        name (str): Name identifier for the tool.
+        description (str): Human-readable description of what the tool does.
+    """
+
+    type: ToolType
+    name: str
+    description: str
+
+
+class FunctionTool(BaseTool):
+    """Configuration for function-based tools.
+
+    Tools that are loaded from Python functions in specified modules.
+
+    Attributes:
+        module_path (str): Python module path containing the function.
+        function_name (str): Name of the function to load from the module.
+    """
+
+    module_path: str
+    function_name: str
+
+
+class McpTypeStreamable(BaseModel):
+    """Model for streamable tool type.
+
+    Configuration for MCP tools that communicate via HTTP streaming.
+
+    Attributes:
+        url (str): Base URL for the MCP server.
+        port (int): Port number for the MCP server.
+        path (str): URL path for the MCP endpoint. Defaults to "/".
+    """
+
+    url: str
+    port: int
+    path: str = "/"
+
+
+class McpTypeStdio(BaseModel):
+    """Model for stdio tool type.
+
+    Configuration for MCP tools that communicate via standard input/output.
+
+    Attributes:
+        command (str): Command to execute for the MCP server.
+        args (List[str]): Command line arguments for the MCP server.
+        env (Dict[str, str], optional): Environment variables for the MCP server.
+    """
+
+    command: str
+    args: List[str]
+    env: Optional[Dict[str, str]] = None
+
+
+class McpTool(BaseTool):
+    """Configuration for MCP-based tools.
+
+    Tools that use the Model Context Protocol for communication.
+
+    Attributes:
+        mcp_config (McpTypeStreamable | McpTypeStdio): Configuration for the MCP
+            connection, either streamable HTTP or stdio based.
+    """
+
+    mcp_config: McpTypeStreamable | McpTypeStdio
+
+
+Tool: TypeAlias = FunctionTool | McpTool

aigency/schemas/aigency_config.py

@@ -0,0 +1,48 @@
+"""Root configuration model for Aigency agents.
+
+This module defines the main configuration schema for Aigency agents using Pydantic
+models. It provides a comprehensive structure that encompasses all aspects of agent
+configuration including metadata, service settings, agent logic, and observability.
+
+The AigencyConfig class serves as the root model that validates and structures
+agent configurations loaded from YAML files, ensuring type safety and proper
+validation of all configuration parameters.
+
+Example:
+    Loading and using agent configuration:
+
+    >>> config_data = yaml.safe_load(open("agent.yaml"))
+    >>> config = AigencyConfig(**config_data)
+    >>> agent_name = config.metadata.name
+    >>> model_name = config.agent.model.name
+
+Attributes:
+    None: This module contains only Pydantic model definitions.
+"""
+
+from pydantic import BaseModel
+from typing import Optional
+from aigency.schemas.observability.observability import Observability
+from aigency.schemas.metadata.metadata import Metadata
+from aigency.schemas.agent.agent import Agent
+from aigency.schemas.service.service import Service
+
+
+class AigencyConfig(BaseModel):
+    """Root Pydantic model for complete agent configuration.
+
+    This is the main configuration model that encompasses all aspects of an
+    agent's setup including metadata, service configuration, agent logic,
+    and observability settings.
+
+    Attributes:
+        metadata (Metadata): Descriptive information about the agent.
+        service (Service): Network and communication configuration.
+        agent (Agent): Core agent logic, model, and capabilities.
+        observability (Observability, optional): Monitoring and observability settings.
+    """
+
+    metadata: Metadata
+    service: Service
+    agent: Agent
+    observability: Optional[Observability] = None

aigency/schemas/metadata/metadata.py

@@ -0,0 +1,38 @@
+"""Agent metadata and descriptive information schema.
+
+This module defines the Metadata Pydantic model for storing descriptive information
+about agents in the Aigency framework. It provides structured metadata that helps
+identify, categorize, and describe agents within the system.
+
+The metadata includes essential information such as agent names, descriptions,
+versions, and other descriptive attributes that facilitate agent discovery,
+management, and documentation.
+
+Example:
+    Creating agent metadata:
+
+    >>> metadata = Metadata(
+    ...     name="data_analyst",
+    ...     description="Analyzes data and generates reports",
+    ...     version="1.0.0",
+    ... )
+
+Attributes:
+    None: This module contains only Pydantic model definitions.
+"""
+
+from pydantic import BaseModel
+
+
+class Metadata(BaseModel):
+    """Descriptive metadata of the agent.
+
+    Attributes:
+        name (str): Name of the agent.
+        version (str): Version identifier of the agent.
+        description (str): Human-readable description of the agent's purpose.
+    """
+
+    name: str
+    version: str
+    description: str

aigency/schemas/observability/observability.py

@@ -0,0 +1,45 @@
+"""Observability and monitoring configuration schemas.
+
+This module defines Pydantic models for configuring observability and monitoring
+capabilities within the Aigency framework. It provides structured configuration
+for various monitoring systems and observability tools that help track agent
+performance, behavior, and system health.
+
+The observability configuration enables comprehensive monitoring of agent
+operations, including metrics collection, logging, tracing, and integration
+with external monitoring platforms.
+
+Example:
+    Configuring observability settings:
+
+    >>> monitoring = Monitoring(phoenix=Phoenix(enabled=True, metrics_endpoint="/metrics"))
+    >>> observability = Observability(
+    ...     monitoring=monitoring
+    ... )
+
+Attributes:
+    None: This module contains only Pydantic model definitions.
+"""
+
+from pydantic import BaseModel
+from aigency.schemas.observability.phoenix import Phoenix
+
+
+class Monitoring(BaseModel):
+    """Configuration for monitoring tools.
+
+    Attributes:
+        phoenix (Phoenix): Phoenix monitoring configuration.
+    """
+
+    phoenix: Phoenix
+
+
+class Observability(BaseModel):
+    """Groups all observability configurations.
+
+    Attributes:
+        monitoring (Monitoring): Monitoring tools configuration.
+    """
+
+    monitoring: Monitoring

aigency/schemas/observability/phoenix.py

@@ -0,0 +1,36 @@
+"""Phoenix monitoring system configuration schema.
+
+This module defines the Phoenix Pydantic model for configuring Phoenix monitoring
+integration within the Aigency framework. Phoenix is a monitoring and observability
+platform that provides insights into agent behavior, performance metrics, and
+system health monitoring.
+
+The Phoenix configuration enables agents to integrate with Phoenix monitoring
+services, allowing for comprehensive tracking and analysis of agent operations
+in production environments.
+
+Example:
+    Configuring Phoenix monitoring:
+
+    >>> phoenix = Phoenix(
+    ...     host="phoenix",
+    ...     port=6006
+    ... )
+
+Attributes:
+    None: This module contains only Pydantic model definitions.
+"""
+
+from pydantic import BaseModel
+
+
+class Phoenix(BaseModel):
+    """Configuration for Phoenix monitor.
+
+    Attributes:
+        host (str): Hostname or IP address for Phoenix monitoring service.
+        port (int): Port number for Phoenix monitoring service.
+    """
+
+    host: str
+    port: int

aigency/schemas/service/capabilities.py

@@ -0,0 +1,32 @@
+"""Service capability configuration schema.
+
+This module defines the Capabilities Pydantic model for configuring service
+capabilities within the Aigency framework. It provides structured configuration
+for defining what capabilities a service or agent can provide to other components
+in the system.
+
+The capabilities configuration helps establish service contracts and enables
+proper service discovery and integration within the distributed agent ecosystem.
+
+Example:
+    Configuring service capabilities:
+
+    >>> capabilities = Capabilities(
+    ...     streaming=True
+    ... )
+
+Attributes:
+    None: This module contains only Pydantic model definitions.
+"""
+
+from pydantic import BaseModel
+
+
+class Capabilities(BaseModel):
+    """Technical capabilities of the agent service.
+
+    Attributes:
+        streaming (bool): Whether the agent supports streaming responses.
+    """
+
+    streaming: bool

aigency/schemas/service/interface.py

@@ -0,0 +1,37 @@
+"""Service interface configuration schema.
+
+This module defines the Interface Pydantic model for configuring service
+interfaces within the Aigency framework. It provides structured configuration
+for defining how services expose their functionality and communicate with
+other components in the system.
+
+The interface configuration establishes the communication protocols, endpoints,
+and interaction patterns that services use to integrate with the broader
+agent ecosystem.
+
+Example:
+    Configuring service interface:
+
+    >>> interface = Interface(
+    ...     default_input_modes=["text/plain"],
+    ...     default_output_modes=["text/plain"]
+    ... )
+
+Attributes:
+    None: This module contains only Pydantic model definitions.
+"""
+
+from typing import List
+from pydantic import BaseModel
+
+
+class Interface(BaseModel):
+    """Define the agent's communication modes.
+
+    Attributes:
+        default_input_modes (List[str]): List of supported input communication modes.
+        default_output_modes (List[str]): List of supported output communication modes.
+    """
+
+    default_input_modes: List[str]
+    default_output_modes: List[str]

aigency/schemas/service/service.py

@@ -0,0 +1,42 @@
+"""Service network and communication configuration schema.
+
+This module defines the Service Pydantic model for configuring service-level
+settings within the Aigency framework. It provides structured configuration
+for network communication, service discovery, and integration parameters
+that enable agents to operate as distributed services.
+
+The service configuration encompasses network settings, communication protocols,
+and service-specific parameters that facilitate agent deployment and operation
+in distributed environments.
+
+Example:
+    Configuring service settings:
+
+    >>> service = Service(
+    ...     interface=Interface(default_input_modes=["text/plain"]),
+    ...     capabilities=Capabilities(streaming=True),
+    ...     host="0.0.0.0",
+    ...     port=8080
+    ... )
+
+Attributes:
+    None: This module contains only Pydantic model definitions.
+"""
+
+from pydantic import BaseModel
+from aigency.schemas.service.interface import Interface
+from aigency.schemas.service.capabilities import Capabilities
+
+
+class Service(BaseModel):
+    """Network and communication configuration of the agent.
+
+    Attributes:
+        url (str): Base URL where the agent service is accessible.
+        interface (Interface): Communication interface configuration.
+        capabilities (Capabilities): Technical capabilities of the service.
+    """
+
+    url: str
+    interface: Interface
+    capabilities: Capabilities

aigency/tools/generator.py

@@ -1,7 +1,24 @@
-"""Tool Factory for dynamically loading and managing agent tools.
+"""Tool factory for dynamically loading and managing agent tools.
 
 This module provides a flexible way to load different types of tools based on
-configuration. It uses the Strategy pattern and Pydantic for validation.
+configuration using the Strategy pattern and Pydantic for validation. It supports
+both MCP (Model Context Protocol) tools and function-based tools, handling their
+instantiation and configuration automatically.
+
+The ToolGenerator class uses a strategy-based approach to delegate tool creation
+to specialized loading functions based on the tool type, providing a clean and
+extensible architecture for tool management.
+
+Example:
+    Creating tools from configuration:
+
+    >>> tool_config = FunctionTool(type=ToolType.FUNCTION, name="calculator",
+    ...                           module_path="math_tools", function_name="add")
+    >>> tool = ToolGenerator.create_tool(tool_config)
+    >>> result = tool(2, 3)
+
+Attributes:
+    None: This module contains only class definitions and strategy mappings.
 """
 
 import importlib
@@ -14,7 +31,7 @@ from google.adk.tools.mcp_tool.mcp_toolset import (
     StreamableHTTPConnectionParams,
 )
 
-from aigency.models.tools import (
+from aigency.schemas.agent.tools import (
     FunctionTool,
     McpTool,
     McpTypeStdio,
@@ -26,11 +43,32 @@ from aigency.utils.utils import expand_env_vars
 
 
 class ToolGenerator:
-    """Generator for creating tools based on configuration."""
+    """Generator for creating tools based on configuration.
+
+    This class provides static methods to dynamically load and create different
+    types of tools (MCP and Function tools) based on their configuration using
+    the Strategy pattern.
+
+    Attributes:
+        STRATEGIES (dict): Dictionary mapping tool types to their loading functions.
+    """
 
     @staticmethod
     def load_function_tool(config: FunctionTool) -> Any:
-        """Load a function tool from configuration."""
+        """Load a function tool from configuration.
+
+        Dynamically imports a Python module and retrieves the specified function
+        to use as a tool.
+
+        Args:
+            config (FunctionTool): Configuration containing module path and function name.
+
+        Returns:
+            Any: The loaded function object.
+
+        Raises:
+            ValueError: If the module cannot be imported or function not found.
+        """
         try:
             module = importlib.import_module(config.module_path)
             return getattr(module, config.function_name)
@@ -39,15 +77,20 @@ class ToolGenerator:
 
     @staticmethod
     def load_mcp_tool(config: McpTool) -> Any:
-        """Load an MCP tool from configuration."""
+        """Load an MCP tool from configuration.
+
+        Creates an MCP toolset based on the connection type (streamable HTTP or stdio).
+
+        Args:
+            config (McpTool): Configuration containing MCP connection details.
+
+        Returns:
+            Any: The created MCPToolset instance.
+        """
 
         if isinstance(config.mcp_config, McpTypeStreamable):
             url = f"http://{config.mcp_config.url}:{config.mcp_config.port}{config.mcp_config.path}"
-            return MCPToolset(
-                connection_params=StreamableHTTPConnectionParams(
-                    url=url
-                )
-            )
+            return MCPToolset(connection_params=StreamableHTTPConnectionParams(url=url))
         elif isinstance(config.mcp_config, McpTypeStdio):
             command = config.mcp_config.command
             args = config.mcp_config.args
@@ -65,19 +108,23 @@ class ToolGenerator:
         ToolType.MCP: load_mcp_tool,
         ToolType.FUNCTION: load_function_tool,
     }
-    
+
     @staticmethod
     def create_tool(tool: Tool) -> Optional[Any]:
         """Create a tool based on its configuration.
 
+        Uses the Strategy pattern to delegate tool creation to the appropriate
+        loading function based on the tool type.
+
         Args:
-            tool: Tool configuration
+            tool (Tool): Tool configuration (FunctionTool or McpTool).
 
         Returns:
-            The created tool or None if creation failed
+            Any | None: The created tool instance or None if creation failed.
 
         Raises:
-            ValueError: If tool type is not supported or config is invalid
+            ValueError: If tool type is not supported or config is invalid.
+            KeyError: If tool type is not found in STRATEGIES.
         """
 
         return ToolGenerator.STRATEGIES[tool.type](tool)