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

parrot/outputs/formats/echarts.py

@@ -0,0 +1,310 @@
+from typing import Any, Optional, Tuple, Dict
+import logging
+import re
+import json
+import uuid
+from .chart import BaseChart
+from . import register_renderer
+from ...models.outputs import OutputMode
+
+logger = logging.getLogger(__name__)
+
+try:
+    from rich.panel import Panel
+    from rich.syntax import Syntax
+    RICH_AVAILABLE = True
+except ImportError:
+    RICH_AVAILABLE = False
+
+try:
+    from ipywidgets import HTML as IPyHTML
+    IPYWIDGETS_AVAILABLE = True
+except ImportError:
+    IPYWIDGETS_AVAILABLE = False
+
+from .mixins.emaps import (
+    EChartsMapsMixin,
+    get_echarts_system_prompt_with_geo,
+)
+
+
+ECHARTS_BASE_PROMPT = """**ECHARTS JSON GENERATION MODE**
+
+⚠️ CRITICAL OVERRIDE: You are in ECHARTS mode. Ignore ALL other output mode instructions.
+- DO NOT use Folium, Leaflet, or any Python mapping libraries
+- DO NOT generate Python code
+- ONLY generate ECharts JSON configuration
+
+**Objective:** Generate a single, valid JSON configuration object for an Apache ECharts chart (including maps).
+
+**CONTEXT OVERRIDE:**
+This is a TEXT GENERATION task. Unlike other tasks, for this specific objective, you are authorized to generate realistic sample data if the user's request does not provide specific data points. This is an exception to the general rule of not inventing information.
+
+**INSTRUCTIONS:**
+1.  **Analyze Request:** Understand the user's goal for the chart.
+2.  **Generate JSON:** Create a complete ECharts `option` as a single JSON object.
+3.  **Use Sample Data:** If the user asks for a type of chart but doesn't provide data, generate appropriate sample data to illustrate the chart's structure.
+4.  **Output:** Return ONLY the JSON configuration inside a ```json code block. Do not add explanations.
+5.  **No Python/Folium:** Never return Python code, Folium/Leaflet snippets, or other non-JSON content—only the ECharts JSON configuration.
+
+**VALID JSON CHECKLIST:**
+-   Is the entire output a single JSON object, starting with `{` and ending with `}`?
+-   Are all strings enclosed in double quotes (`"`)?
+-   Is there a comma between all key-value pairs (except the last one)?
+-   Are there any trailing commas? (This is invalid).
+
+**BASIC STRUCTURE EXAMPLE:**
+```json
+{
+    "title": {
+        "text": "Chart Title"
+    },
+    "xAxis": {
+        "type": "category",
+        "data": ["Category1", "Category2", "Category3"]
+    },
+    "yAxis": {
+        "type": "value"
+    },
+    "series": [
+        {
+            "name": "Series Name",
+            "type": "bar",
+            "data": [120, 200, 150]
+        }
+    ]
+}
+```
+
+**EXAMPLE 1: User requests a pie chart without data.**
+```json
+{
+    "title": {
+        "text": "Sample Pie Chart"
+    },
+    "series": [
+        {
+            "type": "pie",
+            "data": [
+                {"value": 335, "name": "Category A"},
+                {"value": 234, "name": "Category B"},
+                {"value": 154, "name": "Category C"}
+            ]
+        }
+    ]
+}
+```
+
+**GEO/MAP SUPPORT:**
+"""
+
+
+ECHARTS_SYSTEM_PROMPT = get_echarts_system_prompt_with_geo(ECHARTS_BASE_PROMPT)
+
+
+@register_renderer(OutputMode.ECHARTS, system_prompt=ECHARTS_SYSTEM_PROMPT)
+class EChartsRenderer(EChartsMapsMixin, BaseChart):
+    """Renderer for Apache ECharts (JSON Configuration)"""
+
+    def execute_code(
+        self,
+        code: str,
+        pandas_tool: Any = None,
+        **kwargs,
+    ) -> Tuple[Any, Optional[str]]:
+        """Parse and validate ECharts JSON configuration."""
+        try:
+            # Clean up code string if needed (remove markdown blocks if still present)
+            cleaned_code = self._extract_json_code(code) or code
+
+            # Parse JSON
+            config = json.loads(cleaned_code)
+
+            # Unwrap common nested structure `{ "option": { ... } }`
+            if (
+                isinstance(config, dict)
+                and 'option' in config
+                and isinstance(config['option'], dict)
+            ):
+                # If the response wraps the actual chart config under an
+                # "option" key, use the inner configuration for validation and
+                # rendering. This aligns with typical ECharts code snippets and
+                # prevents false validation errors.
+                config = config['option']
+
+            # Basic validation - check for required structure
+            if not isinstance(config, dict):
+                return None, "ECharts config must be a JSON object"
+
+            # 'series' is usually required, but 'dataset' or 'options' (for timeline) are also valid
+            if all(
+                k not in config
+                for k in ['series', 'dataset', 'options', 'baseOption']
+            ):
+                return None, "ECharts config must include 'series', 'dataset', or timeline 'options'"
+
+            return config, None
+
+        except json.JSONDecodeError as e:
+            return None, f"Invalid JSON: {str(e)}"
+        except Exception as e:
+            return None, f"Validation error: {str(e)}"
+
+    def _render_chart_content(self, chart_obj: Any, **kwargs) -> str:
+        """Render ECharts visualization content (HTML/JS)."""
+        # chart_obj is the configuration dict
+        config = chart_obj
+        chart_id = f"echarts-{uuid.uuid4().hex[:8]}"
+
+        # Convert to JSON
+        # config_json = json.dumps(config, indent=2)
+        # Get dimensions
+        width = kwargs.get('width', '100%')
+        height = kwargs.get('height', '500px')
+        # return f'''
+        # <div id="{chart_id}" style="width: {width}; height: {height};"></div>
+        # <script type="text/javascript">
+        #     (function() {{
+        #         var chartDom = document.getElementById('{chart_id}');
+        #         if (!chartDom) return;
+
+        #         var myChart = echarts.init(chartDom);
+        #         var option = {config_json};
+
+        #         option && myChart.setOption(option);
+
+        #         // Resize handler
+        #         window.addEventListener('resize', function() {{
+        #             myChart.resize();
+        #         }});
+
+        #         console.log('ECharts {chart_id} rendered successfully');
+        #     }})();
+        # </script>
+        # '''
+        # Use mixin method for enhanced geo rendering
+        return self._render_chart_content_geo(config, chart_id, width, height)
+
+    def to_html(
+        self,
+        chart_obj: Any,
+        mode: str = 'partial',
+        **kwargs
+    ) -> str:
+        """Convert ECharts to HTML."""
+        # ECharts library for <head>
+        echarts_version = kwargs.get('echarts_version', '5.4.3')
+
+        # Proper CDN URL (no markdown syntax)
+        extra_head = kwargs.get('extra_head', '') + f"""
+    <!-- Apache ECharts -->
+    <script src="https://cdn.jsdelivr.net/npm/echarts@{echarts_version}/dist/echarts.min.js"></script>
+        """
+
+        kwargs['extra_head'] = extra_head
+
+        # Call parent to_html
+        return super().to_html(chart_obj, mode=mode, **kwargs)
+
+    async def render(
+        self,
+        response: Any,
+        theme: str = 'monokai',
+        environment: str = 'html',
+        include_code: bool = False,
+        html_mode: str = 'partial',
+        **kwargs
+    ) -> Tuple[Any, Optional[Any]]:
+        """Render ECharts visualization."""
+
+        # 1. Extract Code
+        code = getattr(response, 'code', None)
+        output_format = kwargs.get('output_format', environment)
+
+        # Fallback: Extract from text if not in structured output
+        if not code:
+            content = self._get_content(response)
+            code = self._extract_json_code(content)
+
+        if not code:
+            error_msg = "No ECharts configuration found in response"
+            if output_format == 'terminal':
+                return error_msg, None
+            error_html = self._wrap_for_environment(
+                f"<div class='error'>{error_msg}</div>",
+                output_format
+            )
+            if output_format == 'html':
+                return None, error_html
+            return error_html, None
+
+        # 2. Parse/Execute (Validation)
+        config, error = self.execute_code(code)
+
+        if error:
+            logger.error("Failed to parse ECharts JSON: %s", error)
+            if output_format == 'terminal':
+                return f"Error parsing JSON: {error}\n\n{code}", None
+            error_html = self._wrap_for_environment(
+                self._render_error(error, code, theme),
+                output_format
+            )
+            if output_format == 'html':
+                return code, error_html
+            return code, error_html
+
+        # 3. Handle Terminal Environment (Show JSON)
+        if output_format == 'terminal':
+            if RICH_AVAILABLE:
+                json_syntax = Syntax(
+                    json.dumps(config, indent=2), "json", theme=theme, line_numbers=True
+                )
+                return Panel(json_syntax, title="📊 ECharts Configuration (JSON)", border_style="blue"), None
+            return json.dumps(config, indent=2), None
+
+        # 4. Generate HTML for Web/Jupyter
+        html_output = self.to_html(
+            config,
+            mode=html_mode,
+            include_code=include_code,
+            code=code,
+            theme=theme,
+            title=kwargs.pop('title', 'ECharts Visualization'),
+            icon='📊',
+            **kwargs
+        )
+
+        # 5. Wrap for Environment
+        if output_format in {'jupyter', 'notebook', 'ipython', 'colab'}:
+            wrapped_html = self._wrap_for_environment(html_output, output_format)
+        else:
+            wrapped_html = html_output
+
+        # 6. Return based on output format
+        if output_format == 'html':
+            # Return the generated code along with the wrapped HTML
+            return code, wrapped_html
+
+        # Default: Return Code + Wrapped Output
+        return code, wrapped_html
+
+    @staticmethod
+    def _extract_json_code(content: str) -> Optional[str]:
+        """Extract JSON code from markdown blocks."""
+        # Try json code block
+        pattern = r'```json\n(.*?)```'
+        if matches := re.findall(pattern, content, re.DOTALL):
+            return matches[0].strip()
+
+        # Try generic code block
+        pattern = r'```\n(.*?)```'
+        if matches := re.findall(pattern, content, re.DOTALL):
+            # Check if it looks like JSON
+            potential_json = matches[0].strip()
+            if potential_json.startswith('{') or potential_json.startswith('['):
+                return potential_json
+
+        # Maybe the content IS just the JSON string?
+        content = content.strip()
+        return content if content.startswith('{') and content.endswith('}') else None
+

