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

aigency/utils/logger.py

@@ -1,3 +1,24 @@
+"""Singleton logger implementation for consistent application-wide logging.
+
+This module provides a centralized logging system using the Singleton pattern to
+ensure consistent logging behavior across the entire Aigency application. It supports
+configurable log levels, multiple output handlers, and dynamic configuration updates.
+
+The Logger class extends the Singleton base class to guarantee only one logger
+instance exists throughout the application lifecycle, preventing configuration
+conflicts and ensuring unified log formatting and output destinations.
+
+Example:
+    Basic logger usage:
+
+    >>> logger = get_logger({"log_level": "DEBUG", "log_file": "app.log"})
+    >>> logger.info("Application started")
+    >>> logger.error("An error occurred", exc_info=True)
+
+Attributes:
+    None: This module contains only class definitions and utility functions.
+"""
+
 import logging
 import sys
 from typing import Optional, Dict, Any
@@ -5,97 +26,165 @@ from aigency.utils.singleton import Singleton
 
 
 class Logger(Singleton):
+    """Singleton logger class for consistent logging across the application.
+
+    This class provides a centralized logging mechanism that ensures only one
+    logger instance exists throughout the application lifecycle.
+
+    Attributes:
+        config (Dict[str, Any]): Configuration dictionary for logger settings.
+        _logger (logging.Logger): Internal logger instance.
+        _initialized (bool): Flag to track initialization state.
+    """
+
     def __init__(self, config: Optional[Dict[str, Any]] = None):
-        if hasattr(self, '_initialized'):
-            # Si ya está inicializado y se pasa nueva config, actualizar
-            if config and config != getattr(self, 'config', {}):
+        """Initialize the logger with optional configuration.
+
+        Args:
+            config (Dict[str, Any], optional): Dictionary containing logger
+                configuration. Defaults to None.
+        """
+        if hasattr(self, "_initialized"):
+            # If already initialized and new config is passed, update
+            if config and config != getattr(self, "config", {}):
                 self.config.update(config)
                 self._setup_logger()
             return
-        
+
         self._initialized = True
         self.config = config or {}
         self._logger = None
         self._setup_logger()
-    
+
     def _setup_logger(self):
