ai-parrot 0.17.2__cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

parrot/openapi/config.py

@@ -0,0 +1,322 @@
+"""
+OpenAPI Configuration for AI-Parrot
+====================================
+
+Configure aiohttp-swagger3 with complete OpenAPI 3.0 schemas for all handlers.
+"""
+from pathlib import Path
+from aiohttp import web
+from aiohttp_swagger3 import (
+    SwaggerDocs,
+    SwaggerInfo,
+    SwaggerContact,
+    SwaggerLicense,
+    SwaggerUiSettings,
+    ReDocUiSettings,
+    RapiDocUiSettings
+)
+
+
+def setup_swagger(app: web.Application) -> web.Application:
+    """
+    Configure Swagger/OpenAPI documentation for AI-Parrot.
+
+    Enables three UI options:
+    - Swagger UI at /api/docs
+    - ReDoc at /api/docs/redoc
+    - RapiDoc at /api/docs/rapidoc
+
+    Args:
+        app: aiohttp Application instance
+
+    Returns:
+        Configured application with documentation endpoints
+    """
+
+    # Define API Information
+    swagger_info = SwaggerInfo(
+        title="AI-Parrot API",
+        version="1.0.0",
+        description="""
+# AI-Parrot: Multi-Agent & Chatbot Platform
+
+AI-Parrot es una plataforma completa para trabajar con LLMs, agentes y chatbots.
+
+## Características principales
+
+- 🤖 **Chatbots inteligentes** con RAG y memoria conversacional
+- 🎯 **Agentes autónomos** con herramientas y MCP servers
+- 🔄 **Orquestación de crews** para tareas complejas
+- 💾 **Vector stores** con PgVector para búsqueda semántica
+- 🔧 **Toolkits extensibles** para integración con sistemas externos
+- 📊 **Structured outputs** con validación Pydantic
+
+## Clientes LLM soportados
+
+- Google GenAI (Gemini)
+- OpenAI (GPT-4, GPT-3.5)
+- Anthropic Claude
+- Groq
+
+## Arquitectura REST
+
+Todos los endpoints siguen convenciones RESTful estándar:
+- `GET` - Obtener información
+- `POST` - Crear o ejecutar acciones
+- `PUT` - Crear recursos
+- `PATCH` - Actualizar recursos parcialmente
+- `DELETE` - Eliminar recursos
+
+## Autenticación
+
+La mayoría de endpoints requieren autenticación mediante session cookies.
+Algunos endpoints administrativos requieren privilegios de superuser.
+        """,
+        contact=SwaggerContact(
+            name="AI-Parrot Development Team",
+            url="https://github.com/phenobarbital/ai-parrot",
+            email="support@ai-parrot.dev"
+        ),
+        license=SwaggerLicense(
+            name="MIT License",
+            url="https://opensource.org/licenses/MIT"
+        ),
+        terms_of_service="https://github.com/phenobarbital/ai-parrot/blob/main/TERMS.md"
+    )
+
+    # Configure Swagger UI (familiar interface for developers)
+    swagger_ui_settings = SwaggerUiSettings(
+        path="/api/docs",
+        docExpansion="list",  # 'list', 'full', 'none'
+        filter=True,  # Enable search filter
+        deepLinking=True,  # Enable deep linking for tags and operations
+        displayRequestDuration=True,  # Show request duration
+        defaultModelsExpandDepth=3,  # Expand models by default
+        defaultModelExpandDepth=3,
+        showExtensions=True,
+        showCommonExtensions=True
+    )
+
+    # Configure ReDoc (beautiful, professional documentation)
+    redoc_ui_settings = ReDocUiSettings(
+        path="/api/docs/redoc",
+        expandResponses="200,201",  # Auto-expand successful responses
+        jsonSampleExpandLevel=3,  # Expand JSON examples
+        hideDownloadButton=False,
+        disableSearch=False,
+        hideHostname=False,
+        expandSingleSchemaField=True,
+        menuToggle=True,
+        sortPropsAlphabetically=True,
+        payloadSampleIdx=0,  # Show first example by default
+    )
+
+    # Configure RapiDoc (modern, customizable with dark mode)
+    rapidoc_ui_settings = RapiDocUiSettings(
+        path="/api/docs/rapidoc",
+        theme="dark",  # 'light' or 'dark'
+        render_style="focused",  # 'read', 'view', 'focused'
+        schema_style="tree",  # 'tree' or 'table'
+        layout="column",  # 'row' or 'column'
+        allow_try=True,  # Enable "Try it out"
+        allow_authentication=True,
+        allow_spec_url_load=False,
+        allow_spec_file_load=False,
+        heading_text="AI-Parrot API Documentation",
+        show_header=True,
+        show_info=True,
+        use_path_in_nav_bar=True,
+        nav_bg_color="#1e1e1e",
+        nav_text_color="#ffffff",
+        nav_hover_bg_color="#333333",
+        primary_color="#4CAF50",
+        font_size="default",
+    )
+
+    # Initialize SwaggerDocs
+    current_dir = Path(__file__).parent
+    components_path = current_dir / "components.yaml"
+
+    swagger = SwaggerDocs(
+        app,
+        info=swagger_info,
+        swagger_ui_settings=swagger_ui_settings,
+        redoc_ui_settings=redoc_ui_settings,
+        rapidoc_ui_settings=rapidoc_ui_settings,
+        components=str(components_path),  # External components file
+        validate=True,  # Validate requests against schema
+        request_key="swagger_dict",  # Key to store validated data in request
+    )
+
+    return app
+
+
+def get_common_responses():
+    """
+    Common HTTP responses used across all endpoints.
+
+    Returns:
+        Dict of reusable response definitions
+    """
+    return {
+        "400": {
+            "description": "Bad Request - Invalid input parameters",
+            "content": {
+                "application/json": {
+                    "schema": {
+                        "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    "example": {
+                        "error": "Bad Request",
+                        "message": "Invalid JSON in request body",
+                        "details": {}
+                    }
+                }
+            }
+        },
+        "401": {
+            "description": "Unauthorized - Authentication required",
+            "content": {
+                "application/json": {
+                    "schema": {
+                        "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    "example": {
+                        "error": "Unauthorized",
+                        "message": "Valid session required"
+                    }
+                }
+            }
+        },
+        "403": {
+            "description": "Forbidden - Insufficient permissions",
+            "content": {
+                "application/json": {
+                    "schema": {
+                        "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    "example": {
+                        "error": "Forbidden",
+                        "message": "Superuser privileges required"
+                    }
+                }
+            }
+        },
+        "404": {
+            "description": "Not Found - Resource does not exist",
+            "content": {
+                "application/json": {
+                    "schema": {
+                        "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    "example": {
+                        "error": "Not Found",
+                        "message": "Chatbot 'my_bot' not found"
+                    }
+                }
+            }
+        },
+        "422": {
+            "description": "Unprocessable Entity - Validation error",
+            "content": {
+                "application/json": {
+                    "schema": {
+                        "$ref": "#/components/schemas/ValidationErrorResponse"
+                    },
+                    "example": {
+                        "error": "Validation Error",
+                        "message": "Input validation failed",
+                        "errors": [
+                            {
+                                "loc": ["body", "temperature"],
+                                "msg": "ensure this value is less than or equal to 2.0",
+                                "type": "value_error"
+                            }
+                        ]
+                    }
+                }
+            }
+        },
+        "500": {
+            "description": "Internal Server Error",
+            "content": {
+                "application/json": {
+                    "schema": {
+                        "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    "example": {
+                        "error": "Internal Server Error",
+                        "message": "An unexpected error occurred"
+                    }
+                }
+            }
+        }
+    }
+
+
+def get_security_schemes():
+    """
+    Security schemes for API authentication.
+
+    Returns:
+        Dict of security scheme definitions
+    """
+    return {
+        "sessionAuth": {
+            "type": "apiKey",
+            "in": "cookie",
+            "name": "session",
+            "description": "Session-based authentication using HTTP cookies"
+        },
+        "bearerAuth": {
+            "type": "http",
+            "scheme": "bearer",
+            "bearerFormat": "JWT",
+            "description": "JWT token authentication"
+        }
+    }
+
+
+# Tags for organizing endpoints
+TAGS_METADATA = [
+    {
+        "name": "chatbots",
+        "description": "Operaciones relacionadas con chatbots - interacción y consulta de información",
+        "externalDocs": {
+            "description": "Chatbot documentation",
+            "url": "https://github.com/phenobarbital/ai-parrot/blob/main/docs/chatbots.md"
+        }
+    },
+    {
+        "name": "bot-management",
+        "description": "Gestión CRUD de bots/agents - crear, listar, actualizar, eliminar",
+        "externalDocs": {
+            "description": "Bot management guide",
+            "url": "https://github.com/phenobarbital/ai-parrot/blob/main/docs/bot-management.md"
+        }
+    },
+    {
+        "name": "agents",
+        "description": "Interacción con agentes autónomos - conversaciones con soporte para tools y MCP",
+        "externalDocs": {
+            "description": "Agent documentation",
+            "url": "https://github.com/phenobarbital/ai-parrot/blob/main/docs/agents.md"
+        }
+    },
+    {
+        "name": "crews",
+        "description": "Orquestación de crews multi-agente para tareas complejas",
+        "externalDocs": {
+            "description": "Crew orchestration guide",
+            "url": "https://github.com/phenobarbital/ai-parrot/blob/main/docs/crews.md"
+        }
+    },
+    {
+        "name": "tools",
+        "description": "Registro y gestión de herramientas para agentes",
+    },
+    {
+        "name": "feedback",
+        "description": "Sistema de feedback para mejorar respuestas de bots",
+    }
+]