parrot/outputs/formats/generators/abstract.py

@@ -0,0 +1,61 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional
+import pandas as pd
+
+class AbstractAppGenerator(ABC):
+    """
+    Abstract base class for Application Generators.
+    Handles payload extraction and defines the interface for generation.
+    """
+
+    def __init__(self, response: Any):
+        self.response = response
+        self.payload = self._extract_payload(response)
+
+    def _extract_payload(self, response: Any) -> Dict[str, Any]:
+        """
+        Extract and normalize the payload from the Agent Response.
+        Can be overridden by subclasses for specific needs.
+        """
+        payload = {
+            "input": getattr(response, "input", "No query provided"),
+            "explanation": "",
+            "data": pd.DataFrame(),
+            "code": None
+        }
+
+        # 1. Extract Explanation
+        output = getattr(response, "output", "")
+        if hasattr(output, "explanation"):
+            payload["explanation"] = output.explanation
+        elif hasattr(output, "response"):
+            payload["explanation"] = output.response
+        elif isinstance(output, str):
+            payload["explanation"] = output
+
+        # 2. Extract Data
+        if hasattr(output, "to_dataframe"):
+            payload["data"] = output.to_dataframe()
+        elif hasattr(output, "data") and output.data is not None:
+            payload["data"] = pd.DataFrame(output.data)
+        elif hasattr(response, "data") and response.data is not None:
+            if isinstance(response.data, pd.DataFrame):
+                payload["data"] = response.data
+            else:
+                payload["data"] = pd.DataFrame(response.data)
+
+        # 3. Extract Code
+        if hasattr(output, "code") and output.code:
+            payload["code"] = output.code
+        elif hasattr(response, "code") and response.code:
+            payload["code"] = response.code
+
+        return payload
+
+    @abstractmethod
+    def generate(self) -> Any:
+        """
+        Generate the application output.
+        Returns source code string (for web apps) or Renderable (for terminal).
+        """
+        pass

