skill-seekers 2.7.3__py3-none-any.whl

skill_seekers/cli/ai_enhancer.py

@@ -0,0 +1,310 @@
+#!/usr/bin/env python3
+"""
+AI Enhancement Module for Pattern Detection and Test Examples
+
+Enhances C3.1 (Pattern Detection) and C3.2 (Test Example Extraction) with AI analysis.
+
+Features:
+- Explains why patterns were detected
+- Suggests improvements and identifies issues
+- Recommends related patterns
+- Adds context to test examples
+- Groups related examples into tutorials
+- Identifies best practices
+
+Credits:
+- Uses Claude AI (Anthropic) for analysis
+- Graceful degradation if API unavailable
+"""
+
+import logging
+import os
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AIAnalysis:
+    """AI analysis result for patterns or examples"""
+
+    explanation: str
+    issues: list[str]
+    recommendations: list[str]
+    related_items: list[str]  # Related patterns or examples
+    best_practices: list[str]
+    confidence_boost: float  # -0.2 to +0.2 adjustment to confidence
+
+
+class AIEnhancer:
+    """Base class for AI enhancement"""
+
+    def __init__(self, api_key: str | None = None, enabled: bool = True, mode: str = "auto"):
+        """
+        Initialize AI enhancer.
+
+        Args:
+            api_key: Anthropic API key (uses ANTHROPIC_API_KEY env if None)
+            enabled: Enable AI enhancement (default: True)
+            mode: Enhancement mode - "auto" (default), "api", or "local"
+                  - "auto": Use API if key available, otherwise disable
+                  - "api": Force API mode (fails if no key)
+                  - "local": Use Claude Code local mode (opens terminal)
+        """
+        self.enabled = enabled
+        self.mode = mode
+        self.api_key = api_key or os.environ.get("ANTHROPIC_API_KEY")
+        self.client = None
+
+        # Determine actual mode
+        if mode == "auto":
+            if self.api_key:
+                self.mode = "api"
+            else:
+                # For now, disable if no API key
+                # LOCAL mode for batch processing is complex
+                self.mode = "disabled"
+                self.enabled = False
+                logger.info("ℹ️  AI enhancement disabled (no API key found)")
+                logger.info(
+                    "   Set ANTHROPIC_API_KEY to enable, or use 'skill-seekers enhance' for SKILL.md"
+                )
+                return
+
+        if self.mode == "api" and self.enabled:
+            try:
+                import anthropic
+
+                self.client = anthropic.Anthropic(api_key=self.api_key)
+                logger.info("✅ AI enhancement enabled (using Claude API)")
+            except ImportError:
+                logger.warning("⚠️  anthropic package not installed. AI enhancement disabled.")
+                logger.warning("   Install with: pip install anthropic")
+                self.enabled = False
+            except Exception as e:
+                logger.warning(f"⚠️  Failed to initialize AI client: {e}")
+                self.enabled = False
+        elif self.mode == "local":
+            # LOCAL mode requires Claude Code to be available
+            # For patterns/examples, this is less practical than API mode
+            logger.info("ℹ️  LOCAL mode not yet supported for pattern/example enhancement")
+            logger.info(
+                "   Use API mode (set ANTHROPIC_API_KEY) or 'skill-seekers enhance' for SKILL.md"
+            )
+            self.enabled = False
+
+    def _call_claude(self, prompt: str, max_tokens: int = 1000) -> str | None:
+        """Call Claude API with error handling"""
+        if not self.client:
+            return None
+
+        try:
+            response = self.client.messages.create(
+                model="claude-sonnet-4-20250514",
+                max_tokens=max_tokens,
+                messages=[{"role": "user", "content": prompt}],
+            )
+            return response.content[0].text
+        except Exception as e:
+            logger.warning(f"⚠️  AI API call failed: {e}")
+            return None
+
+
+class PatternEnhancer(AIEnhancer):
+    """Enhance design pattern detection with AI analysis"""
+
+    def enhance_patterns(self, patterns: list[dict]) -> list[dict]:
+        """
+        Enhance detected patterns with AI analysis.
+
+        Args:
+            patterns: List of detected pattern instances
+
+        Returns:
+            Enhanced patterns with AI analysis
+        """
+        if not self.enabled or not patterns:
+            return patterns
+
+        logger.info(f"🤖 Enhancing {len(patterns)} detected patterns with AI...")
+
+        # Batch patterns to minimize API calls (max 5 per batch)
+        batch_size = 5
+        enhanced = []
+
+        for i in range(0, len(patterns), batch_size):
+            batch = patterns[i : i + batch_size]
+            batch_results = self._enhance_pattern_batch(batch)
+            enhanced.extend(batch_results)
+
+        logger.info(f"✅ Enhanced {len(enhanced)} patterns")
+        return enhanced
+
+    def _enhance_pattern_batch(self, patterns: list[dict]) -> list[dict]:
+        """Enhance a batch of patterns"""
+        # Prepare prompt
+        pattern_descriptions = []
+        for idx, p in enumerate(patterns):
+            desc = f"{idx + 1}. {p['pattern_type']} in {p.get('class_name', 'unknown')}"
+            desc += f"\n   Evidence: {', '.join(p.get('evidence', []))}"
+            pattern_descriptions.append(desc)
+
+        prompt = f"""Analyze these detected design patterns and provide insights:
+
+{chr(10).join(pattern_descriptions)}
+
+For EACH pattern, provide (in JSON format):
+1. "explanation": Brief why this pattern was detected (1-2 sentences)
+2. "issues": List of potential issues or anti-patterns (if any)
+3. "recommendations": Suggestions for improvement (if any)
+4. "related_patterns": Other patterns that might be relevant
+5. "confidence_boost": Confidence adjustment from -0.2 to +0.2 based on evidence quality
+
+Format as JSON array matching input order. Be concise and actionable.
+"""
+
+        response = self._call_claude(prompt, max_tokens=2000)
+
+        if not response:
+            # Return patterns unchanged if API fails
+            return patterns
+
+        try:
+            import json
+
+            analyses = json.loads(response)
+
+            # Merge AI analysis into patterns
+            for idx, pattern in enumerate(patterns):
+                if idx < len(analyses):
+                    analysis = analyses[idx]
+                    pattern["ai_analysis"] = {
+                        "explanation": analysis.get("explanation", ""),
+                        "issues": analysis.get("issues", []),
+                        "recommendations": analysis.get("recommendations", []),
+                        "related_patterns": analysis.get("related_patterns", []),
+                        "confidence_boost": analysis.get("confidence_boost", 0.0),
+                    }
+
+                    # Adjust confidence
+                    boost = analysis.get("confidence_boost", 0.0)
+                    if -0.2 <= boost <= 0.2:
+                        pattern["confidence"] = min(1.0, max(0.0, pattern["confidence"] + boost))
+
+            return patterns
+
+        except json.JSONDecodeError:
+            logger.warning("⚠️  Failed to parse AI response, returning patterns unchanged")
+            return patterns
+        except Exception as e:
+            logger.warning(f"⚠️  Error processing AI analysis: {e}")
+            return patterns
+
+
+class TestExampleEnhancer(AIEnhancer):
+    """Enhance test examples with AI analysis"""
+
+    def enhance_examples(self, examples: list[dict]) -> list[dict]:
+        """
+        Enhance test examples with AI context and explanations.
+
+        Args:
+            examples: List of extracted test examples
+
+        Returns:
+            Enhanced examples with AI analysis
+        """
+        if not self.enabled or not examples:
+            return examples
+
+        logger.info(f"🤖 Enhancing {len(examples)} test examples with AI...")
+
+        # Batch examples to minimize API calls
+        batch_size = 5
+        enhanced = []
+
+        for i in range(0, len(examples), batch_size):
+            batch = examples[i : i + batch_size]
+            batch_results = self._enhance_example_batch(batch)
+            enhanced.extend(batch_results)
+
+        logger.info(f"✅ Enhanced {len(enhanced)} examples")
+        return enhanced
+
+    def _enhance_example_batch(self, examples: list[dict]) -> list[dict]:
+        """Enhance a batch of examples"""
+        # Prepare prompt
+        example_descriptions = []
+        for idx, ex in enumerate(examples):
+            desc = f"{idx + 1}. {ex.get('category', 'unknown')} - {ex.get('test_name', 'unknown')}"
+            desc += f"\n   Code: {ex.get('code', '')[:100]}..."
+            if ex.get("expected_behavior"):
+                desc += f"\n   Expected: {ex['expected_behavior']}"
+            example_descriptions.append(desc)
+
+        prompt = f"""Analyze these test examples and provide educational context:
+
+{chr(10).join(example_descriptions)}
+
+For EACH example, provide (in JSON format):
+1. "explanation": What this example demonstrates (1-2 sentences, beginner-friendly)
+2. "best_practices": List of best practices shown in this example
+3. "common_mistakes": Common mistakes this example helps avoid
+4. "related_examples": Related test scenarios or patterns
+5. "tutorial_group": Suggested tutorial category (e.g., "User Authentication", "Database Operations")
+
+Format as JSON array matching input order. Focus on educational value.
+"""
+
+        response = self._call_claude(prompt, max_tokens=2000)
+
+        if not response:
+            return examples
+
+        try:
+            import json
+
+            analyses = json.loads(response)
+
+            # Merge AI analysis into examples
+            for idx, example in enumerate(examples):
+                if idx < len(analyses):
+                    analysis = analyses[idx]
+                    example["ai_analysis"] = {
+                        "explanation": analysis.get("explanation", ""),
+                        "best_practices": analysis.get("best_practices", []),
+                        "common_mistakes": analysis.get("common_mistakes", []),
+                        "related_examples": analysis.get("related_examples", []),
+                        "tutorial_group": analysis.get("tutorial_group", ""),
+                    }
+
+            return examples
+
+        except json.JSONDecodeError:
+            logger.warning("⚠️  Failed to parse AI response, returning examples unchanged")
+            return examples
+        except Exception as e:
+            logger.warning(f"⚠️  Error processing AI analysis: {e}")
+            return examples
+
+    def generate_tutorials(self, examples: list[dict]) -> dict[str, list[dict]]:
+        """
+        Group enhanced examples into tutorial sections.
+
+        Args:
+            examples: Enhanced examples with AI analysis
+
+        Returns:
+            Dictionary mapping tutorial groups to examples
+        """
+        tutorials = {}
+
+        for example in examples:
+            ai_analysis = example.get("ai_analysis", {})
+            group = ai_analysis.get("tutorial_group", "Miscellaneous")
+
+            if group not in tutorials:
+                tutorials[group] = []
+            tutorials[group].append(example)
+
+        return tutorials