-        """Configura el logger con la configuración proporcionada"""
-        # Obtener configuración del logger
-        log_level = self.config.get('log_level', 'INFO').upper()
-        log_format = self.config.get('log_format', '%(asctime)s - %(name)s - %(levelname)s - %(message)s')
-        log_file = self.config.get('log_file')
-        logger_name = self.config.get('logger_name', 'aigency')
-        
-        # Crear logger
+        """Configure the logger with the provided configuration.
+
+        Sets up the internal logger instance with handlers, formatters, and
+        log levels based on the configuration dictionary.
+        """
+        # Get logger configuration
+        log_level = self.config.get("log_level", "INFO").upper()
+        log_format = self.config.get(
+            "log_format", "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+        )
+        log_file = self.config.get("log_file")
+        logger_name = self.config.get("logger_name", "aigency")
+
+        # Create logger
         self._logger = logging.getLogger(logger_name)
         self._logger.setLevel(getattr(logging, log_level, logging.INFO))
-        
-        # Evitar duplicar handlers si ya existen
+
+        # Avoid duplicating handlers if they already exist
         if self._logger.handlers:
             return
-        
-        # Crear formatter
+
+        # Create formatter
         formatter = logging.Formatter(log_format)
-        
-        # Handler para consola
+
+        # Console handler
         console_handler = logging.StreamHandler(sys.stdout)
         console_handler.setLevel(getattr(logging, log_level, logging.INFO))
         console_handler.setFormatter(formatter)
         self._logger.addHandler(console_handler)
-        
-        # Handler para archivo si se especifica
+
+        # File handler if specified
         if log_file:
             file_handler = logging.FileHandler(log_file)
             file_handler.setLevel(getattr(logging, log_level, logging.INFO))
             file_handler.setFormatter(formatter)
             self._logger.addHandler(file_handler)
-    
+
     def debug(self, message: str, *args, **kwargs):
-        """Log a debug message"""
+        """Log a debug message.
+
+        Args:
+            message (str): The message to log.
+            *args: Variable length argument list.
+            **kwargs: Arbitrary keyword arguments.
+        """
         self._logger.debug(message, *args, **kwargs)
-    
+
     def info(self, message: str, *args, **kwargs):
-        """Log an info message"""
+        """Log an info message.
+
+        Args:
+            message (str): The message to log.
+            *args: Variable length argument list.
+            **kwargs: Arbitrary keyword arguments.
+        """
         self._logger.info(message, *args, **kwargs)
-    
+
     def warning(self, message: str, *args, **kwargs):
-        """Log a warning message"""
+        """Log a warning message.
+
+        Args:
+            message (str): The message to log.
+            *args: Variable length argument list.
+            **kwargs: Arbitrary keyword arguments.
+        """
         self._logger.warning(message, *args, **kwargs)
-    
+
     def error(self, message: str, *args, **kwargs):
-        """Log an error message"""
+        """Log an error message.
+
+        Args:
+            message (str): The message to log.
+            *args: Variable length argument list.
+            **kwargs: Arbitrary keyword arguments.
+        """
         self._logger.error(message, *args, **kwargs)
-    
+
     def critical(self, message: str, *args, **kwargs):
-        """Log a critical message"""
+        """Log a critical message.
+
+        Args:
+            message (str): The message to log.
+            *args: Variable length argument list.
+            **kwargs: Arbitrary keyword arguments.
+        """
         self._logger.critical(message, *args, **kwargs)
-    
+
     def exception(self, message: str, *args, **kwargs):
-        """Log an exception with traceback"""
+        """Log an exception with traceback.
+
+        Args:
+            message (str): The message to log.
+            *args: Variable length argument list.
+            **kwargs: Arbitrary keyword arguments.
+        """
         self._logger.exception(message, *args, **kwargs)
-    
+
     def set_level(self, level: str):
-        """Cambiar el nivel de logging dinámicamente"""
+        """Change the logging level dynamically.
+
+        Args:
+            level (str): The new logging level as a string.
+        """
         log_level = level.upper()
         self._logger.setLevel(getattr(logging, log_level, logging.INFO))
         for handler in self._logger.handlers:
             handler.setLevel(getattr(logging, log_level, logging.INFO))
-    
+
     def get_logger(self):
-        """Obtener la instancia del logger interno"""
+        """Get the internal logger instance.
+
+        Returns:
+            logging.Logger: The internal logging.Logger instance.
+        """
         return self._logger
 
 
-# Función de conveniencia para obtener la instancia del logger
+# Convenience function to get the logger instance
 def get_logger(config: Optional[Dict[str, Any]] = None) -> Logger:
-    """
-    Obtiene la instancia singleton del logger.
-    Si es la primera vez que se llama y se proporciona config, se usa esa configuración.
-    
+    """Get the singleton logger instance.
+
+    If this is the first call and config is provided, that configuration is used.
+
     Args:
-        config: Configuración opcional para el logger (solo se usa en la primera llamada)
-    
+        config (Dict[str, Any], optional): Optional configuration for the logger
+            (only used on first call). Defaults to None.
+
     Returns:
-        Instancia singleton del Logger
+        Logger: Singleton Logger instance.
     """
-    return Logger(config)
+    return Logger(config)

aigency/utils/singleton.py

@@ -1,7 +1,54 @@
+"""Singleton pattern implementation using metaclasses.
+
+This module provides a robust implementation of the Singleton design pattern using
+Python metaclasses. It ensures that classes inheriting from the Singleton base class
+can have only one instance throughout the application lifecycle, which is useful
+for shared resources like loggers, configuration managers, and database connections.
+
+The implementation uses a metaclass approach to control instance creation at the
+class level, providing thread-safe singleton behavior without requiring explicit
+synchronization in the client code.
+
+Example:
+    Creating singleton classes:
+
+    >>> class DatabaseManager(Singleton):
+    ...     def __init__(self):
+    ...         self.connection = "db_connection"
+    >>>
+    >>> db1 = DatabaseManager()
+    >>> db2 = DatabaseManager()
+    >>> db1 is db2
+    True
+
+Attributes:
+    None: This module contains only class definitions.
+"""
+
+
 class SingletonMeta(type):
+    """Metaclass that implements the Singleton pattern.
+
+    This metaclass ensures that only one instance of a class can exist.
+    When a class uses this metaclass, subsequent instantiation attempts
+    will return the same instance.
+
+    Attributes:
+        _instances (dict): Dictionary storing singleton instances by class.
+    """
+
     _instances = {}
 
     def __call__(cls, *args, **kwargs):
+        """Control instance creation to ensure singleton behavior.
+
+        Args:
+            *args: Variable length argument list for class instantiation.
+            **kwargs: Arbitrary keyword arguments for class instantiation.
+
+        Returns:
+            object: The singleton instance of the class.
+        """
         if cls not in cls._instances:
             instance = super().__call__(*args, **kwargs)
             cls._instances[cls] = instance
@@ -9,4 +56,18 @@ class SingletonMeta(type):
 
 
 class Singleton(metaclass=SingletonMeta):
-    pass
+    """Base class for implementing singleton pattern.
+
+    Classes that inherit from this base class will automatically
+    follow the singleton pattern, ensuring only one instance exists.
+
+    Example:
+        >>> class MyClass(Singleton):
+        ...     pass
+        >>> obj1 = MyClass()
+        >>> obj2 = MyClass()
+        >>> obj1 is obj2
+        True
+    """
+
+    pass

aigency/utils/utils.py

@@ -1,4 +1,23 @@
-"""Utility functions for type conversions and environment variable handling."""
+"""Utility functions for type conversions and environment variable handling.
+
+This module provides essential utility functions for the Aigency framework, including
+type conversions between A2A and Google GenAI formats, environment variable expansion,
+URL generation, and safe asynchronous execution helpers.
+
+The utilities handle common operations needed across the framework, such as converting
+message parts between different protocol formats, managing environment variables in
+configurations, and safely running coroutines in various asyncio contexts.
+
+Example:
+    Converting between A2A and GenAI formats:
+
+    >>> a2a_part = TextPart(text="Hello world")
+    >>> genai_part = convert_a2a_part_to_genai(a2a_part)
+    >>> back_to_a2a = convert_genai_part_to_a2a(genai_part)
+
+Attributes:
+    logger: Module-level logger instance for utility operations.
+"""
 
 import asyncio
 import os
@@ -57,9 +76,17 @@ def convert_genai_part_to_a2a(part: types.Part) -> Part:
 
 
 def expand_env_vars(env_dict):
-    """
-    Expande los valores del diccionario usando variables de entorno solo si el valor es una clave de entorno existente.
-    Si la variable no existe en el entorno, deja el valor literal.
+    """Expand dictionary values using environment variables.
+
+    Expands values in the dictionary using environment variables only if the value
+    is an existing environment variable key. If the variable doesn't exist in the
+    environment, leaves the literal value.
+
+    Args:
+        env_dict (dict): Dictionary with potential environment variable references.
+
+    Returns:
+        dict: Dictionary with expanded environment variable values.
     """
     result = {}
     for k, v in env_dict.items():
@@ -85,7 +112,20 @@ def generate_url(host: str, port: int, path: str = "") -> str:
 
 
 def safe_async_run(coro):
-    """Simple wrapper to safely run async code."""
+    """Simple wrapper to safely run async code.
+
+    This function handles different asyncio event loop scenarios to safely
+    execute coroutines, including cases where a loop is already running.
+
+    Args:
+        coro: The coroutine to execute.
+
+    Returns:
+        Any: The result of the coroutine execution.
+
+    Raises:
+        Exception: Any exception raised by the coroutine.
+    """
     try:
         loop = asyncio.get_event_loop()
         if loop.is_running():
@@ -111,4 +151,3 @@ def safe_async_run(coro):
             return loop.run_until_complete(coro)
     except RuntimeError:
         return asyncio.run(coro)
-

aigency-0.1.0.dist-info/METADATA

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: aigency
+Version: 0.1.0
+Summary: Add your description here
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: google-adk>=1.11.0
+Requires-Dist: a2a-sdk>=0.3.0
+Requires-Dist: litellm<1.73.0,>=1.72.6
+Requires-Dist: pyyaml==6.0.2
+Requires-Dist: PyJWT==2.10.1
+
+# Aigency
+
+AI Agent Development Acceleration Kit — build, run, and orchestrate intelligent agents with a production‑ready Agent‑to‑Agent (A2A) runtime.
+
+Aigency provides primitives and utilities to define agents via simple YAML, instantiate them programmatically, and serve them over HTTP using the A2A server. It is designed to be modular, observable, and extensible.
+
+- Python: >= 3.12
+- PyPI package: `aigency`
+- Core deps: `a2a-sdk`, `pyyaml`, `litellm`, `PyJWT`, `google-adk`
+
+## Features
+- Config‑first agents: define agent behavior, skills, tools, and model in YAML
+- Agent generator: instantiate agents, build agent cards, and executors programmatically
+- A2A integration: serve agents over HTTP with Starlette‑based A2A server
+- MCP‑friendly: integrate external tools/services via Model Context Protocol (optional)
+- Observability: compatible with Phoenix and A2A Inspector for tracing and debugging
+- Docker‑friendly: used across example demos and containers
+
+## Installation
+```bash
+pip install aigency
+```
+Requires Python 3.12+.
+
+## Quickstart
+Minimal example for a single agent (no MCP) that responds in the user’s language.
+
+1) Create an agent config file (e.g., `agent_config.yaml`):
+```yaml
+metadata:
+  name: hello_agent
+  description: A simple example agent that greets and answers briefly.
+  version: 1.0.0
+
+service:
+  url: http://hello-agent:8080
+  capabilities:
+    streaming: true
+  interface:
+    default_input_modes: [text, text/plain]
+    default_output_modes: [text, text/plain]
+
+agent:
+  model:
+    name: gemini-2.0-flash
+
+  instruction: |
+      """
+      You are a friendly, concise assistant. Always reply in the same language as the user.
+      Keep responses short and helpful.
+      """
+
+  skills:
+    - id: greet
+      name: Greet
+      description: Greets users and offers help
+      examples:
+        - "Hello! How can I help you today?"
+```
+
+2) Run a tiny A2A app (e.g., `app.py`):
+```python
+import os
+import uvicorn
+from a2a.server.apps import A2AStarletteApplication
+from a2a.server.request_handlers import DefaultRequestHandler
+from a2a.server.tasks import InMemoryTaskStore
+from aigency.agents.generator import AgentA2AGenerator
+from aigency.utils.config_service import ConfigService
+
+CONFIG_PATH = os.path.join(os.path.dirname(__file__), "agent_config.yaml")
+
+config_service = ConfigService(config_file=CONFIG_PATH)
+agent_config = config_service.config
+
+agent = AgentA2AGenerator.create_agent(agent_config=agent_config)
+agent_card = AgentA2AGenerator.build_agent_card(agent_config=agent_config)
+executor = AgentA2AGenerator.build_executor(agent=agent, agent_card=agent_card)
+
+request_handler = DefaultRequestHandler(
+    agent_executor=executor,
+    task_store=InMemoryTaskStore(),
+)
+app = A2AStarletteApplication(
+    agent_card=agent_card,
+    http_handler=request_handler,
+).build()
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8080)
+```
+
+3) Start the server:
+```bash
+python app.py
+```
+Then open http://localhost:8080 to interact via the A2A HTTP interface or connect a compatible client.
+
+## Using Models & Providers
+Aigency integrates with LLM providers via its dependencies. For Google Gemini models:
+
+- Use API key (Google AI Studio):
+  - `GEMINI_API_KEY=your_gemini_api_key`
+  - `GOOGLE_GENAI_USE_VERTEXAI=FALSE`
+- Or use Vertex AI (requires additional env like project/region and credentials):
+  - `GOOGLE_GENAI_USE_VERTEXAI=TRUE`
+
+Set these environment variables before running your app if you use Gemini‑based models.
+
+## Configuration Reference (YAML)
+Common top‑level sections:
+
+- `metadata`: name, description, version
+- `service`: url, capabilities, interface defaults
+- `agent`:
+  - `model`: model name (e.g., `gemini-2.0-flash`)
+  - `instruction`: system prompt/persona
+  - `skills`: list of skills with `id`, `name`, `description`, and `examples`
+  - `tools`: optional integrations (e.g., MCP tools)
+- `observability`: optional Phoenix/A2A Inspector configuration
+
+Example of adding an MCP tool:
+```yaml
+tools:
+  - type: mcp
+    name: sample_mcp
+    description: Example MCP tool
+    mcp_config:
+      url: sample-mcp-service
+      port: 8080
+      path: /mcp/
+```
+
+## Examples & Demos
+Explore ready‑to‑run demos built with Aigency:
+
+- Reception Agent (single agent, no MCP):
+  https://aigency-project.github.io/get_started/demos/reception_aigent
+- Gossip Agent (single agent + MCP tools):
+  https://aigency-project.github.io/get_started/demos/gossip_agent
+- Detective Aigency (multi‑agent system):
+  https://aigency-project.github.io/get_started/demos/detective_aigency/
+
+Documentation site:
+- https://aigency-project.github.io/
+
+## Observability
+Aigency‑based apps can be observed with:
+- Phoenix dashboard (tracing/metrics)
+- A2A Inspector (agent/task introspection)
+
+Refer to the demo repositories for docker‑compose setups that launch these services.
+
+## Development
+- Python 3.12+
+- Install dev deps and run tests as usual; for versioning helpers, see `scripts/version_manager.py` in this repo.
+
+## License
+This project’s license is provided in the `LICENSE` file.

