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

parrot/outputs/formatter.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+import sys
+from typing import Any, Optional, Tuple
+from .formats import get_renderer, get_output_prompt, has_system_prompt
+from ..models.outputs import OutputMode
+from ..template.engine import TemplateEngine
+
+
+class OutputFormatter:
+    """
+    Formatter for AI responses supporting multiple output modes.
+    """
+
+    def __init__(self, template_engine: Optional[TemplateEngine] = None):
+        """
+        Initialize the OutputFormatter.
+
+        Args:
+            template_engine: Optional TemplateEngine instance for template-based rendering.
+            If not provided, a new one will be created when needed.
+        """
+        self._is_ipython = self._detect_ipython()
+        self._is_notebook = self._detect_notebook()
+        self._environment = self._detect_environment()
+        self._renderers = {}
+        self._template_engine = template_engine
+
+    def _detect_environment(self) -> str:
+        if self._is_ipython:
+            return "jupyter" if self._is_notebook else "ipython"
+        return "terminal"
+
+    def _detect_ipython(self) -> bool:
+        try:
+            if "IPython" not in sys.modules:
+                return False
+            from IPython import get_ipython
+            return get_ipython() is not None
+        except (ImportError, NameError):
+            return False
+
+    def _detect_notebook(self) -> bool:
+        try:
+            from IPython import get_ipython
+            ipython = get_ipython()
+            return ipython is not None and "IPKernelApp" in ipython.config
+        except Exception:
+            return False
+
+    def _get_renderer(self, mode: OutputMode):
+        """
+        Get or create a renderer instance for the specified output mode.
+
+        Args:
+            mode: OutputMode enum value
+
+        Returns:
+            Renderer instance for the given mode
+        """
+        if mode not in self._renderers:
+            renderer_cls = get_renderer(mode)
+            # Special handling for TEMPLATE_REPORT renderer to pass TemplateEngine
+            if mode == OutputMode.TEMPLATE_REPORT:
+                # Lazy initialize TemplateEngine if not provided
+                if self._template_engine is None:
+                    self._template_engine = TemplateEngine()
+                self._renderers[mode] = renderer_cls(
+                    template_engine=self._template_engine
+                )
+            else:
+                self._renderers[mode] = renderer_cls()
+        return self._renderers[mode]
+
+    def get_system_prompt(self, mode: OutputMode) -> Optional[str]:
+        """
+        Get the system prompt for a given output mode.
+
+        Args:
+            mode: OutputMode enum value
+
+        Returns:
+            System prompt string or None if mode has no specific prompt
+        """
+        print(f"Getting system prompt for mode: {mode}")
+        return get_output_prompt(mode)
+
+    def has_system_prompt(self, mode: OutputMode) -> bool:
+        """
+        Check if an output mode has a registered system prompt.
+
+        Args:
+            mode: OutputMode enum value
+
+        Returns:
+            True if mode has a system prompt
+        """
+        return has_system_prompt(mode)
+
+    async def format(
+        self,
+        mode: OutputMode,
+        data: Any,
+        **kwargs
+    ) -> Tuple[str, Optional[str]]:
+        """
+        Format output based on mode
+
+        Returns:
+            Tuple[str, Optional[str]]: (content, wrapped_content)
+            - content: main formatted output
+            - wrapped_content: optional wrapped version (e.g., HTML)
+        """
+        if mode == OutputMode.DEFAULT:
+            return data, None
+
+        renderer = self._get_renderer(mode)
+        render_method = getattr(renderer, "render_async", renderer.render)
+
+        # Call renderer and get tuple response
+        return await render_method(
+            data,
+            environment=self._environment,
+            is_ipython=self._is_ipython,
+            is_notebook=self._is_notebook,
+            **kwargs,
+        )
+
+    def add_template(self, name: str, content: str) -> None:
+        """
+        Add an in-memory template for use with TEMPLATE_REPORT mode.
+
+        Args:
+            name: Template name (e.g., 'report.html', 'summary.md')
+            content: Jinja2 template content
+
+        Example:
+            formatter = OutputFormatter()
+            formatter.add_template('report.html', '<h1>{{ title }}</h1>')
+            result = await formatter.format_async(
+                OutputMode.TEMPLATE_REPORT,
+                {"title": "My Report"},
+                template="report.html"
+            )
+        """
+        # Ensure TemplateEngine is initialized
+        if self._template_engine is None:
+            self._template_engine = TemplateEngine()
+
+        # Get or create the TEMPLATE_REPORT renderer to add the template
+        renderer = self._get_renderer(OutputMode.TEMPLATE_REPORT)
+        if hasattr(renderer, 'add_template'):
+            renderer.add_template(name, content)

