aigency 0.0.1rc235167702__py3-none-any.whl → 0.1.0__py3-none-any.whl

aigency/schemas/agent/skills.py

@@ -1,10 +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 una habilidad específica del agente."""
+    """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]
+    examples: List[str]

aigency/schemas/agent/tools.py

@@ -1,39 +1,126 @@
-"""Tool models for agent configuration."""
+"""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
+from typing import Dict, List, Optional, TypeAlias
 
 from pydantic import BaseModel
 
 
 class ToolType(str, Enum):
-    """Enum for tool types."""
+    """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 Tool(BaseModel):
-    """Define an external tool that the agent can use."""
+
+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(Tool):
-    """Configuration for function-based tools."""
+
+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."""
+    """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."""
+    """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(Tool):
-    """Configuration for MCP-based tools."""
-    mcp_config: McpTypeStreamable | McpTypeStdio
+
+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

@@ -1,3 +1,25 @@
+"""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
@@ -5,8 +27,20 @@ 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."""
+    """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

aigency/schemas/metadata/metadata.py

@@ -1,8 +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):
-    """Metadatos descriptivos del agente."""
+    """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
+    description: str

aigency/schemas/observability/observability.py

@@ -1,10 +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):
-    """Configuración de las herramientas de monitoreo."""
+    """Configuration for monitoring tools.
+
+    Attributes:
+        phoenix (Phoenix): Phoenix monitoring configuration.
+    """
+
     phoenix: Phoenix
 
+
 class Observability(BaseModel):
-    """Agrupa todas las configuraciones de observabilidad."""
-    monitoring: Monitoring
+    """Groups all observability configurations.
+
+    Attributes:
+        monitoring (Monitoring): Monitoring tools configuration.
+    """
+
+    monitoring: Monitoring

aigency/schemas/observability/phoenix.py

@@ -1,6 +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):
-    """Configuración del monitor Phoenix."""
+    """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
+    port: int

aigency/schemas/service/capabilities.py

@@ -1,5 +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):
-    """Capacidades técnicas del servicio del agente."""
-    streaming: bool
+    """Technical capabilities of the agent service.
+
+    Attributes:
+        streaming (bool): Whether the agent supports streaming responses.
+    """
+
+    streaming: bool

aigency/schemas/service/interface.py

@@ -1,7 +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 los modos de comunicación del agente."""
+    """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]
+    default_output_modes: List[str]

aigency/schemas/service/service.py

@@ -1,9 +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):
-    """Configuración de red y comunicación del agente."""
+    """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
+    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
@@ -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,7 +77,16 @@ 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}"
@@ -66,14 +113,18 @@ class ToolGenerator:
     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)