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

parrot/pipelines/table.sql

@@ -0,0 +1,97 @@
+DROP TABLE IF EXISTS troc.planograms_configurations;
+
+CREATE TABLE troc.planograms_configurations (
+    -- Primary key
+    planogram_id SERIAL PRIMARY KEY,
+
+    -- Basic configuration info
+    config_name VARCHAR(255) NOT NULL UNIQUE,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+
+    -- Core planogram configuration (stored as JSONB for flexibility)
+    planogram_config JSONB NOT NULL,
+
+    -- Prompts (can be quite long)
+    roi_detection_prompt TEXT NOT NULL,
+    object_identification_prompt TEXT NOT NULL,
+
+    -- Reference images (stored as JSONB with paths/references, not actual image data)
+    reference_images JSONB DEFAULT '{}',
+
+    -- Detection parameters
+    confidence_threshold DECIMAL(3,2) NOT NULL DEFAULT 0.25 CHECK (confidence_threshold >= 0.0 AND confidence_threshold <= 1.0),
+    detection_model VARCHAR(100) NOT NULL DEFAULT 'yolo11l.pt',
+
+    -- EndcapGeometry fields (flattened for better queryability)
+    -- Basic geometry
+    aspect_ratio DECIMAL(4,2) NOT NULL DEFAULT 1.35,
+    left_margin_ratio DECIMAL(4,3) NOT NULL DEFAULT 0.010,
+    right_margin_ratio DECIMAL(4,3) NOT NULL DEFAULT 0.030,
+    top_margin_ratio DECIMAL(4,3) NOT NULL DEFAULT 0.020,
+    bottom_margin_ratio DECIMAL(4,3) NOT NULL DEFAULT 0.050,
+    inter_shelf_padding DECIMAL(4,3) NOT NULL DEFAULT 0.020,
+
+    -- ROI detection margins
+    width_margin_percent DECIMAL(4,3) NOT NULL DEFAULT 0.250,
+    height_margin_percent DECIMAL(4,3) NOT NULL DEFAULT 0.300,
+    top_margin_percent DECIMAL(4,3) NOT NULL DEFAULT 0.050,
+    side_margin_percent DECIMAL(4,3) NOT NULL DEFAULT 0.050,
+
+    -- Optional metadata
+    description TEXT,
+    brand VARCHAR(100),
+    program_slug VARCHAR,
+    version VARCHAR(20) DEFAULT '1.0',
+    is_active BOOLEAN DEFAULT TRUE
+);
+
+-- Indexes for better query performance
+CREATE INDEX idx_planograms_config_name ON troc.planograms_configurations(config_name);
+CREATE INDEX idx_planograms_brand ON troc.planograms_configurations(brand);
+CREATE INDEX idx_planograms_active ON troc.planograms_configurations(is_active);
+CREATE INDEX idx_planograms_created_at ON troc.planograms_configurations(created_at);
+
+-- GIN index for JSONB fields to enable efficient JSON queries
+CREATE INDEX idx_planograms_config_gin ON troc.planograms_configurations USING GIN (planogram_config);
+CREATE INDEX idx_planograms_ref_images_gin ON troc.planograms_configurations USING GIN (reference_images);
+
+-- Trigger to automatically update the updated_at timestamp
+CREATE OR REPLACE FUNCTION update_updated_at_column()
+RETURNS TRIGGER AS $$
+BEGIN
+    NEW.updated_at = CURRENT_TIMESTAMP;
+    RETURN NEW;
+END;
+$$ language 'plpgsql';
+
+CREATE TRIGGER update_planograms_configurations_updated_at
+    BEFORE UPDATE ON troc.planograms_configurations
+    FOR EACH ROW
+    EXECUTE FUNCTION update_updated_at_column();
+
+-- Comments for documentation
+COMMENT ON TABLE troc.planograms_configurations IS 'Stores planogram analysis pipeline configurations including prompts, reference images, and geometry parameters';
+COMMENT ON COLUMN troc.planograms_configurations.planogram_config IS 'Complete planogram description as JSONB (shelves, products, compliance rules, etc.)';
+COMMENT ON COLUMN troc.planograms_configurations.reference_images IS 'Reference images stored as JSONB with image paths/URLs, not binary data';
+COMMENT ON COLUMN troc.planograms_configurations.roi_detection_prompt IS 'Prompt used for ROI detection phase by _find_poster method';
+COMMENT ON COLUMN troc.planograms_configurations.object_identification_prompt IS 'Prompt used for Phase 2 object identification by _identify_objects method';
+
+-- Example insert statement
+-- INSERT INTO planograms_configurations (
+--     config_name,
+--     planogram_config,
+--     roi_detection_prompt,
+--     object_identification_prompt,
+--     reference_images,
+--     brand,
+--     description
+-- ) VALUES (
+--     'hisense_tv_display_v1',
+--     '{"brand": "Hisense", "shelves": [...]}',
+--     'Find the Hisense promotional poster...',
+--     'Identify the TV models and promotional graphics...',
+--     '{"poster_ref": "/images/hisense_poster.jpg", "u7_ref": "/images/u7_tv.jpg"}',
+--     'Hisense',
+--     'Hisense TV display configuration for retail endcaps'
+-- );

