empathy-framework 5.3.0__py3-none-any.whl → 5.4.0__py3-none-any.whl

empathy_os/meta_workflows/form_engine.py

@@ -1,292 +0,0 @@
-"""Socratic form engine for requirements gathering.
-
-Uses AskUserQuestion tool to interactively collect user requirements
-through structured question flows.
-
-Created: 2026-01-17
-Updated: 2026-01-18 (v4.3.0 - Real AskUserQuestion integration)
-Purpose: Interactive requirements gathering for meta-workflows
-"""
-
-import logging
-from collections.abc import Callable
-from typing import Any
-
-from empathy_os.meta_workflows.models import FormQuestion, FormResponse, FormSchema
-
-logger = logging.getLogger(__name__)
-
-# Type alias for the AskUserQuestion callback function
-AskUserQuestionCallback = Callable[[list[dict[str, Any]]], dict[str, Any]]
-
-
-class SocraticFormEngine:
-    """Engine for collecting user requirements through Socratic questioning.
-
-    Uses the AskUserQuestion tool to present forms to users and
-    collect structured responses.
-
-    The engine supports two modes:
-    1. **Interactive mode**: Provide an `ask_user_callback` to invoke the real
-       AskUserQuestion tool (e.g., when running in Claude Code context)
-    2. **Default mode**: Uses default values from questions when no callback
-       is provided (useful for testing or batch processing)
-
-    Example:
-        >>> # Interactive mode with callback
-        >>> def my_callback(questions):
-        ...     # This would invoke the real AskUserQuestion tool
-        ...     return {"q1": "user answer"}
-        >>> engine = SocraticFormEngine(ask_user_callback=my_callback)
-
-        >>> # Default mode (no interaction)
-        >>> engine = SocraticFormEngine()
-    """
-
-    def __init__(
-        self,
-        ask_user_callback: AskUserQuestionCallback | None = None,
-        use_defaults_when_no_callback: bool = True,
-    ):
-        """Initialize the Socratic form engine.
-
-        Args:
-            ask_user_callback: Optional callback function that invokes the
-                AskUserQuestion tool. When provided, enables interactive mode.
-                The callback should accept a list of question dicts and return
-                a dict mapping question IDs to user answers.
-            use_defaults_when_no_callback: If True and no callback is provided,
-                use default values from questions. If False, raise an error
-                when trying to ask questions without a callback.
-        """
-        self.responses_cache: dict[str, FormResponse] = {}
-        self._ask_user_callback = ask_user_callback
-        self._use_defaults_when_no_callback = use_defaults_when_no_callback
-
-    def ask_questions(self, form_schema: FormSchema, template_id: str) -> FormResponse:
-        """Ask all questions in the form schema and collect responses.
-
-        Args:
-            form_schema: Schema defining questions to ask
-            template_id: ID of template these questions are for
-
-        Returns:
-            FormResponse with user's answers
-
-        Raises:
-            ValueError: If form_schema is invalid
-        """
-        if not form_schema.questions:
-            logger.warning(f"Form schema for {template_id} has no questions")
-            return FormResponse(template_id=template_id, responses={})
-
-        # Batch questions (AskUserQuestion supports max 4 at once)
-        batches = form_schema.get_question_batches(batch_size=4)
-        all_responses = {}
-
-        logger.info(f"Asking {len(form_schema.questions)} questions in {len(batches)} batch(es)")
-
-        for batch_idx, batch in enumerate(batches, 1):
-            logger.debug(f"Processing batch {batch_idx}/{len(batches)}")
-
-            # Convert batch to AskUserQuestion format
-            batch_questions = self._convert_batch_to_ask_user_format(batch)
-
-            # In real usage, this would call AskUserQuestion tool
-            # For now, this is a placeholder that tests can mock
-            batch_responses = self._ask_batch(batch_questions, template_id)
-
-            # Merge responses
-            all_responses.update(batch_responses)
-
-        # Create FormResponse
-        response = FormResponse(template_id=template_id, responses=all_responses)
-
-        # Cache response
-        self.responses_cache[response.response_id] = response
-
-        logger.info(f"Collected {len(all_responses)} responses for template {template_id}")
-        return response
-
-    def _convert_batch_to_ask_user_format(self, batch: list[FormQuestion]) -> list[dict[str, Any]]:
-        """Convert a batch of FormQuestions to AskUserQuestion format.
-
-        Args:
-            batch: List of FormQuestion objects
-
-        Returns:
-            List of question dictionaries compatible with AskUserQuestion
-        """
-        return [q.to_ask_user_format() for q in batch]
-
-    def _ask_batch(self, questions: list[dict[str, Any]], template_id: str) -> dict[str, Any]:
-        """Ask a batch of questions using AskUserQuestion tool.
-
-        Args:
-            questions: Questions in AskUserQuestion format
-            template_id: Template ID for context
-
-        Returns:
-            Dictionary mapping question_id → user's answer
-
-        Raises:
-            RuntimeError: If no callback is set and use_defaults_when_no_callback
-                is False
-
-        Note:
-            When a callback is provided, invokes the real AskUserQuestion tool.
-            Otherwise, uses default values from questions or raises an error.
-        """
-        logger.debug(f"_ask_batch called with {len(questions)} questions")
-
-        # If we have a callback, use it for interactive mode
-        if self._ask_user_callback is not None:
-            try:
-                logger.info(f"Invoking AskUserQuestion callback for {len(questions)} questions")
-                result = self._ask_user_callback(questions)
-                logger.debug(f"Received {len(result)} responses from callback")
-                return result
-            except Exception as e:
-                logger.error(f"AskUserQuestion callback failed: {e}")
-                if self._use_defaults_when_no_callback:
-                    logger.warning("Falling back to default values")
-                    return self._get_defaults_from_questions(questions)
-                raise RuntimeError(f"AskUserQuestion callback failed: {e}") from e
-
-        # No callback - use defaults or raise error
-        if self._use_defaults_when_no_callback:
-            logger.debug("No callback provided, using default values")
-            return self._get_defaults_from_questions(questions)
-
-        raise RuntimeError(
-            "No AskUserQuestion callback provided and use_defaults_when_no_callback=False. "
-            "Either provide a callback or set use_defaults_when_no_callback=True."
-        )
-
-    def _get_defaults_from_questions(self, questions: list[dict[str, Any]]) -> dict[str, Any]:
-        """Extract default values from question definitions.
-
-        Args:
-            questions: Questions in AskUserQuestion format
-
-        Returns:
-            Dictionary mapping question_id → default value
-        """
-        defaults = {}
-        for q in questions:
-            # Get question identifier - prefer question_id for agent rule matching
-            key = q.get("question_id", q.get("header", q.get("question", "unknown")))
-
-            # Check for explicit default value first
-            if "default" in q and q["default"]:
-                defaults[key] = q["default"]
-                logger.debug(f"Default for '{key}': {defaults[key]} (explicit)")
-                continue
-
-            # Get default from options (first option is typically recommended)
-            options = q.get("options", [])
-            if options:
-                # Use first option's label as default
-                first_option = options[0]
-                if isinstance(first_option, dict):
-                    defaults[key] = first_option.get("label", "")
-                else:
-                    defaults[key] = str(first_option)
-            else:
-                defaults[key] = ""
-
-            logger.debug(f"Default for '{key}': {defaults[key]} (from options)")
-
-        return defaults
-
-    def set_callback(self, callback: AskUserQuestionCallback | None) -> None:
-        """Set or update the AskUserQuestion callback.
-
-        Args:
-            callback: The callback function to use, or None to disable
-        """
-        self._ask_user_callback = callback
-        logger.debug(f"AskUserQuestion callback {'set' if callback else 'cleared'}")
-
-    def get_cached_response(self, response_id: str) -> FormResponse | None:
-        """Retrieve a cached response by ID.
-
-        Args:
-            response_id: ID of response to retrieve
-
-        Returns:
-            FormResponse if found, None otherwise
-        """
-        return self.responses_cache.get(response_id)
-
-    def clear_cache(self) -> None:
-        """Clear the response cache."""
-        self.responses_cache.clear()
-        logger.debug("Response cache cleared")
-
-
-# =============================================================================
-# Helper functions for converting between formats
-# =============================================================================
-
-
-def convert_ask_user_response_to_form_response(
-    ask_user_result: dict[str, Any], template_id: str
-) -> FormResponse:
-    """Convert AskUserQuestion tool result to FormResponse.
-
-    Args:
-        ask_user_result: Result from AskUserQuestion tool
-        template_id: Template ID
-
-    Returns:
-        FormResponse object
-
-    Example:
-        >>> result = {"q1": "Answer 1", "q2": ["Option A", "Option B"]}
-        >>> response = convert_ask_user_response_to_form_response(result, "test")
-        >>> response.get("q1")
-        'Answer 1'
-    """
-    return FormResponse(template_id=template_id, responses=ask_user_result)
-
-
-def create_header_from_question(question: FormQuestion) -> str:
-    """Create a short header for a question (max 12 chars for AskUserQuestion).
-
-    Args:
-        question: FormQuestion to create header for
-
-    Returns:
-        Short header string (≤12 chars)
-
-    Example:
-        >>> q = FormQuestion(id="has_tests", text="Do you have tests?", type=QuestionType.BOOLEAN)
-        >>> create_header_from_question(q)
-        'Tests'
-    """
-    # Extract key words from question text
-    text = question.text.lower()
-
-    # Common patterns
-    if "test" in text:
-        return "Tests"
-    elif "coverage" in text:
-        return "Coverage"
-    elif "version" in text:
-        return "Version"
-    elif "publish" in text:
-        return "Publishing"
-    elif "quality" in text:
-        return "Quality"
-    elif "security" in text:
-        return "Security"
-    elif "name" in text:
-        return "Name"
-    elif "changelog" in text:
-        return "Changelog"
-    elif "git" in text:
-        return "Git"
-
-    # Fallback: use question ID (truncated to 12 chars)
-    return question.id[:12].title()