parrot/outputs/templates/__init__.py

@@ -0,0 +1,95 @@
+from typing import Dict, Any, List, Optional
+from pathlib import Path
+from jinja2 import Environment, FileSystemLoader, Template
+from pydantic import BaseModel
+
+class TemplateSection(BaseModel):
+    """Defines a fillable section in the template."""
+    name: str
+    description: str
+    content_type: str  # 'text', 'table', 'chart', 'image', 'list'
+    required: bool = True
+    example: Optional[str] = None
+
+class ReportTemplate(BaseModel):
+    """Defines a report template structure."""
+    name: str
+    description: str
+    template_path: Path
+    sections: List[TemplateSection]
+    css_path: Optional[Path] = None
+
+    def get_section_prompts(self) -> Dict[str, str]:
+        """Generate prompts for LLM to fill each section."""
+        prompts = {}
+        for section in self.sections:
+            prompt = (
+                f"Generate {section.content_type} content for the "
+                f"'{section.name}' section.\n"
+                f"Description: {section.description}\n"
+            )
+            if section.example:
+                prompt += f"Example format:\n{section.example}\n"
+            prompts[section.name] = prompt
+        return prompts
+
+class TemplateRegistry:
+    """Registry of available templates."""
+
+    def __init__(self, templates_dir: Path):
+        self.templates_dir = templates_dir
+        self.env = Environment(
+            loader=FileSystemLoader(templates_dir)
+        )
+        self._templates: Dict[str, ReportTemplate] = {}
+
+    def register(self, template: ReportTemplate):
+        """Register a template."""
+        self._templates[template.name] = template
+
+    def get(self, name: str) -> ReportTemplate:
+        """Get a template by name."""
+        return self._templates.get(name)
+
+    def list(self) -> List[str]:
+        """List available templates."""
+        return list(self._templates.keys())
+
+# Built-in templates
+EXECUTIVE_SUMMARY_TEMPLATE = ReportTemplate(
+    name="executive_summary",
+    description="Executive summary report with key findings",
+    template_path=Path("templates/executive_summary.html"),
+    sections=[
+        TemplateSection(
+            name="title",
+            description="Report title",
+            content_type="text"
+        ),
+        TemplateSection(
+            name="executive_summary",
+            description="High-level overview (2-3 paragraphs)",
+            content_type="text"
+        ),
+        TemplateSection(
+            name="key_findings",
+            description="Bullet points of main findings",
+            content_type="list"
+        ),
+        TemplateSection(
+            name="data_table",
+            description="Supporting data in table format",
+            content_type="table"
+        ),
+        TemplateSection(
+            name="visualization",
+            description="Chart showing trends",
+            content_type="chart"
+        ),
+        TemplateSection(
+            name="recommendations",
+            description="Actionable recommendations",
+            content_type="list"
+        )
+    ]
+)

parrot/pipelines/abstract.py