parrot/plugins/__init__.py

@@ -0,0 +1,106 @@
+import sys
+import contextlib
+from importlib import import_module
+from navconfig.logging import Logger
+from parrot.conf import PLUGINS_DIR, AGENTS_DIR
+from .importer import PluginImporter
+
+# Add plugins directory to sys.path
+# If AGENTS_DIR is already at position 0 (from parrot.conf), insert PLUGINS_DIR at position 1
+# to preserve AGENTS_DIR priority. Otherwise, insert PLUGINS_DIR at position 0.
+plugins_dir_str = str(PLUGINS_DIR)
+agents_dir_str = str(AGENTS_DIR)
+
+if plugins_dir_str not in sys.path:
+    # Check if AGENTS_DIR is at position 0
+    if sys.path and sys.path[0] == agents_dir_str:
+        # AGENTS_DIR has priority, insert PLUGINS_DIR at position 1
+        sys.path.insert(1, plugins_dir_str)
+    else:
+        # Insert PLUGINS_DIR at position 0
+        sys.path.insert(0, plugins_dir_str)
+
+# Agents Loader - maps parrot.agents to project_folder/plugins/agents/
+agents_dir = PLUGINS_DIR / "agents"
+agents_dir.mkdir(exist_ok=True)
+
+# Create __init__.py if it doesn't exist
+init_file = agents_dir / "__init__.py"
+if not init_file.exists():
+    init_file.touch()
+
+def setup_plugin_importer(package_name: str, plugin_subdir: str):
+    """
+    Configures a PluginImporter for any package to extend its search path.
+
+    This allows modules in both core package and plugins folder to be imported
+    with the same syntax.
+
+    Args:
+        package_name: Full package name (e.g., 'parrot.agents', 'parrot.tools')
+        plugin_subdir: Subdirectory name in plugins folder (e.g., 'agents', 'tools')
+
+    Example:
+        # In parrot/agents/__init__.py:
+        from parrot.plugins import setup_plugin_importer
+        setup_plugin_importer('parrot.agents', 'agents')
+
+        # Now you can do:
+        from parrot.agents import MyPluginAgent  # Works for both core and plugin agents
+    """
+    try:
+        # Path to plugin subdirectory
+        plugin_dir = PLUGINS_DIR / plugin_subdir
+
+        # Create directory if it doesn't exist
+        plugin_dir.mkdir(parents=True, exist_ok=True)
+
+        # Ensure __init__.py exists
+        init_file = plugin_dir / "__init__.py"
+        if not init_file.exists():
+            init_file.touch()
+
+        # Register the importer to extend the package search path
+        sys.meta_path.append(
+            PluginImporter(package_name, str(plugin_dir))
+        )
+
+        return True
+    except Exception:
+        # During package build, dependencies might not be available
+        # This is fine - plugins just won't be available until runtime
+        return False
+
+
+def dynamic_import_helper(package_name: str, attr_name: str):
+    """
+    Helper for __getattr__ to dynamically import plugin modules.
+
+    Args:
+        package_name: Package name (e.g., 'parrot.agents')
+        attr_name: Attribute being accessed (e.g., 'HRAgent')
+
+    Returns:
+        The imported class/module if found
+
+    Raises:
+        AttributeError: If the attribute cannot be found
+
+    Example:
+        # In parrot/agents/__init__.py:
+        def __getattr__(name):
+            from parrot.plugins import dynamic_import_helper
+            return dynamic_import_helper(__name__, name)
+    """
+    with contextlib.suppress(ImportError):
+        # Try to import as a submodule (lowercase convention)
+        module = import_module(f".{attr_name.lower()}", package_name)
+
+        # Look for a class with the original name (usually CamelCase)
+        if hasattr(module, attr_name):
+            return getattr(module, attr_name)
+
+    # If not found, raise the appropriate error
+    raise AttributeError(
+        f"module '{package_name}' has no attribute '{attr_name}'"
+    )