parrot/outputs/__init__.py

@@ -0,0 +1,32 @@
+"""
+Output formatters for AI-Parrot using Rich (terminal) and Panel (HTML) with Jupyter support.
+- Interactive widgets and controls
+- Rich markdown rendering
+- Collapsible sections
+- Inline visualizations
+- Syntax highlighting
+- Tables and structured data
+
+Automatically detects and renders:
+- Folium maps
+- Plotly charts
+- Matplotlib figures
+- DataFrames
+- Bokeh plots
+- Altair charts
+- Panel dashboards
+- HTML widgets
+- Images
+
+Each output type is rendered appropriately based on the output mode (Terminal, HTML, Jupyter).
+HTML mode generates embeddable widgets for integration with Streamlit, Gradio, web apps, etc.
+"""
+from ..models.outputs import OutputMode, OutputType
+from .formatter import OutputFormatter
+
+
+__all__ = (
+    'OutputMode',
+    'OutputType',
+    'OutputFormatter',
+)

parrot/outputs/formats/__init__.py

@@ -0,0 +1,108 @@
+import contextlib
+from typing import Protocol, Dict, Type, Any, Optional
+from importlib import import_module
+from ...models.outputs import OutputMode
+
+class Renderer(Protocol):
+    """Protocol for output renderers."""
+    @staticmethod
+    def render(data: Any, **kwargs) -> Any:
+        ...
+
+
+RENDERERS: Dict[OutputMode, Type[Renderer]] = {}
+_PROMPTS: Dict[OutputMode, str] = {}
+
+
+def register_renderer(mode: OutputMode, system_prompt: Optional[str] = None):
+    """
+    Decorator to register a renderer class and optionally its system prompt.
+
+    Args:
+        mode: OutputMode enum value
+        system_prompt: Optional system prompt to inject when using this mode
+    """
+    print(':::: Registering renderer for mode:', mode)
+    def decorator(cls):
+        RENDERERS[mode] = cls
+        if system_prompt:
+            _PROMPTS[mode] = system_prompt
+        return cls
+    return decorator
+
+def get_renderer(mode: OutputMode) -> Type[Renderer]:
+    """Get the renderer class for the given output mode."""
+    if mode not in RENDERERS:
+        # Lazy load the module to register the renderer
+        with contextlib.suppress(ImportError):
+            if mode == OutputMode.TERMINAL:
+                import_module('.terminal', 'parrot.outputs.formats')
+            elif mode == OutputMode.HTML:
+                import_module('.html', 'parrot.outputs.formats')
+            elif mode == OutputMode.JSON:
+                import_module('.json', 'parrot.outputs.formats')
+            elif mode == OutputMode.MARKDOWN:
+                import_module('.markdown', 'parrot.outputs.formats')
+            elif mode == OutputMode.YAML:
+                import_module('.yaml', 'parrot.outputs.formats')
+            elif mode == OutputMode.CHART:
+                import_module('.charts', 'parrot.outputs.formats')
+            elif mode == OutputMode.MAP:
+                import_module('.map', 'parrot.outputs.formats')
+            elif mode == OutputMode.ALTAIR:
+                import_module('.altair', 'parrot.outputs.formats')
+            elif mode == OutputMode.JINJA2:
+                import_module('.jinja2', 'parrot.outputs.formats')
+            elif mode == OutputMode.TEMPLATE_REPORT:
+                import_module('.template_report', 'parrot.outputs.formats')
+            elif mode == OutputMode.BOKEH:
+                import_module('.bokeh', 'parrot.outputs.formats')
+            elif mode == OutputMode.PLOTLY:
+                import_module('.plotly', 'parrot.outputs.formats')
+            elif mode == OutputMode.MATPLOTLIB:
+                import_module('.matplotlib', 'parrot.outputs.formats')
+            elif mode == OutputMode.D3:
+                import_module('.d3', 'parrot.outputs.formats')
+            elif mode == OutputMode.ECHARTS:
+                import_module('.echarts', 'parrot.outputs.formats')
+            elif mode == OutputMode.SEABORN:
+                import_module('.seaborn', 'parrot.outputs.formats')
+            elif mode == OutputMode.HOLOVIEWS:
+                import_module('.holoviews', 'parrot.outputs.formats')
+            elif mode == OutputMode.TABLE:
+                import_module('.table', 'parrot.outputs.formats')
+            elif mode == OutputMode.APPLICATION:
+                import_module('.application', 'parrot.outputs.formats')
+            elif mode == OutputMode.CARD:
+                import_module('.card', 'parrot.outputs.formats')
+    try:
+        return RENDERERS[mode]
+    except KeyError as exc:
+        raise ValueError(
+            f"No renderer registered for mode: {mode}"
+        ) from exc
+
+def get_output_prompt(mode: OutputMode) -> Optional[str]:
+    """Get system prompt for mode."""
+    # Trigger lazy loading to ensure decorator has run
+    if mode not in _PROMPTS:
+        with contextlib.suppress(ValueError):
+            get_renderer(mode)
+    return _PROMPTS.get(mode)
+
+def has_system_prompt(mode: OutputMode) -> bool:
+    """Check if mode has a registered system prompt."""
+    if mode not in _PROMPTS:
+        with contextlib.suppress(ValueError):
+            get_renderer(mode)
+    return mode in _PROMPTS
+
+
+__all__ = (
+    'RENDERERS',
+    'register_renderer',
+    'get_renderer',
+    'Renderer',
+    'get_output_prompt',
+    'has_system_prompt',
+)