@mc1global/opencode-jarvis 0.12.0 → 0.13.1

package/src/infrastructure/rag/cli_metadata_loader.py

@@ -0,0 +1,456 @@
+#!/usr/bin/env python3
+"""CLI Metadata Loader - Specialized chunking for YAML CLI metadata files.
+
+This loader generates specialized chunks optimized for RAG retrieval of CLI commands:
+1. Intent chunks: Map natural language queries to commands
+2. Command overview chunks: High-level command information
+3. Option detail chunks: One chunk per option with validation rules
+4. Error troubleshooting chunks: One chunk per common error
+
+SOLID Compliance:
+- SRP: Only loads and chunks CLI metadata YAML files
+- OCP: Extensible via additional chunk generators
+- LSP: N/A (no inheritance)
+- ISP: Minimal interface focused on CLI metadata
+- DIP: Depends on YAML abstraction, not implementation details
+
+DDD Compliance:
+- Bounded Context: CLI Command Intelligence
+- Ubiquitous Language: intent, command, option, troubleshooting
+"""
+
+import logging
+from pathlib import Path
+from typing import Dict, List, Optional
+
+import yaml
+
+logger = logging.getLogger(__name__)
+
+
+class CLIMetadataLoader:
+    """
+    Load YAML CLI metadata files and generate specialized chunks for RAG indexing.
+
+    Generates 4 chunk types:
+    1. Intent: Maps natural language to commands ("criar card" → card.create)
+    2. Command Overview: High-level command info for discovery
+    3. Option Details: Per-option chunks with validation rules
+    4. Error Troubleshooting: Per-error chunks with solutions
+
+    Usage:
+        loader = CLIMetadataLoader("metadata/cli/")
+        all_chunks = loader.load_all_metadata()
+    """
+
+    def __init__(self, metadata_dir: str) -> None:
+        """
+        Initialize CLI Metadata Loader.
+
+        Args:
+            metadata_dir: Directory containing YAML CLI metadata files
+        """
+        self.metadata_dir = Path(metadata_dir)
+        if not self.metadata_dir.exists():
+            raise ValueError(f"Metadata directory not found: {metadata_dir}")
+
+        logger.info(f"CLIMetadataLoader initialized for: {metadata_dir}")
+
+    def load_yaml(self, yaml_path: str) -> dict:
+        """
+        Load and parse YAML file.
+
+        Args:
+            yaml_path: Path to YAML file
+
+        Returns:
+            Parsed YAML data as dictionary
+
+        Raises:
+            FileNotFoundError: If YAML file doesn't exist
+            yaml.YAMLError: If YAML is malformed
+        """
+        path = Path(yaml_path)
+        if not path.exists():
+            raise FileNotFoundError(f"YAML file not found: {yaml_path}")
+
+        try:
+            with open(path, 'r', encoding='utf-8') as f:
+                data = yaml.safe_load(f)
+                if not data:
+                    logger.warning(f"Empty YAML file: {yaml_path}")
+                    return {}
+                return data
+        except yaml.YAMLError as e:
+            logger.error(f"Failed to parse YAML {yaml_path}: {e}")
+            raise
+
+    def generate_chunks(self, yaml_data: dict, source_file: str) -> List[Dict]:
+        """
+        Generate all chunk types from YAML data.
+
+        Args:
+            yaml_data: Parsed YAML metadata
+            source_file: Source YAML filename for reference
+
+        Returns:
+            List of chunk dictionaries with 'content' and 'metadata' keys
+        """
+        if not yaml_data:
+            logger.warning(f"No data to chunk from: {source_file}")
+            return []
+
+        chunks = []
+
+        # 1. Generate intent chunk (1 per file)
+        intent_chunk = self._chunk_intent(yaml_data, source_file)
+        if intent_chunk:
+            chunks.append(intent_chunk)
+
+        # 2. Generate command overview chunks (1 per command)
+        commands = yaml_data.get('commands', [])
+        for command_data in commands:
+            cmd_chunk = self._chunk_command(command_data, source_file)
+            if cmd_chunk:
+                chunks.append(cmd_chunk)
+
+            # 3. Generate option detail chunks (1 per option)
+            opt_chunks = self._chunk_options(command_data, source_file)
+            chunks.extend(opt_chunks)
+
+        # 4. Generate troubleshooting chunks (1 per error)
+        error_chunks = self._chunk_troubleshooting(yaml_data, source_file)
+        chunks.extend(error_chunks)
+
+        logger.info(f"Generated {len(chunks)} chunks from {source_file}")
+        return chunks
+
+    def _chunk_intent(self, yaml_data: dict, source: str) -> Optional[Dict]:
+        """
+        Generate intent mapping chunk.
+
+        Maps natural language intents and keywords to script/command.
+        Use case: "quero criar card" → finds kanban_manager card.create
+
+        Args:
+            yaml_data: Full YAML data
+            source: Source filename
+
+        Returns:
+            Intent chunk dictionary or None
+        """
+        metadata_section = yaml_data.get('metadata', {})
+        if not metadata_section:
+            return None
+
+        script_name = metadata_section.get('script_name', '')
+        description = metadata_section.get('description', '')
+        intents = metadata_section.get('intents', [])
+        keywords = metadata_section.get('keywords', [])
+
+        if not (script_name and intents):
+            return None
+
+        # Build rich content for embedding
+        intent_lines = [
+            f"Script: {script_name}",
+            f"Description: {description}",
+            "",
+            "User Intents (natural language queries):",
+        ]
+        for intent in intents:
+            intent_lines.append(f"  - {intent}")
+
+        if keywords:
+            intent_lines.append("")
+            intent_lines.append("Keywords:")
+            intent_lines.append(f"  {', '.join(keywords)}")
+
+        content = "\n".join(intent_lines)
+
+        return {
+            'content': content,
+            'metadata': {
+                'source_file': source,
+                'chunk_type': 'intent',
+                'script_name': script_name,
+                'section': 'metadata.intents',
+            }
+        }
+
+    def _chunk_command(self, command_data: dict, source: str) -> Optional[Dict]:
+        """
+        Generate command overview chunk.
+
+        High-level command information for discovery.
+        Use case: "what commands are available for cards"
+
+        Args:
+            command_data: Single command from 'commands' list
+            source: Source filename
+
+        Returns:
+            Command overview chunk or None
+        """
+        command_name = command_data.get('name', '')
+        description = command_data.get('description', '')
+        intent = command_data.get('intent', '')
+
+        if not command_name:
+            return None
+
+        # Build overview content
+        content_lines = [
+            f"Command: {command_name}",
+            f"Description: {description}",
+            f"Intent: {intent}",
+            "",
+            "Options:",
+        ]
+
+        # List all options
+        options = command_data.get('options', [])
+        for opt in options:
+            flag = opt.get('flag', '')
+            opt_desc = opt.get('description', '')
+            required = opt.get('required', False)
+            req_marker = "[REQUIRED]" if required else "[OPTIONAL]"
+            content_lines.append(f"  {flag} {req_marker}: {opt_desc}")
+
+        content = "\n".join(content_lines)
+
+        return {
+            'content': content,
+            'metadata': {
+                'source_file': source,
+                'chunk_type': 'command',
+                'command_name': command_name,
+                'section': f'commands.{command_name}',
+            }
+        }
+
+    def _chunk_options(self, command_data: dict, source: str) -> List[Dict]:
+        """
+        Generate one chunk per option with detailed validation rules.
+
+        Critical: Includes invalid_values to prevent common errors.
+        Use case: "priority high medium low" → returns priority option details
+
+        Args:
+            command_data: Single command data
+            source: Source filename
+
+        Returns:
+            List of option detail chunks
+        """
+        chunks = []
+        command_name = command_data.get('name', '')
+        options = command_data.get('options', [])
+
+        for opt in options:
+            chunk = self._build_option_chunk(opt, command_name, source)
+            if chunk:
+                chunks.append(chunk)
+
+        return chunks
+
+    def _build_option_chunk(
+        self,
+        opt: dict,
+        command_name: str,
+        source: str
+    ) -> Optional[Dict]:
+        """
+        Build a single option chunk.
+
+        Extracted to reduce complexity of _chunk_options.
+
+        Args:
+            opt: Option dictionary
+            command_name: Parent command name
+            source: Source filename
+
+        Returns:
+            Option chunk or None if flag missing
+        """
+        flag = opt.get('flag', '')
+        if not flag:
+            return None
+
+        opt_type = opt.get('type', '')
+        description = opt.get('description', '')
+        required = opt.get('required', False)
+
+        # Build detailed option content
+        content_lines = [
+            f"Option: {flag}",
+            f"Command: {command_name}",
+            f"Type: {opt_type}",
+            f"Required: {'Yes' if required else 'No'}",
+            f"Description: {description}",
+        ]
+
+        # Add optional sections
+        self._add_default_section(opt, content_lines)
+        self._add_choices_section(opt, content_lines)
+        self._add_invalid_values_section(opt, content_lines)
+        self._add_validation_section(opt, content_lines)
+        self._add_examples_section(opt, content_lines)
+
+        content = "\n".join(content_lines)
+
+        return {
+            'content': content,
+            'metadata': {
+                'source_file': source,
+                'chunk_type': 'option',
+                'command_name': command_name,
+                'option_flag': flag,
+                'section': f'commands.{command_name}.options.{flag}',
+            }
+        }
+
+    def _add_default_section(self, opt: dict, content_lines: List[str]) -> None:
+        """Add default value section to option content."""
+        default = opt.get('default')
+        if default:
+            content_lines.append(f"Default: {default}")
+
+    def _add_choices_section(self, opt: dict, content_lines: List[str]) -> None:
+        """Add valid choices section to option content."""
+        choices = opt.get('choices', [])
+        if choices:
+            content_lines.append("")
+            content_lines.append("Valid values:")
+            for choice in choices:
+                content_lines.append(f"  - {choice}")
+
+    def _add_invalid_values_section(
+        self,
+        opt: dict,
+        content_lines: List[str]
+    ) -> None:
+        """Add invalid values section to option content (critical for RAG)."""
+        invalid_values = opt.get('invalid_values', [])
+        if invalid_values:
+            content_lines.append("")
+            content_lines.append("Invalid values (DO NOT USE):")
+            for invalid in invalid_values:
+                content_lines.append(f"  - {invalid}")
+
+    def _add_validation_section(self, opt: dict, content_lines: List[str]) -> None:
+        """Add validation rule section to option content."""
+        validation = opt.get('validation', {})
+        if validation:
+            val_rule = validation.get('rule', '')
+            val_msg = validation.get('message', '')
+            content_lines.append("")
+            content_lines.append(f"Validation: {val_rule}")
+            content_lines.append(f"Error message: {val_msg}")
+
+    def _add_examples_section(self, opt: dict, content_lines: List[str]) -> None:
+        """Add examples section to option content."""
+        examples = opt.get('examples', [])
+        if examples:
+            content_lines.append("")
+            content_lines.append("Examples:")
+            for ex in examples:
+                ex_value = ex.get('value', '')
+                ex_context = ex.get('context', '')
+                content_lines.append(f"  - {ex_value} ({ex_context})")
+
+    def _chunk_troubleshooting(
+        self,
+        yaml_data: dict,
+        source: str
+    ) -> List[Dict]:
+        """
+        Generate one chunk per troubleshooting entry.
+
+        Use case: "erro priority critical" → returns troubleshooting for that error
+
+        Args:
+            yaml_data: Full YAML data
+            source: Source filename
+
+        Returns:
+            List of troubleshooting chunks
+        """
+        chunks = []
+        troubleshooting = yaml_data.get('troubleshooting', [])
+
+        for entry in troubleshooting:
+            problem = entry.get('problem', '')
+            cause = entry.get('cause', '')
+            solution = entry.get('solution', '')
+            query_patterns = entry.get('query_patterns', [])
+
+            if not problem:
+                continue
+
+            # Build troubleshooting content
+            content_lines = [
+                f"Error: {problem}",
+                f"Cause: {cause}",
+                f"Solution: {solution}",
+            ]
+
+            if query_patterns:
+                content_lines.append("")
+                content_lines.append("Related queries:")
+                for pattern in query_patterns:
+                    content_lines.append(f"  - {pattern}")
+
+            content = "\n".join(content_lines)
+
+            chunks.append({
+                'content': content,
+                'metadata': {
+                    'source_file': source,
+                    'chunk_type': 'troubleshooting',
+                    'error_type': problem[:50],  # First 50 chars for identification
+                    'section': 'troubleshooting',
+                }
+            })
+
+        return chunks
+
+    def load_all_metadata(self) -> List[Dict]:
+        """
+        Load all YAML files from metadata_dir and generate chunks.
+
+        Returns:
+            List of all chunks from all YAML files
+
+        Raises:
+            RuntimeError: If no YAML files found or all files failed
+        """
+        yaml_files = list(self.metadata_dir.glob("*.yaml"))
+        yaml_files.extend(self.metadata_dir.glob("*.yml"))
+
+        if not yaml_files:
+            raise RuntimeError(f"No YAML files found in {self.metadata_dir}")
+
+        all_chunks = []
+        successful_files = 0
+
+        for yaml_file in yaml_files:
+            try:
+                yaml_data = self.load_yaml(str(yaml_file))
+                chunks = self.generate_chunks(yaml_data, yaml_file.name)
+                all_chunks.extend(chunks)
+                successful_files += 1
+            except Exception as e:
+                logger.error(f"Failed to process {yaml_file.name}: {e}")
+                continue
+
+        if successful_files == 0:
+            raise RuntimeError(
+                f"All YAML files failed to load from {self.metadata_dir}"
+            )
+
+        logger.info(
+            f"Loaded {len(all_chunks)} chunks from "
+            f"{successful_files}/{len(yaml_files)} files"
+        )
+        return all_chunks