parrot/outputs/formats/generators/panel.py

@@ -0,0 +1,145 @@
+from typing import Any, Dict
+import json
+import pandas as pd
+from .abstract import AbstractAppGenerator
+
+
+class PanelGenerator(AbstractAppGenerator):
+    """Generates a single-file Panel application."""
+
+    def generate(self) -> str:
+        # 1. Serialize Data for Embedding
+        data_str = "[]"
+        if not self.payload["data"].empty:
+            data_str = self.payload["data"].to_json(orient="records")
+
+        # 2. Sanitize Strings
+        explanation = self.payload["explanation"].replace('"""', "\\\"\\\"\\\"")
+        query = self.payload["input"].replace('"', '\\"')
+        # 3. Construct Visualization Logic
+        viz_code = ""
+        imports = ["import panel as pn", "import pandas as pd", "import json"]
+
+        if code_snippet := self.payload["code"]:
+            if isinstance(code_snippet, (dict, list)):
+                # JSON Specification (Altair/Vega-Lite)
+                imports.append("import altair as alt")
+                viz_code = f"""
+# --- Visualization (Vega-Lite JSON) ---
+spec = {json.dumps(code_snippet)}
+viz_pane = pn.pane.Vega(spec, sizing_mode='stretch_width', height=400)
+                """
+            elif isinstance(code_snippet, str):
+                # Python Code Execution
+                # We wrap the execution to capture the figure
+                viz_code = f"""
+# --- Visualization (Dynamic Code) ---
+def get_visualization(df):
+    try:
+        # Inject dataframe into local scope
+        local_vars = {{'df': df, 'pd': pd, 'pn': pn}}
+
+        # Execute the generated code
+        exec('''{code_snippet}''', globals(), local_vars)
+
+        # Attempt to find a renderable object in locals
+        # Priority: 'fig', 'chart', 'map', or the last expression
+        for var_name in ['fig', 'chart', 'map', 'm']:
+            if var_name in local_vars:
+                return local_vars[var_name]
+        return None
+    except Exception as e:
+        return pn.pane.Alert(f"Error rendering chart: {{e}}", alert_type="danger")
+
+viz_obj = get_visualization(df)
+
+# Determine appropriate pane type based on object
+if viz_obj:
+    if hasattr(viz_obj, 'to_dict') and 'data' in viz_obj.to_dict(): # Plotly
+        viz_pane = pn.pane.Plotly(viz_obj, sizing_mode='stretch_width', height=400)
+    elif hasattr(viz_obj, 'savefig'): # Matplotlib
+        viz_pane = pn.pane.Matplotlib(viz_obj, sizing_mode='stretch_width', height=400, tight=True)
+    elif hasattr(viz_obj, 'save') and hasattr(viz_obj, '_repr_html_'): # Folium/Altair
+        viz_pane = pn.pane.plot.Folium(viz_obj, sizing_mode='stretch_width', height=400)
+    else:
+        # Fallback/Generic (HoloViews, Bokeh, etc.)
+        viz_pane = pn.panel(viz_obj, sizing_mode='stretch_width')
+else:
+    viz_pane = pn.pane.Markdown("No visualization generated.")
+                """
+                # Add common imports just in case the generated code needs them
+                imports.extend([
+                    "import matplotlib.pyplot as plt",
+                    "import plotly.express as px",
+                    "import plotly.graph_objects as go",
+                    "import altair as alt"
+                ])
+        else:
+            viz_pane = "viz_pane = pn.pane.Markdown('No visualization requested.')"
+            viz_code = viz_pane
+
+        imports = "\n".join(sorted(list(set(imports))))
+
+        # 4. Generate Full Script
+        return f"""
+{imports}
+pn.extension('tabulator', 'vega', 'plotly', 'katex', design='bootstrap')
+
+# --- Data Loading ---
+@pn.cache
+def load_data():
+    raw_json = '{data_str}'
+    try:
+        data = json.loads(raw_json)
+        return pd.DataFrame(data)
+    except Exception:
+        return pd.DataFrame()
+
+df = load_data()
+
+# --- Visualizations ---
+{viz_code}
+
+# --- Layout Components ---
+title = pn.pane.Markdown(f"# 🤖 AI Analysis Report\\n**Query:** `{query}`", sizing_mode='stretch_width')
+
+explanation_pane = pn.pane.Markdown(
+    f\"\"\"{explanation}\"\"\",
+    sizing_mode='stretch_width',
+    styles={{'padding': '10px', 'background': '#f8f9fa', 'border-radius': '5px'}}
+)
+
+data_view = pn.widgets.Tabulator(
+    df,
+    pagination='remote',
+    page_size=10,
+    sizing_mode='stretch_width',
+    theme='bootstrap',
+)
+
+# --- Dashboard Template ---
+template = pn.template.FastListTemplate(
+    title='AI-Parrot Dashboard',
+    sidebar=[
+        pn.pane.Markdown("## 📊 Data Summary"),
+        pn.indicators.Number(name='Total Rows', value=df.shape[0] if not df.empty else 0, format='{{value}}'),
+        pn.indicators.Number(name='Total Columns', value=df.shape[1] if not df.empty else 0, format='{{value}}'),
+        pn.layout.Divider(),
+        pn.pane.Markdown("### Columns"),
+        pn.pane.DataFrame(pd.DataFrame(df.columns, columns=['Name']), height=300, sizing_mode='stretch_width') if not df.empty else ""
+    ],
+    main=[
+        pn.Row(title),
+        pn.Row(
+            pn.Column("### 📝 Analysis", explanation_pane, sizing_mode='stretch_width'),
+            pn.Column("### 📈 Visualization", viz_pane, sizing_mode='stretch_width')
+        ),
+        pn.Row("### 🗃️ Source Data", data_view)
+    ],
+    accent_base_color="#2E86C1",
+    header_background="#2E86C1",
+)
+
+if __name__.startswith("bokeh"):
+    template.servable()
+"""