aigency-0.1.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+aigency/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aigency/agents/client.py,sha256=M2j6NpzjG4aeLmYY0NMsgjb6HQSLMVz9Cba7WJsEIQ8,2651
+aigency/agents/communicator.py,sha256=qr77SolCIiNrp7nmuFfPOscmdPnCWmgQwPQcBwJIlt4,5712
+aigency/agents/executor.py,sha256=0FdWQodUeTnYbMGe3CPOYxzhQ2uF0S7m2aJudTrdx20,7494
+aigency/agents/generator.py,sha256=D1O0Vn96kyruv6yvuZUWhE5yGxDpoUrYiDQpOEcS6N8,7363
+aigency/schemas/aigency_config.py,sha256=qbcHjmmMAG_-nWY689aS9wQ0gzbroQTpjPb9MlDBfmc,1817
+aigency/schemas/agent/agent.py,sha256=NamGZsk9ajOmIJiLyoSdFZsbJ8av6-0d2mTgHNG5z64,1910
+aigency/schemas/agent/model.py,sha256=FKLoXiPamrsFs1G8jFQkn0nvdp3rIlpMUg5BWmL1Klc,1381
+aigency/schemas/agent/remote_agent.py,sha256=wfqirTisFGQFwOAU_oKLyiYw_61ZZVp7lIfe1g_11ZA,1244
+aigency/schemas/agent/skills.py,sha256=LZntfTygAhuv09m5URbkygDhCD0-Sl2A9gEAJkgCncg,1287
+aigency/schemas/agent/tools.py,sha256=ANyzJstAFn3dg5JjpiwTGmkOHSFJ4-Ry7Fw2nmj1XNk,3526
+aigency/schemas/metadata/metadata.py,sha256=9mKSJgLfwjhRrKD3pvdNIuhk6b8c3pz1YaVIb5qOWMY,1108
+aigency/schemas/observability/observability.py,sha256=DHY4zmFg_qy7U97YILRJ02Y0tWNgcNB9w7akZaNbyfo,1302
+aigency/schemas/observability/phoenix.py,sha256=SpiStSw5xbXkEZH8HW56rCidMyjBi3OT3Y2i4D0tA_k,1018
+aigency/schemas/service/capabilities.py,sha256=sMQtqCaXYVnDebdKhZ48iKDL1h9CoXWoxh7TFm1LO6E,898
+aigency/schemas/service/interface.py,sha256=Jcp9Wy2sArhdeh_PiQNqcl0f2IMbipo3Muw5EWIoiiE,1140
+aigency/schemas/service/service.py,sha256=E_KZNiM-7DJS4Ezd8xPfFq_W8HkzIFZvzGe4sreDfjY,1415
+aigency/tools/generator.py,sha256=wMk5rt8wXSCci_K-vVyUMKvNuWlJcnpB7Y3SxRnfgG4,4355
+aigency/utils/config_service.py,sha256=ZE7xptJ20zk9sAJMxcDa2QYWMPhzfiW95gHquSX8E3s,5852
+aigency/utils/logger.py,sha256=kOIWbCTFiT4coz3cqcvD-YAu_EqIy4bqLBdaJ-sYOnk,6602
+aigency/utils/singleton.py,sha256=zwIj5c-A3F6BhK16AnwwxUX_qr_AbPAab-477nSGf7w,2267
+aigency/utils/utils.py,sha256=qjnzCV_5yOT0XG870_jU-xYnQeK1TUqVksU5Rnefxcs,4470
+aigency-0.1.0.dist-info/METADATA,sha256=XNj8kLxh_5HpkN5xAJrNEeVD_DZa6-ktlfW7CqnNXgo,5400
+aigency-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+aigency-0.1.0.dist-info/top_level.txt,sha256=nr33Htucgjs3wJFNugPV8w7b9ZgSnytxCtRiinR3eb8,8
+aigency-0.1.0.dist-info/RECORD,,