attune-ai 2.0.0__py3-none-any.whl

attune/meta_workflows/form_engine.py

@@ -0,0 +1,292 @@
+"""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 attune.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()

attune/meta_workflows/intent_detector.py

@@ -0,0 +1,409 @@
+"""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 attune.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