parrot/outputs/formats/generators/streamlit.py

@@ -0,0 +1,86 @@
+import json
+from .abstract import AbstractAppGenerator
+
+class StreamlitGenerator(AbstractAppGenerator):
+    """Generates a single-file Streamlit application."""
+
+    def generate(self) -> str:
+        # Serialize data for embedding
+        data_str = "[]"
+        if not self.payload["data"].empty:
+            data_str = self.payload["data"].to_json(orient="records")
+
+        # Sanitize strings
+        explanation = self.payload["explanation"].replace('"""', "\\\"\\\"\\\"")
+        query = self.payload["input"].replace('"', '\\"')
+        # Dynamic Code Injection
+        code_section = ""
+        if code_snippet := self.payload["code"]:
+            if isinstance(code_snippet, (dict, list)):
+                # JSON Chart (Vega/Altair)
+                code_section = f"""
+st.subheader("📊 Generated Visualization")
+spec = {json.dumps(code_snippet)}
+st.vega_lite_chart(data=df, spec=spec, use_container_width=True)
+                """
+            elif isinstance(code_snippet, str):
+                # Python Code
+                # We wrap it to ensure it uses the local 'df' and 'st' context
+                code_section = f"""
+    st.subheader("📊 Analysis Visualization")
+    with st.container():
+        # Injected Code Execution
+        try:
+            {self._indent_code(code_snippet)}
+        except Exception as e:
+            st.error(f"Error rendering visualization: {{e}}")
+            st.code('''{code_snippet}''', language='python')
+                """
+
+        return f"""
+import streamlit as st
+import pandas as pd
+import json
+import altair as alt
+import plotly.express as px
+import matplotlib.pyplot as plt
+
+st.set_page_config(page_title="Agent Analysis", layout="wide")
+
+@st.cache_data
+def load_data():
+    try:
+        return pd.DataFrame(json.loads('{data_str}'))
+    except:
+        return pd.DataFrame()
+
+df = load_data()
+
+st.title("🤖 Analysis Report")
+st.markdown(f"**Query:** {query}")
+st.divider()
+
+col1, col2 = st.columns([2, 1])
+with col1:
+    st.subheader("📝 Findings")
+    st.markdown(\"\"\"{explanation}\"\"\")
+
+with col2:
+    st.subheader("🔢 Data Stats")
+    if not df.empty:
+        st.dataframe(df.describe().T, height=300)
+    else:
+        st.info("No data available")
+
+st.divider()
+if not df.empty:
+    with st.expander("🗃️ Source Data", expanded=True):
+        st.dataframe(df, use_container_width=True)
+
+{code_section}
+"""
+
+    def _indent_code(self, code: str, spaces: int = 8) -> str:
+        """Helper to indent injected code correctly."""
+        indentation = " " * spaces
+        return "\n".join(f"{indentation}{line}" for line in code.splitlines())