@@ -0,0 +1,210 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional, List, Tuple, Union
+from pathlib import Path
+import io
+from PIL import (
+    Image,
+    ImageDraw,
+    ImageFont,
+    ImageEnhance,
+    ImageOps
+)
+from navconfig.logging import logging
+from datamodel.parsers.json import JSONContent  # pylint: disable=E0611
+from ..clients.factory import SUPPORTED_CLIENTS
+from ..clients.google import GoogleGenAIClient, GoogleModel
+
+
+logging.getLogger('pytesseract').setLevel(logging.WARNING)
+
+class AbstractPipeline(ABC):
+    """Abstract base class for all pipelines."""
+    def __init__(
+        self,
+        llm: Any = None,
+        llm_provider: str = "google",
+        llm_model: Optional[str] = None,
+        **kwargs: Any
+    ):
+        """
+        Initialize the 3-step pipeline
+
+        Args:
+            llm_provider: LLM provider for identification
+            llm_model: Specific LLM model
+            api_key: API key
+            detection_model: Object detection model to use
+        """
+        self.llm = llm
+        self.llm_provider = None
+        self.logger = logging.getLogger(f'parrot.pipelines.{self.__class__.__name__}')
+        self._json = JSONContent()
+        if not llm:
+            self.llm_provider = llm_provider.lower()
+            self.llm = self._get_llm(
+                llm_provider,
+                llm_model,
+                **kwargs
+            )
+        else:
+            self.llm_provider = llm.client_name.lower()
+        # Ensure a Google Client for multi-modal capabilities:
+        self.roi_client = GoogleGenAIClient(
+            model=GoogleModel.GEMINI_2_5_FLASH,
+            temperature=0.0,
+            max_retries=2,
+            timeout=20
+        )
+
+    def _get_llm(
+        self,
+        provider: str,
+        model: Optional[str] = None,
+        **kwargs: Any
+    ) -> Any:
+        """
+        Get the LLM client based on provider and model
+
+        Args:
+            provider: LLM provider name
+            model: Specific model to use
+            **kwargs: Additional parameters for client initialization
+
+        Returns:
+            Initialized LLM client
+        """
+        if provider not in SUPPORTED_CLIENTS:
+            raise ValueError(
+                f"Unsupported LLM provider: {provider}"
+            )
+
+        client_class = SUPPORTED_CLIENTS[provider]
+        client = client_class(model=model, **kwargs)
+        self.llm_provider = client.client_name.lower()
+        return client
+
+    def open_image(self, image_path: Union[Path, Image.Image]) -> Image.Image:
+        """Open an image from a file path."""
+        try:
+            if isinstance(image_path, (str, Path)):
+                img = Image.open(str(image_path))
+            else:
+                img = image_path
+            if img.mode != "RGB":
+                img = img.convert("RGB")
+            img = self._enhance_image(img)
+            self.logger.debug(
+                f"Opened image {image_path} with size {img.size} and mode {img.mode}"
+            )
+            return img
+        except Exception as e:
+            self.logger.error(f"Error opening image {image_path}: {e}")
+            raise
+
+    def _clamp(self, w, h, x1, y1, x2, y2):
+        x1, x2 = int(max(0, min(w - 1, min(x1, x2)))), int(max(0, min(w - 1, max(x1, x2))))
+        y1, y2 = int(max(0, min(h - 1, min(y1, y2)))), int(max(0, min(h - 1, max(y1, y2))))
+        return x1, y1, x2, y2
+
+    def _save_detections(
+        self,
+        pil_image: Image.Image,
+        poster_bounds: Tuple[int, int, int, int],
+        detections: List[dict],
+        save_path: str,
+        poster_label: str = 'poster_panel',
+    ) -> None:
+        """Save debug image showing poster detection results"""
+        try:
+            debug_img = pil_image.copy()
+            draw = ImageDraw.Draw(debug_img)
+            # draw the detections:
+            for det in detections:
+                label = det.label
+                conf = float(det.confidence or 0.0)
+                bbox = det.bbox
+                x1 = int(bbox.x1 * debug_img.width)
+                y1 = int(bbox.y1 * debug_img.height)
+                x2 = int(bbox.x2 * debug_img.width)
+                y2 = int(bbox.y2 * debug_img.height)
+                x1, y1, x2, y2 = self._clamp(debug_img.width, debug_img.height, x1, y1, x2, y2)
+
+                color = (255, 165, 0) if label == poster_label else (0, 255, 255)
+                draw.rectangle(
+                    [(x1, y1), (x2, y2)],
+                    outline=color,
+                    width=3
+                )
+                draw.text(
+                    (x1, y1 - 20),
+                    f"{label} {conf:.2f}",
+                    fill=color
+                )
+
+            # Draw final poster bounds in bright green
+            x1, y1, x2, y2 = poster_bounds
+            draw.rectangle(
+                [(x1, y1), (x2, y2)],
+                outline=(0, 255, 0),
+                width=4
+            )
+            draw.text(
+                (x1, y1 - 45),
+                f"POSTER: {x2-x1}x{y2-y1}",
+                fill=(0, 255, 0)
+            )
+
+            # Save debug image
+            Path(save_path).parent.mkdir(parents=True, exist_ok=True)
+            debug_img.save(save_path, quality=95)
+            self.logger.debug(
+                f"Saved poster debug image to {save_path}"
+            )
+
+        except Exception as e:
+            self.logger.error(f"Failed to save debug image: {e}")
+
+    def _enhance_image(
+        self,
+        pil_img: "Image.Image",
+        brightness: float = 1.10,
+        contrast: float = 1.20
+    ) -> "Image.Image":
+        """
+        Enhances a PIL image by adjusting brightness and contrast.
+        This generic utility can be used by any pipeline subclass.
+        """
+        self.logger.debug("Applying generic image enhancement...")
+        # Brightness/contrast + autocontrast; tweak if needed
+        pil = ImageEnhance.Brightness(pil_img).enhance(brightness)
+        pil = ImageEnhance.Contrast(pil).enhance(contrast)
+        pil = ImageOps.autocontrast(pil)
+        return pil
+
+    def _downscale_image(self, img: Image.Image, max_side=1024, quality=82) -> Image.Image:
+        if img.mode != "RGB":
+            img = img.convert("RGB")
+        w, h = img.size
+        s = max(w, h)
+        if s > max_side:
+            scale = max_side / float(s)
+            img = img.resize((int(w * scale), int(h * scale)), Image.Resampling.LANCZOS)
+        # (Optional) strip metadata by re-encoding
+        bio = io.BytesIO()
+        img.save(bio, format="JPEG", quality=quality, optimize=True)
+        bio.seek(0)
+        return Image.open(bio)
+
+    @abstractmethod
+    async def run(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        """
+        Run the pipeline with the provided arguments
+
+        Args:
+            *args: Positional arguments for the pipeline
+            **kwargs: Keyword arguments for the pipeline
+
+        Returns:
+            Dictionary with results of the pipeline execution
+        """
+        raise NotImplementedError("Subclasses must implement this method")

parrot/pipelines/detector.py

@@ -0,0 +1,124 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional, List, Tuple
+import cv2
+import torch
+from PIL import Image
+from transformers import CLIPProcessor, CLIPModel
+from navconfig.logging import logging
+try:
+    from ultralytics import YOLO  # yolo12m works with this API
+except Exception:
+    YOLO = None
+from ..models.detections import DetectionBox
+
+class AbstractDetector(ABC):
+    """Abstract base class for all detectors."""
+    def __init__(
+        self,
+        yolo_model: str = "yolo12l.pt",
+        conf: float = 0.15,
+        iou: float = 0.5,
+        device: str = "cuda" if torch.cuda.is_available() else "cpu",
+        **kwargs
+    ):
+        if isinstance(yolo_model, str):
+            assert YOLO is not None, "ultralytics is required"
+            self.yolo = YOLO(yolo_model)
+        else:
+            self.yolo = yolo_model
+        self.conf = conf
+        self.iou = iou
+        self.device = device
+        self.logger = logging.getLogger(
+            f'parrot.pipelines.{self.__class__.__name__}'
+        )
+        self._define_clip()
+
+    # ----------------------- enhancement & CLIP -------------------------------
+    def _embed_image(self, path: Optional[str]):
+        if not path:
+            return None
+        im = Image.open(path).convert("RGB")
+        with torch.no_grad():
+            inputs = self.proc(images=im, return_tensors="pt").to(self.device)
+            feat = self.clip.get_image_features(**inputs)
+            feat = feat / feat.norm(dim=-1, keepdim=True)
+        return feat
+
+    def _define_clip(self):
+        self.clip = CLIPModel.from_pretrained("openai/clip-vit-base-patch32").to(self.device)
+        self.proc = CLIPProcessor.from_pretrained("openai/clip-vit-base-patch32")
+
+    def _iou(self, a: DetectionBox, b: DetectionBox) -> float:
+        ix1, iy1 = max(a.x1, b.x1), max(a.y1, b.y1)
+        ix2, iy2 = min(a.x2, b.x2), min(a.y2, b.y2)
+        iw, ih = max(0, ix2 - ix1), max(0, iy2 - iy1)
+        inter = iw * ih
+        if inter <= 0:
+            return 0.0
+        ua = a.area + b.area - inter
+        return inter / float(max(1, ua))
+
+    def _normalized_y(self, b, h: int) -> Tuple[float, float, float]:
+        y1n, y2n = b.y1 / h, b.y2 / h
+        yc = 0.5 * (y1n + y2n)
+        return y1n, yc, y2n
+
+    def _iou_box_tuple(self, d: DetectionBox, box: tuple[int,int,int,int]) -> float:
+        ax1, ay1, ax2, ay2 = box
+        ix1, iy1 = max(d.x1, ax1), max(d.y1, ay1)
+        ix2, iy2 = min(d.x2, ax2), min(d.y2, ay2)
+        if ix2 <= ix1 or iy2 <= iy1:
+            return 0.0
+        inter = (ix2 - ix1) * (iy2 - iy1)
+        return inter / float(d.area + (ax2-ax1)*(ay2-ay1) - inter + 1e-6)
+
+    def _coerce_bbox(self, bbox, W, H):
+        if bbox is None:
+            return None
+        if isinstance(bbox, (list, tuple)) and len(bbox) == 4:
+            x1, y1, x2, y2 = map(float, bbox)
+        elif isinstance(bbox, dict):
+            if {"x1","y1","x2","y2"} <= bbox.keys():
+                x1, y1, x2, y2 = map(float, (bbox["x1"], bbox["y1"], bbox["x2"], bbox["y2"]))
+            elif {"x","y","w","h"} <= bbox.keys():
+                x1, y1 = float(bbox["x"]), float(bbox["y"])
+                x2, y2 = x1 + float(bbox["w"]), y1 + float(bbox["h"])
+            else:
+                return None
+        else:
+            return None
+        def to_px(v, M):
+            return int(round(v * M)) if v <= 1.5 else int(round(v))
+        x1, y1, x2, y2 = to_px(x1, W), to_px(y1, H), to_px(x2, W), to_px(y2, H)
+        if x2 < x1:
+            x1, x2 = x2, x1
+        if y2 < y1:
+            y1, y2 = y2, y1
+        x1 = max(0, min(W-1, x1))
+        x2 = max(0, min(W-1, x2))
+        y1 = max(0, min(H-1, y1))
+        y2 = max(0, min(H-1, y2))
+        if (x2-x1) < 4 or (y2-y1) < 4:
+            return None
+        return (x1, y1, x2, y2)
+
+    @abstractmethod
+    async def detect(
+        self,
+        image: Any,
+        image_array: Any,
+        **kwargs: Any
+    ) -> Tuple[Any, List[Any]]:
+        """
+        Abstract method for detecting objects in an image.
+
+        Args:
+            image: The input image.
+            image_array: The input image as a numpy array.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            A tuple containing the processed image and a list of detections.
+        """
+        pass

parrot/pipelines/models.py

@@ -0,0 +1,90 @@
+from typing import Optional, Dict, List, Any, Union
+from pathlib import Path
+from enum import Enum
+from PIL import Image
+from pydantic import BaseModel, Field
+from ..models.detections import (
+    PlanogramDescription,
+    PlanogramDescriptionFactory,
+)
+
+class EndcapGeometry(BaseModel):
+    """Configurable endcap geometry parameters"""
+    aspect_ratio: float = Field(default=1.35, description="Endcap width/height ratio")
+    left_margin_ratio: float = Field(default=0.01, description="Left margin as ratio of panel width")
+    right_margin_ratio: float = Field(default=0.03, description="Right margin as ratio of panel width")
+    top_margin_ratio: float = Field(default=0.02, description="Top margin as ratio of panel height")
+
+    # NEW: Additional margin controls for better shelf separation
+    bottom_margin_ratio: float = Field(default=0.05, description="Bottom margin as ratio of panel height")
+    inter_shelf_padding: float = Field(default=0.02, description="Padding between shelves as ratio of ROI height")
+
+    # ROI detection specific margins
+    width_margin_percent: float = Field(default=0.25, description="Panel width margin percentage")
+    height_margin_percent: float = Field(default=0.30, description="Panel height margin percentage")
+    top_margin_percent: float = Field(default=0.05, description="Panel top margin percentage")
+    side_margin_percent: float = Field(default=0.05, description="Panel side margin percentage")
+
+class PlanogramConfig(BaseModel):
+    """
+    Complete configuration for planogram analysis pipeline.
+    Contains planogram description, prompts, and reference images.
+    """
+    planogram_id: Optional[int] = Field(
+        default=None,
+        description="Optional unique identifier for the planogram (if any)"
+    )
+
+    config_name: str = Field(
+        default="default_planogram_config",
+        description="Name of the planogram configuration"
+    )
+
+    # Core planogram configuration
+    planogram_config: Dict[str, Any] = Field(
+        description="Planogram configuration dictionary (gets converted to PlanogramDescription)"
+    )
+
+    # ROI Detection prompt
+    roi_detection_prompt: str = Field(
+        description="Prompt for ROI detection phase (used by _find_poster method)"
+    )
+
+    # Object identification prompt
+    object_identification_prompt: str = Field(
+        description="Prompt for Phase 2 object identification (used by _identify_objects method)"
+    )
+
+    # Reference images
+    reference_images: Dict[str, Union[str, Path, Image.Image]] = Field(
+        default_factory=dict,
+        description="Reference images for object identification"
+    )
+
+    # Optional: Additional detection parameters
+    confidence_threshold: float = Field(
+        default=0.25,
+        description="YOLO detection confidence threshold"
+    )
+
+    detection_model: str = Field(
+        default="yolo11l.pt",
+        description="YOLO model to use for detection"
+    )
+
+    endcap_geometry: EndcapGeometry = Field(
+        default_factory=EndcapGeometry,
+        description="Endcap geometry and margin configuration"
+    )
+
+    class Config:
+        """Pydantic configuration."""
+        arbitrary_types_allowed = True
+
+    def get_planogram_description(self) -> PlanogramDescription:
+        """
+        Load and validate a planogram description from a configuration dictionary.
+        Uses PlanogramDescriptionFactory to parse and validate the config.
+        """
+        factory = PlanogramDescriptionFactory()
+        return factory.create_planogram_description(self.planogram_config)