parrot/plugins/importer.py

@@ -0,0 +1,80 @@
+import types
+import importlib
+import importlib.util
+import importlib.abc
+from importlib.machinery import SourceFileLoader
+import os
+
+
+class PluginImporter(importlib.abc.MetaPathFinder, importlib.abc.Loader):
+    """A custom importer to load plugins from a specified directory."""
+    def __init__(self, package_name, plugins_path):
+        self.package_name = package_name
+        self.plugins_path = plugins_path
+
+    def find_spec(self, fullname, path, target=None):
+        if fullname.startswith(self.package_name):
+            # Handle submodules
+            if fullname.startswith(self.package_name + "."):
+                component_name = fullname.split(".")[-1]
+                component_path = os.path.join(self.plugins_path, f"{component_name}.py")
+
+                if os.path.exists(component_path):
+                    return importlib.util.spec_from_loader(fullname, self)
+
+        return None
+
+    def create_module(self, spec):
+        return None
+
+    def exec_module(self, module):
+        fullname = module.__name__
+
+        # Handle package __init__.py loading
+        if fullname == self.package_name:
+            init_path = os.path.join(self.plugins_path, "__init__.py")
+            if os.path.exists(init_path):
+                loader = SourceFileLoader("__init__", init_path)
+                loaded = types.ModuleType(loader.name)
+                loader.exec_module(loaded)
+                module.__dict__.update(loaded.__dict__)
+                # Append plugins_path to __path__ instead of replacing it
+                # This allows both main directory and plugins directory to coexist
+                if not hasattr(module, '__path__'):
+                    module.__path__ = []
+                if self.plugins_path not in module.__path__:
+                    module.__path__.append(self.plugins_path)
+
+        # Handle individual component files
+        else:
+            component_name = fullname.split(".")[-1]
+            component_path = os.path.join(self.plugins_path, f"{component_name}.py")
+            if os.path.exists(component_path):
+                loader = SourceFileLoader(component_name, component_path)
+                loaded = types.ModuleType(loader.name)
+                loader.exec_module(loaded)
+                module.__dict__.update(loaded.__dict__)
+
+def list_plugins(plugin_subdir: str) -> list[str]:
+    """
+    List all available plugins in a subdirectory.
+
+    Args:
+        plugin_subdir: Subdirectory name (e.g., 'agents', 'tools')
+
+    Returns:
+        List of plugin module names (without .py extension)
+    """
+    try:
+        from ..conf import PLUGINS_DIR
+        plugin_dir = PLUGINS_DIR / plugin_subdir
+
+        if not plugin_dir.exists():
+            return []
+
+        return [
+            f.stem for f in plugin_dir.glob("*.py")
+            if f.stem != "__init__"
+        ]
+    except (ImportError, Exception):
+        return []

parrot/registry/__init__.py

@@ -0,0 +1,18 @@
+from ..conf import AGENTS_DIR, PLUGINS_DIR
+from .registry import AgentRegistry, BotMetadata
+
+
+# Global default registry
+agent_registry = AgentRegistry(
+    agents_dir=AGENTS_DIR,
+    extra_agent_dirs=[PLUGINS_DIR / "agents"]
+)
+
+register_agent = agent_registry.register_bot_decorator  # type: ignore
+
+__all__ = [
+    "agent_registry",
+    "BotMetadata",
+    "register_agent",
+    "AgentRegistry"
+]