parrot/outputs/formats/generators/terminal.py

@@ -0,0 +1,63 @@
+from typing import Any
+import json
+try:
+    from rich.console import Console, Group
+    from rich.panel import Panel
+    from rich.markdown import Markdown
+    from rich.table import Table
+    from rich.layout import Layout
+    from rich.syntax import Syntax
+    RICH_AVAILABLE = True
+except ImportError:
+    RICH_AVAILABLE = False
+from .abstract import AbstractAppGenerator
+
+
+class TerminalGenerator(AbstractAppGenerator):
+    """Generates a Rich Console Dashboard."""
+
+    def generate(self) -> Any:
+        if not RICH_AVAILABLE:
+            return f"Query: {self.payload['input']}\n\n{self.payload['explanation']}"
+
+        # 1. Header
+        header = Panel(
+            f"[bold blue]Query:[/bold blue] {self.payload['input']}",
+            title="🤖 AI Agent Analysis",
+            border_style="green"
+        )
+
+        # 2. Explanation (Markdown)
+        explanation = Panel(
+            Markdown(self.payload["explanation"]),
+            title="📝 Analysis",
+            border_style="blue"
+        )
+
+        # 3. Data Table
+        df = self.payload["data"]
+        if not df.empty:
+            table = Table(show_header=True, header_style="bold magenta")
+            # Limit to first 5 columns and 10 rows for terminal readability
+            show_cols = df.columns[:5]
+            for col in show_cols:
+                table.add_column(str(col))
+
+            for _, row in df.head(10).iterrows():
+                table.add_row(*[str(item) for item in row])
+
+            data_panel = Panel(table, title=f"🔢 Data Preview ({len(df)} rows)", border_style="yellow")
+        else:
+            data_panel = Panel("No structured data returned.", title="🔢 Data", border_style="yellow")
+
+        # 4. Code View
+        if code_content := self.payload["code"]:
+            if isinstance(code_content, (dict, list)):
+                syntax = Syntax(json.dumps(code_content, indent=2), "json", theme="monokai")
+            else:
+                syntax = Syntax(code_content, "python", theme="monokai", line_numbers=True)
+
+            code_panel = Panel(syntax, title="📊 Generated Code", border_style="cyan")
+            return Group(header, explanation, data_panel, code_panel)
+
+        return Group(header, explanation, data_panel)