empathy_os/meta_workflows/intent_detector.py

@@ -1,409 +0,0 @@
-"""Intent detection for automatic agent team creation.
-
-Analyzes user requests and suggests appropriate meta-workflow templates.
-
-Created: 2026-01-18
-Purpose: Enable natural discovery of agent teams based on user intent
-"""
-
-import logging
-import re
-from dataclasses import dataclass, field
-from typing import Any
-
-from empathy_os.meta_workflows.builtin_templates import BUILTIN_TEMPLATES
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass
-class IntentMatch:
-    """A detected intent match with confidence score.
-
-    Attributes:
-        template_id: ID of matching template
-        template_name: Human-readable name
-        confidence: Match confidence (0.0 to 1.0)
-        matched_keywords: Keywords that triggered the match
-        description: What this template does
-    """
-
-    template_id: str
-    template_name: str
-    confidence: float
-    matched_keywords: list[str] = field(default_factory=list)
-    description: str = ""
-
-
-# Intent patterns for each template
-INTENT_PATTERNS = {
-    "release-prep": {
-        "keywords": [
-            "release",
-            "deploy",
-            "publish",
-            "ship",
-            "launch",
-            "ready",
-            "readiness",
-            "checklist",
-            "preparation",
-            "security scan",
-            "vulnerability",
-            "audit",
-            "production",
-            "go live",
-            "version bump",
-            "pre-release",
-            "before release",
-            "quality check",
-            "code review",
-            "final check",
-        ],
-        "phrases": [
-            r"ready (for|to) (release|deploy|publish)",
-            r"(check|verify|validate) (for )?release",
-            r"(prepare|preparing) (for )?(a )?(release|deployment)",
-            r"security (scan|check|audit)",
-            r"(is|are) (we|it) ready",
-            r"release (check|prep|preparation)",
-            r"prepare for (a )?release",
-            r"need to release",
-            r"before (we )?(release|deploy|publish|ship|launch)",
-            r"quality (check|audit|review)",
-            r"ready to (ship|deploy|launch|publish)",
-        ],
-        "weight": 1.0,
-    },
-    "test-coverage-boost": {
-        "keywords": [
-            "test coverage",
-            "coverage",
-            "tests",
-            "testing",
-            "unit tests",
-            "improve coverage",
-            "boost coverage",
-            "generate tests",
-            "missing tests",
-            "coverage gap",
-            "80%",
-            "90%",
-            "percent coverage",
-            "more tests",
-            "add tests",
-            "write tests",
-            "create tests",
-            "batch tests",
-            "batch generation",
-            "parallel tests",
-            "bulk tests",
-            "mass test generation",
-            "rapidly generate",
-            "quickly boost",
-        ],
-        "phrases": [
-            r"(improve|increase|boost) (test )?coverage",
-            r"(generate|create|write|add) (more )?tests",
-            r"coverage (is )?(too )?low",
-            r"(find|identify) (coverage )?gaps",
-            r"(need|want) more tests",
-            r"test generation",
-            r"my (test )?coverage",
-            r"improve.*coverage",
-            r"(batch|bulk|mass) (test )?generation",
-            r"generate tests (in )?(batch|parallel)",
-            r"(rapidly|quickly) (generate|boost|improve)",
-            r"parallel test (generation|creation)",
-        ],
-        "weight": 1.0,
-    },
-    "test-maintenance": {
-        "keywords": [
-            "test maintenance",
-            "stale tests",
-            "outdated tests",
-            "flaky tests",
-            "test health",
-            "test cleanup",
-            "test lifecycle",
-            "maintain tests",
-            "fix tests",
-            "broken tests",
-            "failing tests",
-        ],
-        "phrases": [
-            r"(fix|update|maintain) tests",
-            r"(stale|outdated|old) tests",
-            r"test (maintenance|health|cleanup)",
-            r"tests (are )?(failing|flaky|broken)",
-            r"clean up tests",
-            r"test.*broken",
-            r"failing test",
-        ],
-        "weight": 1.0,
-    },
-    "manage-docs": {
-        "keywords": [
-            "documentation",
-            "docs",
-            "docstrings",
-            "readme",
-            "api docs",
-            "missing docs",
-            "update docs",
-            "document",
-            "documenting",
-            "undocumented",
-            "up to date",
-            "sync",
-            "stale docs",
-            "outdated docs",
-        ],
-        "phrases": [
-            r"(update|improve|fix|add) (the )?doc(s|umentation)?",
-            r"missing (doc)?strings",
-            r"(check|verify) documentation",
-            r"(readme|api docs?) (is )?(outdated|stale|missing)",
-            r"document (the )?(code|api|functions)",
-            r"documentation.*(up to date|sync|current|fresh)",
-            r"(is|are).*(doc|documentation).*(up to date|current|sync)",
-            r"doc.*(stale|outdated|old)",
-        ],
-        "weight": 1.0,
-    },
-    "auth-strategy": {
-        "keywords": [
-            "authentication",
-            "auth",
-            "auth strategy",
-            "auth mode",
-            "api key",
-            "subscription",
-            "configure auth",
-            "setup auth",
-            "auth status",
-            "check auth",
-            "recommend auth",
-            "authentication mode",
-            "api mode",
-            "subscription mode",
-            "cost optimization",
-            "auth config",
-        ],
-        "phrases": [
-            r"(setup|configure) auth(entication)?",
-            r"auth(entication)? (setup|config|status|mode)",
-            r"(check|show|view) auth(entication)? (status|config|mode)",
-            r"(what|which) auth(entication)? mode",
-            r"recommend auth(entication)?",
-            r"(api|subscription) (key|mode)",
-            r"switch (to )?(api|subscription)",
-            r"auth(entication)? (for|with)",
-            r"reset auth(entication)?",
-        ],
-        "weight": 1.0,
-    },
-    "agent-dashboard": {
-        "keywords": [
-            "dashboard",
-            "agent dashboard",
-            "coordination dashboard",
-            "monitor agents",
-            "view agents",
-            "agent status",
-            "heartbeat",
-            "agent coordination",
-            "multi-agent",
-            "orchestration",
-            "agent metrics",
-            "agent health",
-            "show dashboard",
-            "open dashboard",
-        ],
-        "phrases": [
-            r"(show|view|open|display) (the )?dashboard",
-            r"agent (dashboard|coordination|status|health)",
-            r"(monitor|track|watch) agents",
-            r"coordination dashboard",
-            r"(multi.?agent|orchestration) (dashboard|monitor)",
-            r"dashboard (for )?agents",
-            r"agent (monitoring|metrics|heartbeat)",
-        ],
-        "weight": 1.0,
-    },
-}
-
-
-class IntentDetector:
-    """Detects user intent and suggests appropriate agent teams.
-
-    Uses keyword matching and phrase patterns to identify what the user
-    is trying to accomplish and maps it to available meta-workflow templates.
-    """
-
-    def __init__(self):
-        """Initialize the intent detector."""
-        self.patterns = INTENT_PATTERNS
-        self.templates = BUILTIN_TEMPLATES
-
-    def detect(self, user_input: str, threshold: float = 0.3) -> list[IntentMatch]:
-        """Detect user intent from natural language input.
-
-        Args:
-            user_input: User's natural language request
-            threshold: Minimum confidence score to include (default: 0.3)
-
-        Returns:
-            List of IntentMatch objects, sorted by confidence (highest first)
-        """
-        if not user_input or not isinstance(user_input, str):
-            return []
-
-        user_input_lower = user_input.lower().strip()
-        matches = []
-
-        for template_id, pattern_config in self.patterns.items():
-            confidence, matched_keywords = self._calculate_match_score(
-                user_input_lower, pattern_config
-            )
-
-            if confidence >= threshold:
-                template = self.templates.get(template_id)
-                matches.append(
-                    IntentMatch(
-                        template_id=template_id,
-                        template_name=template.name if template else template_id,
-                        confidence=confidence,
-                        matched_keywords=matched_keywords,
-                        description=template.description if template else "",
-                    )
-                )
-
-        # Sort by confidence (highest first)
-        matches.sort(key=lambda m: m.confidence, reverse=True)
-        return matches
-
-    def _calculate_match_score(
-        self, user_input: str, pattern_config: dict[str, Any]
-    ) -> tuple[float, list[str]]:
-        """Calculate match score for a template.
-
-        Args:
-            user_input: Lowercase user input
-            pattern_config: Pattern configuration for a template
-
-        Returns:
-            Tuple of (confidence score, list of matched keywords)
-        """
-        keywords = pattern_config.get("keywords", [])
-        phrases = pattern_config.get("phrases", [])
-        weight = pattern_config.get("weight", 1.0)
-
-        matched_keywords = []
-        keyword_score = 0.0
-        phrase_score = 0.0
-
-        # Check keyword matches
-        for keyword in keywords:
-            if keyword.lower() in user_input:
-                matched_keywords.append(keyword)
-                # Longer keywords are weighted more
-                keyword_score += len(keyword.split()) * 0.1
-
-        # Check phrase matches (more specific, higher weight)
-        for phrase in phrases:
-            if re.search(phrase, user_input, re.IGNORECASE):
-                phrase_score += 0.3
-                # Extract matched text for debugging
-                match = re.search(phrase, user_input, re.IGNORECASE)
-                if match:
-                    matched_keywords.append(f"[{match.group()}]")
-
-        # Combine scores (cap at 1.0)
-        total_score = min((keyword_score + phrase_score) * weight, 1.0)
-
-        return total_score, matched_keywords
-
-    def get_suggestion_text(self, matches: list[IntentMatch]) -> str:
-        """Generate a user-friendly suggestion message.
-
-        Args:
-            matches: List of intent matches
-
-        Returns:
-            Formatted suggestion text
-        """
-        if not matches:
-            return ""
-
-        lines = ["I detected the following agent teams that might help:\n"]
-
-        for i, match in enumerate(matches[:3], 1):  # Top 3 suggestions
-            confidence_pct = int(match.confidence * 100)
-            lines.append(f"  {i}. **{match.template_name}** ({confidence_pct}% match)")
-            lines.append(f"     {match.description}")
-            lines.append(f"     Run with: `empathy meta-workflow run {match.template_id}`")
-            lines.append("")
-
-        return "\n".join(lines)
-
-    def should_suggest(self, user_input: str, min_confidence: float = 0.4) -> bool:
-        """Check if we should suggest agent teams for this input.
-
-        Args:
-            user_input: User's input text
-            min_confidence: Minimum confidence to trigger suggestion
-
-        Returns:
-            True if we should suggest agent teams
-        """
-        matches = self.detect(user_input, threshold=min_confidence)
-        return len(matches) > 0
-
-    def get_best_match(self, user_input: str) -> IntentMatch | None:
-        """Get the best matching template for user input.
-
-        Args:
-            user_input: User's natural language request
-
-        Returns:
-            Best matching IntentMatch or None if no good match
-        """
-        matches = self.detect(user_input, threshold=0.4)
-        return matches[0] if matches else None
-
-
-def detect_and_suggest(user_input: str) -> str:
-    """Convenience function to detect intent and return suggestion.
-
-    Args:
-        user_input: User's natural language request
-
-    Returns:
-        Suggestion text or empty string if no matches
-    """
-    detector = IntentDetector()
-    matches = detector.detect(user_input)
-    return detector.get_suggestion_text(matches)
-
-
-def auto_detect_template(user_input: str) -> str | None:
-    """Auto-detect the best template for a user request.
-
-    Args:
-        user_input: User's natural language request
-
-    Returns:
-        Template ID if confident match, None otherwise
-    """
-    detector = IntentDetector()
-    match = detector.get_best_match(user_input)
-
-    if match and match.confidence >= 0.6:
-        logger.info(
-            f"Auto-detected template: {match.template_id} (confidence: {match.confidence:.0%})"
-        )
-        return match.template_id
-
-    return None