devsquad 3.6.0__py3-none-any.whl

scripts/collaboration/ai_semantic_matcher.py

@@ -0,0 +1,260 @@
+#!/usr/bin/env python3
+import json
+import hashlib
+import logging
+from typing import Dict, List, Any, Optional
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from .models import ROLE_REGISTRY, ROLE_ALIASES
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class SemanticMatchResult:
+    role_id: str
+    role_name: str
+    confidence: float
+    reasoning: str
+    matched_capabilities: List[str] = field(default_factory=list)
+    relevance_score: float = 0.0
+    explanation: str = ""
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+class AISemanticMatcher:
+    """
+    AI-powered semantic role matcher.
+
+    Uses LLM backend for deep semantic understanding of task requirements,
+    falling back to keyword matching when no LLM is available.
+
+    Workflow:
+    1. Analyze task requirements, extract key semantic info
+    2. Understand role capabilities and responsibilities
+    3. Match based on semantic similarity
+    4. Generate explainable matching results
+    """
+
+    MATCH_PROMPT_TEMPLATE = """You are an intelligent role matching expert. Analyze the following task and match the most suitable roles.
+
+## Task
+**Description**: {task_description}
+**Required capabilities**: {required_capabilities}
+
+## Available Roles
+{role_descriptions}
+
+## Requirements
+1. Analyze the core needs and key capability requirements of the task
+2. Evaluate each role's match with the task
+3. Consider the role's professional capabilities and experience
+4. Provide matching reasons and confidence scores
+
+Return the matching results in JSON format:
+{{
+    "matches": [
+        {{
+            "role_id": "role ID",
+            "role_name": "role name",
+            "confidence": 0.0-1.0,
+            "reasoning": "matching reasoning",
+            "matched_capabilities": ["matched capability list"],
+            "relevance_score": 0.0-1.0,
+            "explanation": "detailed explanation"
+        }}
+    ],
+    "best_match": "best match role ID",
+    "analysis": "overall analysis"
+}}"""
+
+    def __init__(self, llm_backend=None):
+        self.llm_backend = llm_backend
+        self.match_cache: Dict[str, SemanticMatchResult] = {}
+        self.match_history: List[Dict[str, Any]] = []
+
+    def match(
+        self,
+        task_description: str,
+        required_capabilities: List[str] = None,
+        preferred_skills: List[str] = None,
+        use_cache: bool = True,
+    ) -> List[SemanticMatchResult]:
+        """
+        Perform intelligent role matching using AI.
+
+        Args:
+            task_description: Task description text
+            required_capabilities: Required capability list
+            preferred_skills: Preferred skill list
+            use_cache: Whether to use cached results
+
+        Returns:
+            List[SemanticMatchResult]: Matched results sorted by confidence
+        """
+        cache_key = self._generate_cache_key(task_description)
+
+        if use_cache and cache_key in self.match_cache:
+            logger.info("Using cached match result")
+            return [self.match_cache[cache_key]]
+
+        roles = self._build_role_list()
+        role_descriptions = self._build_role_descriptions(roles)
+
+        if self.llm_backend:
+            try:
+                prompt = self.MATCH_PROMPT_TEMPLATE.format(
+                    task_description=task_description,
+                    required_capabilities=required_capabilities or [],
+                    role_descriptions=role_descriptions,
+                )
+                ai_response = self.llm_backend.generate(prompt)
+                results = self._parse_ai_response(ai_response, roles)
+
+                if results and use_cache:
+                    self.match_cache[cache_key] = results[0]
+
+                self._record_match(task_description, results)
+                return results
+            except Exception as e:
+                logger.warning("AI matching failed, falling back to keyword: %s", e)
+
+        results = self._keyword_match(task_description, roles)
+        self._record_match(task_description, results)
+        return results
+
+    def _build_role_list(self) -> List[Dict[str, Any]]:
+        roles = []
+        for role_id, rdef in ROLE_REGISTRY.items():
+            if rdef.status == "core":
+                roles.append({
+                    'id': role_id,
+                    'name': rdef.name,
+                    'description': rdef.description,
+                    'capabilities': rdef.keywords,
+                    'skills': rdef.keywords[:3],
+                    'keywords': rdef.keywords,
+                })
+        return roles
+
+    def _build_role_descriptions(self, roles: List[Dict[str, Any]]) -> str:
+        descriptions = []
+        for i, role in enumerate(roles, 1):
+            desc = f"{i}. **{role.get('name', 'Unknown')}** ({role.get('id', 'unknown')})\n"
+            desc += f"   - Responsibilities: {role.get('description', '')}\n"
+            desc += f"   - Capabilities: {', '.join(role.get('capabilities', []))}\n"
+            descriptions.append(desc)
+        return "\n".join(descriptions)
+
+    EN_KEYWORD_MAP = {
+        "architect": ["architecture", "design", "system", "microservice", "tech stack", "api design", "performance", "module", "interface"],
+        "product-manager": ["requirement", "prd", "user story", "product", "feature", "acceptance", "competitive", "experience"],
+        "tester": ["test", "quality", "qa", "automated", "performance test", "bug", "defect", "verification", "edge case"],
+        "solo-coder": ["implement", "develop", "code", "fix", "optimize", "refactor", "review", "best practice"],
+        "ui-designer": ["ui", "interface", "frontend", "visual", "interaction", "prototype", "ux", "accessibility"],
+        "devops": ["ci/cd", "deploy", "monitor", "infrastructure", "docker", "kubernetes", "container", "devops"],
+        "security": ["security", "vulnerability", "audit", "threat", "encryption", "auth", "owasp", "compliance"],
+    }
+
+    def _keyword_match(self, task_description: str, roles: List[Dict[str, Any]]) -> List[SemanticMatchResult]:
+        task_lower = task_description.lower()
+        results = []
+
+        for role in roles:
+            role_id = role.get('id', '')
+            keywords = role.get('keywords', [])
+            en_keywords = self.EN_KEYWORD_MAP.get(role_id, [])
+
+            cn_match = sum(1 for kw in keywords if kw.lower() in task_lower)
+            en_match = sum(1 for kw in en_keywords if kw.lower() in task_lower)
+            match_count = cn_match + en_match
+
+            if match_count > 0:
+                confidence = min(0.5 + match_count * 0.1, 0.95)
+                result = SemanticMatchResult(
+                    role_id=role_id,
+                    role_name=role.get('name', ''),
+                    confidence=confidence,
+                    reasoning=f"Keyword match: {match_count} keywords matched",
+                    matched_capabilities=role.get('capabilities', [])[:3],
+                    relevance_score=match_count / 10.0,
+                    explanation="Task requirements are highly related to this role's responsibilities",
+                )
+                results.append(result)
+
+        results.sort(key=lambda r: r.confidence, reverse=True)
+
+        if not results:
+            results.append(SemanticMatchResult(
+                role_id="solo-coder",
+                role_name="Solo Developer",
+                confidence=0.5,
+                reasoning="Default role: no specific keyword match",
+                matched_capabilities=["general development"],
+                relevance_score=0.3,
+                explanation="No specific role matched, using default developer role",
+            ))
+
+        return results
+
+    def _parse_ai_response(self, response: str, roles: List[Dict[str, Any]]) -> List[SemanticMatchResult]:
+        try:
+            if isinstance(response, str):
+                data = json.loads(response)
+            else:
+                data = response
+
+            results = []
+            for match_data in data.get('matches', []):
+                result = SemanticMatchResult(
+                    role_id=match_data.get('role_id', ''),
+                    role_name=match_data.get('role_name', ''),
+                    confidence=float(match_data.get('confidence', 0.0)),
+                    reasoning=match_data.get('reasoning', ''),
+                    matched_capabilities=match_data.get('matched_capabilities', []),
+                    relevance_score=float(match_data.get('relevance_score', 0.0)),
+                    explanation=match_data.get('explanation', ''),
+                    metadata={
+                        'best_match': data.get('best_match'),
+                        'analysis': data.get('analysis'),
+                    },
+                )
+                results.append(result)
+
+            results.sort(key=lambda r: r.confidence, reverse=True)
+            return results
+        except Exception as e:
+            logger.warning("Failed to parse AI response: %s", e)
+            return []
+
+    def _generate_cache_key(self, task_description: str) -> str:
+        content = f"{task_description}|{len(ROLE_REGISTRY)}"
+        return hashlib.md5(content.encode('utf-8')).hexdigest()
+
+    def _record_match(self, task_description: str, results: List[SemanticMatchResult]):
+        record = {
+            'task_description': task_description[:100],
+            'timestamp': datetime.now().isoformat(),
+            'results_count': len(results),
+            'top_role': results[0].role_id if results else None,
+            'top_confidence': results[0].confidence if results else 0.0,
+        }
+        self.match_history.append(record)
+
+    def get_match_history(self, limit: int = 10) -> List[Dict]:
+        return self.match_history[-limit:]
+
+    def clear_cache(self):
+        self.match_cache.clear()
+
+    def explain_match(self, result: SemanticMatchResult) -> str:
+        explanation = (
+            f"Match: {result.role_name} ({result.role_id})\n"
+            f"Confidence: {result.confidence:.1%}\n"
+            f"Relevance: {result.relevance_score:.1%}\n\n"
+            f"Reasoning:\n{result.reasoning}\n\n"
+            f"Explanation:\n{result.explanation}\n\n"
+            f"Matched capabilities: {', '.join(result.matched_capabilities) if result.matched_capabilities else 'None'}"
+        )
+        return explanation