skill_seekers/cli/api_reference_builder.py

@@ -0,0 +1,373 @@
+#!/usr/bin/env python3
+"""
+API Reference Builder
+
+Generates markdown API documentation from code analysis results.
+Supports Python, JavaScript/TypeScript, and C++.
+
+Output Format:
+- One .md file per analyzed source file
+- Organized by: Classes → Methods, then standalone Functions
+- Includes: Signatures, parameters, return types, docstrings
+
+Usage:
+    from skill_seekers.cli.api_reference_builder import APIReferenceBuilder
+
+    builder = APIReferenceBuilder(code_analysis_results)
+    builder.build_reference(output_dir)
+"""
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+class APIReferenceBuilder:
+    """
+    Builds markdown API reference from code analysis results.
+
+    Processes code analysis data and generates well-formatted markdown
+    documentation for each analyzed source file.
+    """
+
+    def __init__(self, code_analysis: dict[str, Any]):
+        """
+        Initialize builder with code analysis results.
+
+        Args:
+            code_analysis: Dictionary containing analyzed files and their code structures.
+                          Expected format: {'files': [{'file': 'path', 'classes': [...], 'functions': [...]}]}
+        """
+        self.code_analysis = code_analysis
+        self.files_data = code_analysis.get("files", [])
+
+    def build_reference(self, output_dir: Path) -> dict[str, Path]:
+        """
+        Generate markdown files for each analyzed source file.
+
+        Args:
+            output_dir: Directory to save generated markdown files
+
+        Returns:
+            Dictionary mapping source file paths to generated markdown file paths
+        """
+        output_dir = Path(output_dir)
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        generated_files = {}
+
+        for file_data in self.files_data:
+            source_file = file_data.get("file", "unknown")
+            language = file_data.get("language", "Unknown")
+
+            # Skip files with no analysis
+            if not file_data.get("classes") and not file_data.get("functions"):
+                continue
+
+            # Generate markdown content
+            markdown_content = self._generate_file_reference(file_data, source_file, language)
+
+            # Determine output filename
+            output_filename = self._get_output_filename(source_file)
+            output_path = output_dir / output_filename
+
+            # Write markdown file
+            output_path.write_text(markdown_content, encoding="utf-8")
+            generated_files[source_file] = output_path
+
+        return generated_files
+
+    def _get_output_filename(self, source_file: str) -> str:
+        """
+        Generate output filename from source file path.
+
+        Args:
+            source_file: Path to source file
+
+        Returns:
+            Safe filename for markdown output
+        """
+        # Get base filename
+        basename = Path(source_file).name
+
+        # Replace extension with .md
+        name_without_ext = basename.rsplit(".", 1)[0] if "." in basename else basename
+        return f"{name_without_ext}.md"
+
+    def _generate_file_reference(
+        self, file_data: dict[str, Any], source_file: str, language: str
+    ) -> str:
+        """
+        Generate complete markdown reference for a single file.
+
+        Args:
+            file_data: Analysis data for the file
+            source_file: Path to source file
+            language: Programming language
+
+        Returns:
+            Complete markdown content
+        """
+        lines = []
+
+        # Header
+        filename = Path(source_file).name
+        lines.append(f"# API Reference: {filename}\n")
+        lines.append(f"**Language**: {language}\n")
+        lines.append(f"**Source**: `{source_file}`\n")
+        lines.append("---\n")
+
+        # Classes section
+        classes = file_data.get("classes", [])
+        if classes:
+            lines.append("## Classes\n")
+            for cls in classes:
+                lines.append(self._format_class(cls))
+                lines.append("\n")
+
+        # Functions section
+        functions = file_data.get("functions", [])
+        if functions:
+            lines.append("## Functions\n")
+            for func in functions:
+                lines.append(self._format_function(func))
+                lines.append("\n")
+
+        return "\n".join(lines)
+
+    def _format_class(self, class_sig: dict[str, Any]) -> str:
+        """
+        Format class signature as markdown.
+
+        Args:
+            class_sig: Class signature dictionary
+
+        Returns:
+            Formatted markdown for class
+        """
+        lines = []
+
+        # Class name
+        class_name = class_sig.get("name", "Unknown")
+        lines.append(f"### {class_name}\n")
+
+        # Docstring
+        docstring = class_sig.get("docstring")
+        if docstring:
+            lines.append(f"{docstring}\n")
+
+        # Inheritance
+        base_classes = class_sig.get("base_classes", [])
+        if base_classes:
+            bases_str = ", ".join(base_classes)
+            lines.append(f"**Inherits from**: {bases_str}\n")
+        else:
+            lines.append("**Inherits from**: (none)\n")
+
+        # Methods
+        methods = class_sig.get("methods", [])
+        if methods:
+            lines.append("#### Methods\n")
+            for method in methods:
+                lines.append(self._format_method(method))
+                lines.append("")
+
+        return "\n".join(lines)
+
+    def _format_method(self, method_sig: dict[str, Any]) -> str:
+        """
+        Format method signature as markdown.
+
+        Args:
+            method_sig: Method signature dictionary
+
+        Returns:
+            Formatted markdown for method
+        """
+        lines = []
+
+        # Method signature
+        signature = self._build_signature(method_sig)
+        lines.append(f"##### {signature}\n")
+
+        # Docstring
+        docstring = method_sig.get("docstring")
+        if docstring:
+            lines.append(f"{docstring}\n")
+
+        # Decorators
+        decorators = method_sig.get("decorators", [])
+        if decorators:
+            dec_str = ", ".join(f"`@{d}`" for d in decorators)
+            lines.append(f"**Decorators**: {dec_str}\n")
+
+        # Parameters table
+        params = method_sig.get("parameters", [])
+        if params:
+            lines.append(self._format_parameters(params))
+            lines.append("")
+
+        # Return type
+        return_type = method_sig.get("return_type")
+        if return_type:
+            lines.append(f"**Returns**: `{return_type}`\n")
+
+        return "\n".join(lines)
+
+    def _format_function(self, func_sig: dict[str, Any]) -> str:
+        """
+        Format function signature as markdown.
+
+        Args:
+            func_sig: Function signature dictionary
+
+        Returns:
+            Formatted markdown for function
+        """
+        lines = []
+
+        # Function signature
+        signature = self._build_signature(func_sig)
+        lines.append(f"### {signature}\n")
+
+        # Async indicator
+        if func_sig.get("is_async"):
+            lines.append("**Async function**\n")
+
+        # Docstring
+        docstring = func_sig.get("docstring")
+        if docstring:
+            lines.append(f"{docstring}\n")
+
+        # Parameters table
+        params = func_sig.get("parameters", [])
+        if params:
+            lines.append(self._format_parameters(params))
+            lines.append("")
+
+        # Return type
+        return_type = func_sig.get("return_type")
+        if return_type:
+            lines.append(f"**Returns**: `{return_type}`\n")
+        else:
+            lines.append("**Returns**: (none)\n")
+
+        return "\n".join(lines)
+
+    def _build_signature(self, sig: dict[str, Any]) -> str:
+        """
+        Build function/method signature string.
+
+        Args:
+            sig: Signature dictionary
+
+        Returns:
+            Formatted signature string
+        """
+        name = sig.get("name", "unknown")
+        params = sig.get("parameters", [])
+        return_type = sig.get("return_type")
+
+        # Build parameter list
+        param_strs = []
+        for param in params:
+            param_str = param.get("name", "")
+
+            # Add type hint if available
+            type_hint = param.get("type_hint")
+            if type_hint:
+                param_str += f": {type_hint}"
+
+            # Add default value if available
+            default = param.get("default")
+            if default:
+                param_str += f" = {default}"
+
+            param_strs.append(param_str)
+
+        params_str = ", ".join(param_strs)
+
+        # Build full signature
+        if return_type:
+            return f"{name}({params_str}) → {return_type}"
+        else:
+            return f"{name}({params_str})"
+
+    def _format_parameters(self, params: list[dict]) -> str:
+        """
+        Format parameter list as markdown table.
+
+        Args:
+            params: List of parameter dictionaries
+
+        Returns:
+            Formatted markdown table
+        """
+        if not params:
+            return ""
+
+        lines = []
+        lines.append("**Parameters**:")
+        lines.append("")
+        lines.append("| Name | Type | Default | Description |")
+        lines.append("|------|------|---------|-------------|")
+
+        for param in params:
+            name = param.get("name", "-")
+            type_hint = param.get("type_hint", "-")
+            default = param.get("default")
+
+            # Show "-" for parameters without defaults
+            default_str = default if default is not None else "-"
+
+            # For description, use empty for now (would need JSDoc/docstring parsing)
+            description = "-"
+
+            lines.append(f"| {name} | {type_hint} | {default_str} | {description} |")
+
+        return "\n".join(lines)
+
+
+def main():
+    """
+    Command-line interface for API reference generation.
+
+    Reads code analysis JSON and generates markdown API documentation.
+    """
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Generate API reference from code analysis results"
+    )
+
+    parser.add_argument("input_file", help="Code analysis JSON file")
+    parser.add_argument("output_dir", help="Output directory for markdown files")
+
+    args = parser.parse_args()
+
+    # Read code analysis
+    input_path = Path(args.input_file)
+    if not input_path.exists():
+        print(f"Error: Input file not found: {input_path}")
+        return 1
+
+    with open(input_path, encoding="utf-8") as f:
+        code_analysis = json.load(f)
+
+    # Build API reference
+    builder = APIReferenceBuilder(code_analysis)
+    generated_files = builder.build_reference(Path(args.output_dir))
+
+    # Report results
+    print(f"✅ Generated {len(generated_files)} API reference files")
+    print(f"📁 Output directory: {args.output_dir}")
+    for source, output in generated_files.items():
+        print(f"  • {output.name} (from {Path(source).name})")
+
+    return 0
+
+
+if __name__ == "__main__":
+    import sys
+
+    sys.exit(main())