scripts/collaboration/anchor_checker.py

@@ -0,0 +1,281 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+AnchorChecker - V3.6.0 Goal Alignment Engine
+
+Checks whether current output remains aligned with the original task goal
+at key decision points (anchor points), preventing goal drift during
+long-running Agent tasks.
+
+Design Principles:
+- No LLM calls: Pure algorithmic matching (keyword + TF-IDF)
+- Trigger only at key nodes: step complete, phase gate, conflict, direction change
+- Lightweight: <50ms per check
+- Non-blocking: Warnings written to Scratchpad, execution continues
+"""
+
+import re
+import math
+import logging
+from datetime import datetime
+from collections import Counter
+from typing import Dict, List, Optional, Any
+
+from .models import (
+    StructuredGoal, GoalItem, GoalItemStatus,
+    AnchorResult, AnchorTrigger, DriftItem, DriftSeverity,
+)
+
+logger = logging.getLogger(__name__)
+
+_GOAL_PATTERNS = [
+    (r"(?:需要|必须|shall|must|should|需要实现|需要完成|要求)[：:\s]*(.+?)(?:[。\n；;]|$)", 0.9),
+    (r"(?:目标|objective|goal|target)[：:\s]*(.+?)(?:[。\n；;]|$)", 0.85),
+    (r"(?:实现|implement|build|create|develop|design)[：:\s]*(.+?)(?:[。\n；;]|$)", 0.8),
+    (r"(?:确保|ensure|guarantee|verify)[：:\s]*(.+?)(?:[。\n；;]|$)", 0.75),
+    (r"(?:支持|support|provide|enable)[：:\s]*(.+?)(?:[。\n；;]|$)", 0.7),
+    (r"^\s*[-•*]\s*(.+?)$", 0.6),
+    (r"^\s*\d+[.、)\]]\s*(.+?)$", 0.6),
+]
+
+_STOP_WORDS = frozenset([
+    "的", "了", "在", "是", "我", "有", "和", "就", "不", "人", "都", "一", "一个",
+    "上", "也", "很", "到", "说", "要", "去", "你", "会", "着", "没有", "看", "好",
+    "自己", "这", "他", "她", "它", "们", "那", "些", "什么", "怎么", "如何",
+    "the", "a", "an", "is", "are", "was", "were", "be", "been", "being",
+    "have", "has", "had", "do", "does", "did", "will", "would", "could",
+    "should", "may", "might", "shall", "can", "need", "to", "of", "in",
+    "for", "on", "with", "at", "by", "from", "as", "into", "through",
+    "and", "or", "but", "if", "then", "else", "when", "up", "out",
+    "this", "that", "these", "those", "it", "its", "i", "me", "my",
+])
+
+
+def _tokenize(text: str) -> List[str]:
+    result = []
+    english_tokens = re.findall(r'[a-zA-Z_]{2,}', text.lower())
+    result.extend(english_tokens)
+
+    chinese_segments = re.findall(r'[\u4e00-\u9fff]+', text)
+    for seg in chinese_segments:
+        if len(seg) <= 4:
+            result.append(seg)
+        else:
+            for i in range(len(seg) - 1):
+                result.append(seg[i:i + 2])
+            for i in range(len(seg) - 3):
+                result.append(seg[i:i + 4])
+
+    filtered = []
+    for t in result:
+        if t in _STOP_WORDS:
+            continue
+        if len(t) <= 1 and not re.match(r'[\u4e00-\u9fff]', t):
+            continue
+        filtered.append(t)
+    return filtered
+
+
+def _compute_tfidf_vectors(documents: List[List[str]]) -> List[Dict[str, float]]:
+    if not documents:
+        return []
+    doc_freq = Counter()
+    for doc in documents:
+        unique_terms = set(doc)
+        for term in unique_terms:
+            doc_freq[term] += 1
+    n_docs = len(documents)
+    idf = {term: math.log(n_docs / (freq + 1)) + 1.0 for term, freq in doc_freq.items()}
+    vectors = []
+    for doc in documents:
+        tf = Counter(doc)
+        total = len(doc) if doc else 1
+        vec = {term: (count / total) * idf.get(term, 1.0) for term, count in tf.items()}
+        vectors.append(vec)
+    return vectors
+
+
+def _cosine_similarity(v1: Dict[str, float], v2: Dict[str, float]) -> float:
+    common = set(v1.keys()) & set(v2.keys())
+    if not common:
+        return 0.0
+    dot = sum(v1[k] * v2[k] for k in common)
+    norm1 = math.sqrt(sum(v ** 2 for v in v1.values()))
+    norm2 = math.sqrt(sum(v ** 2 for v in v2.values()))
+    if norm1 == 0 or norm2 == 0:
+        return 0.0
+    return dot / (norm1 * norm2)
+
+
+class AnchorChecker:
+    """
+    Goal alignment checker that runs at key decision points.
+
+    Usage:
+        checker = AnchorChecker()
+        goal = checker.parse_goal("Design a secure auth system with JWT and RBAC")
+        result = checker.check(goal, "Implemented JWT token generation...", trigger=AnchorTrigger.STEP_COMPLETE)
+        if not result.aligned:
+            print(f"DRIFT: {result.recommendation}")
+    """
+
+    DRIFT_THRESHOLD = 0.3
+    COVERAGE_THRESHOLD = 0.6
+
+    def __init__(self, drift_threshold: float = 0.3, coverage_threshold: float = 0.6):
+        self._drift_threshold = drift_threshold
+        self._coverage_threshold = coverage_threshold
+        self._check_history: List[AnchorResult] = []
+
+    def parse_goal(self, task_description: str) -> StructuredGoal:
+        """Parse a free-form task description into a StructuredGoal."""
+        items = []
+        item_id = 0
+        seen = set()
+
+        for pattern, _ in _GOAL_PATTERNS:
+            for match in re.finditer(pattern, task_description, re.MULTILINE | re.IGNORECASE):
+                desc = match.group(1).strip()
+                if desc and len(desc) > 3 and desc not in seen:
+                    seen.add(desc)
+                    keywords = _tokenize(desc)
+                    items.append(GoalItem(
+                        item_id=f"G{item_id}",
+                        description=desc,
+                        keywords=keywords,
+                    ))
+                    item_id += 1
+
+        if not items:
+            keywords = _tokenize(task_description)
+            items.append(GoalItem(
+                item_id="G0",
+                description=task_description.strip(),
+                keywords=keywords,
+            ))
+
+        return StructuredGoal(
+            goal_id=f"goal_{datetime.now().strftime('%Y%m%d_%H%M%S')}",
+            original_description=task_description,
+            items=items,
+            created_at=datetime.now().isoformat(),
+        )
+
+    def check(
+        self,
+        goal: StructuredGoal,
+        current_output: str,
+        trigger: AnchorTrigger = AnchorTrigger.STEP_COMPLETE,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> AnchorResult:
+        """
+        Check whether current output aligns with the original goal.
+
+        Args:
+            goal: The structured goal to check against.
+            current_output: The current output text to evaluate.
+            trigger: What triggered this anchor check.
+            context: Optional additional context (e.g., step info).
+
+        Returns:
+            AnchorResult with alignment status, coverage, drift info.
+        """
+        output_tokens = _tokenize(current_output)
+        output_text_lower = current_output.lower()
+
+        all_docs = [item.keywords for item in goal.items] + [output_tokens]
+        all_vectors = _compute_tfidf_vectors(all_docs)
+        output_vector = all_vectors[-1]
+
+        uncovered = []
+        drifts = []
+
+        for i, item in enumerate(goal.items):
+            item_vector = all_vectors[i]
+            sim = _cosine_similarity(item_vector, output_vector)
+
+            keyword_hits = sum(1 for kw in item.keywords if kw in output_text_lower)
+            keyword_ratio = keyword_hits / max(len(item.keywords), 1)
+
+            coverage = max(sim, keyword_ratio * 0.8 + sim * 0.2)
+            coverage = min(coverage, 1.0)
+
+            item.coverage_score = coverage
+
+            if coverage >= 0.7:
+                item.status = GoalItemStatus.FULLY_COVERED
+            elif coverage >= 0.3:
+                item.status = GoalItemStatus.PARTIALLY_COVERED
+                uncovered.append(item.description)
+            else:
+                item.status = GoalItemStatus.PENDING
+                uncovered.append(item.description)
+
+        overall_coverage = goal.overall_coverage
+        drift_score = 1.0 - overall_coverage
+
+        output_terms = set(output_tokens)
+        goal_terms = set()
+        for item in goal.items:
+            goal_terms.update(item.keywords)
+
+        extra_terms = output_terms - goal_terms
+        if extra_terms and goal_terms:
+            extra_ratio = len(extra_terms) / max(len(output_terms), 1)
+            if extra_ratio > 0.5:
+                drift_score = min(drift_score + 0.1, 1.0)
+                drifts.append(DriftItem(
+                    content=f"Output contains significant off-topic content ({extra_ratio:.0%} new terms)",
+                    severity=DriftSeverity.MEDIUM,
+                    reason=f"New terms not in goal: {', '.join(list(extra_terms)[:5])}",
+                ))
+
+        aligned = drift_score < self._drift_threshold and overall_coverage >= self._coverage_threshold
+
+        recommendation = ""
+        if not aligned:
+            if uncovered:
+                recommendation = f"Goal drift detected. Uncovered goals: {'; '.join(uncovered[:3])}"
+            if drifts:
+                recommendation += f" | Drifts: {'; '.join(d.reason for d in drifts[:2])}"
+
+        result = AnchorResult(
+            aligned=aligned,
+            trigger=trigger,
+            coverage=overall_coverage,
+            drift_score=drift_score,
+            drifts=drifts,
+            uncovered_goals=uncovered,
+            recommendation=recommendation,
+            checked_at=datetime.now().isoformat(),
+        )
+
+        self._check_history.append(result)
+
+        if not aligned:
+            logger.warning(
+                "Anchor check FAILED: coverage=%.0f%%, drift=%.0f%%, trigger=%s, rec=%s",
+                overall_coverage * 100, drift_score * 100, trigger.value, recommendation[:80],
+            )
+        else:
+            logger.debug(
+                "Anchor check PASSED: coverage=%.0f%%, drift=%.0f%%, trigger=%s",
+                overall_coverage * 100, drift_score * 100, trigger.value,
+            )
+
+        return result
+
+    @property
+    def check_history(self) -> List[AnchorResult]:
+        return list(self._check_history)
+
+    @property
+    def drift_count(self) -> int:
+        return sum(1 for r in self._check_history if not r.aligned)
+
+    @property
+    def total_checks(self) -> int:
+        return len(self._check_history)
+
+    def reset(self):
+        self._check_history.clear()