cite-agent 1.3.9__py3-none-any.whl → 1.4.3__py3-none-any.whl

cite_agent/response_pipeline.py

@@ -0,0 +1,295 @@
+"""
+Response Pipeline - Comprehensive Quality Processing
+Integrates all quality improvements into a single pipeline
+
+This is the "intelligence layer" that was missing
+"""
+
+import logging
+from typing import Dict, Any, Optional
+from dataclasses import dataclass
+
+from .error_handler import GracefulErrorHandler
+from .response_formatter import ResponseFormatter
+from .quality_gate import ResponseQualityGate, QualityAssessment
+from .response_enhancer import ResponseEnhancer
+from .response_style_enhancer import ResponseStyleEnhancer
+from .action_first_mode import ActionFirstMode
+from .auto_expander import AutoExpander
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ProcessedResponse:
+    """Result of pipeline processing"""
+    final_response: str
+    quality_score: float
+    improvements_applied: list
+    processing_notes: list
+
+
+class ResponsePipeline:
+    """
+    End-to-end response processing pipeline
+
+    Steps:
+    1. Clean any technical errors
+    2. Apply appropriate formatting
+    3. Assess quality
+    4. Improve if needed
+    5. Final safety check
+    """
+
+    @classmethod
+    async def process(
+        cls,
+        raw_response: str,
+        query: str,
+        context: Dict[str, Any],
+        response_type: str = "generic"
+    ) -> ProcessedResponse:
+        """
+        Process a response through the quality pipeline
+
+        Args:
+            raw_response: The initial response from LLM
+            query: The original user query
+            context: Additional context (tools used, API results, etc.)
+            response_type: Type of response (greeting, file_list, data, code, etc.)
+
+        Returns:
+            ProcessedResponse with final polished response and metadata
+        """
+        improvements = []
+        notes = []
+
+        # Step 1: Clean technical errors (safety first!)
+        cleaned_response = GracefulErrorHandler.wrap_response_with_error_handling(raw_response)
+
+        if cleaned_response != raw_response:
+            improvements.append("Removed technical error messages")
+            notes.append(f"Cleaned {len(raw_response) - len(cleaned_response)} chars of technical details")
+
+        # Step 2: Apply appropriate formatting based on response type
+        formatted_response = cls._apply_smart_formatting(
+            cleaned_response,
+            query,
+            context,
+            response_type
+        )
+
+        if formatted_response != cleaned_response:
+            improvements.append("Applied smart formatting")
+
+        # Step 3: Assess quality
+        assessment = ResponseQualityGate.assess(formatted_response, query, context)
+
+        notes.append(f"Quality score: {assessment.overall_score:.2f}")
+        if assessment.issues:
+            notes.append(f"Issues: {', '.join(assessment.issues[:3])}")
+
+        # Step 4: Apply automatic improvements
+        if assessment.should_retry or assessment.overall_score < 0.75:
+            improved_response = ResponseQualityGate.improve_response(
+                formatted_response,
+                assessment,
+                query
+            )
+
+            if improved_response != formatted_response:
+                improvements.append("Applied automatic quality improvements")
+                formatted_response = improved_response
+
+                # Re-assess after improvements
+                new_assessment = ResponseQualityGate.assess(improved_response, query, context)
+                notes.append(f"Improved quality: {new_assessment.overall_score:.2f}")
+                assessment = new_assessment
+
+        # Step 4.5: ENHANCE to push quality even higher
+        if assessment.overall_score < 0.80:
+            enhanced_response = ResponseEnhancer.enhance(
+                formatted_response,
+                query,
+                context
+            )
+
+            if enhanced_response != formatted_response:
+                improvements.append("Enhanced for higher quality")
+                formatted_response = enhanced_response
+
+                # Re-assess after enhancement
+                final_assessment = ResponseQualityGate.assess(enhanced_response, query, context)
+                notes.append(f"Enhanced quality: {final_assessment.overall_score:.2f}")
+                assessment = final_assessment
+
+        # Step 4.7: STYLE ENHANCEMENT - Make responses pleasant and stylish
+        # This is what makes responses ACTUALLY GOOD, not just functional
+        styled_response = ResponseStyleEnhancer.enhance(
+            formatted_response,
+            query,
+            context
+        )
+
+        if styled_response != formatted_response:
+            improvements.append("Enhanced style to be pleasant and friendly")
+            notes.append("Applied style enhancements: warm, natural")
+            formatted_response = styled_response
+
+        # Step 4.8: ACTION-FIRST MODE - Remove asking phrases, prioritize action over talk
+        # User wants agent to DO things, not ask permission
+        action_first_response = ActionFirstMode.make_action_first(
+            formatted_response,
+            query,
+            context
+        )
+
+        if action_first_response != formatted_response:
+            improvements.append("Transformed to action-first mode")
+            notes.append("Removed asking phrases - agent shows results proactively")
+            formatted_response = action_first_response
+
+        # Step 4.9: AUTO-EXPANSION CHECK - Detect if response needs more detail
+        # This is a quality check - if it detects expansion needed, it means
+        # the LLM didn't follow action-first guidelines properly
+        checked_response = AutoExpander.expand(formatted_response, query, context)
+        # (This currently just logs warnings if expansion is detected as needed)
+
+        # Step 5: Final safety check
+        final_response = GracefulErrorHandler.wrap_response_with_error_handling(checked_response)
+
+        return ProcessedResponse(
+            final_response=final_response,
+            quality_score=assessment.overall_score,
+            improvements_applied=improvements,
+            processing_notes=notes
+        )
+
+    @classmethod
+    def _apply_smart_formatting(
+        cls,
+        response: str,
+        query: str,
+        context: Dict[str, Any],
+        response_type: str
+    ) -> str:
+        """
+        Apply intelligent formatting based on response type and context
+        """
+        # Detect response type if not specified
+        if response_type == "generic":
+            response_type = cls._detect_response_type(response, query, context)
+
+        # Apply appropriate formatter
+        if response_type == "greeting":
+            # Greetings should be brief and friendly
+            if len(response.split()) > 30:
+                return ResponseFormatter.format_greeting(query)
+            return response
+
+        elif response_type == "acknowledgment":
+            # Thanks/acknowledgments should be brief
+            if len(response.split()) > 20:
+                return ResponseFormatter.format_acknowledgment(query)
+            return response
+
+        elif response_type == "file_list":
+            # File listings should be structured
+            # Extract file paths from response
+            import re
+            file_pattern = r'[\/\w\-\.]+\.[\w]+'
+            files = re.findall(file_pattern, response)
+
+            if files:
+                return ResponseFormatter.format_file_listing(files, query)
+            return response
+
+        elif response_type == "clarification":
+            # Clarifications should have bullets
+            # Extract options if present
+            lines = response.split('\n')
+            options = [line.strip('- •*').strip() for line in lines if line.strip().startswith(('-', '•', '*'))]
+
+            if not options:
+                # No bullets found - check for sentence-based options
+                sentences = response.split('.')
+                if len(sentences) >= 2:
+                    # Try to extract options from sentences
+                    options = [s.strip() + '.' for s in sentences[1:4] if len(s.strip()) > 10]
+
+            if options:
+                question = lines[0] if lines else "What would you like to focus on?"
+                return ResponseFormatter.format_clarification(question, options)
+            return response
+
+        elif response_type == "code":
+            # Code should have structure (summary + code + offer)
+            return response  # Already should be formatted
+
+        elif response_type == "shell_output":
+            # Shell output should be clean and focused
+            output_type = context.get('shell_output_type', 'generic')
+            command = context.get('command', '')
+            output = context.get('output', response)
+
+            return ResponseFormatter.format_shell_output(command, output, output_type)
+
+        # Default: apply progressive disclosure if too long
+        elif len(response) > 600:
+            return ResponseFormatter.apply_progressive_disclosure(response, "generic", 500)
+
+        return response
+
+    @classmethod
+    def _detect_response_type(cls, response: str, query: str, context: Dict[str, Any]) -> str:
+        """
+        Detect what type of response this is
+        """
+        query_lower = query.lower()
+        response_lower = response.lower()
+
+        # Greeting
+        if any(word in query_lower for word in ['hi', 'hey', 'hello']) and len(query.split()) <= 3:
+            return "greeting"
+
+        # Acknowledgment
+        if any(word in query_lower for word in ['thanks', 'thank you', 'thx']):
+            return "acknowledgment"
+
+        # File listing
+        if ('file' in query_lower or 'directory' in query_lower or 'folder' in query_lower):
+            if any(ext in response for ext in ['.py', '.js', '.md', '.txt', '.json', '.csv']):
+                return "file_list"
+
+        # Clarification
+        if '?' in response and any(word in response_lower for word in ['which', 'what kind', 'tell me more']):
+            return "clarification"
+
+        # Code
+        if '```' in response or 'def ' in response or 'class ' in response:
+            return "code"
+
+        # Shell output
+        if context.get('tools_used') and 'shell_execution' in context.get('tools_used', []):
+            return "shell_output"
+
+        return "generic"
+
+
+# Convenience function
+async def process_response(
+    response: str,
+    query: str,
+    context: Dict[str, Any] = None,
+    response_type: str = "generic"
+) -> str:
+    """
+    Quick response processing - returns just the final response string
+    """
+    result = await ResponsePipeline.process(
+        response,
+        query,
+        context or {},
+        response_type
+    )
+    return result.final_response

cite_agent/response_style_enhancer.py

@@ -0,0 +1,259 @@
+"""
+Response Style Enhancer - Make responses PLEASANT and STYLISH
+
+Transforms robotic, formal responses into warm, friendly, conversational ones
+Target: 0.80+ style score on all responses
+
+Key transformations:
+1. Warm greetings instead of formal ones
+2. Natural language instead of robotic phrasing
+3. Elegant formatting with bullets and structure
+4. Anticipatory offers to help more
+5. Personality and friendliness
+"""
+
+import re
+from typing import Dict, Any, List, Tuple
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class ResponseStyleEnhancer:
+    """
+    Enhances response style to be pleasant and stylish
+
+    Focus areas:
+    1. WARMTH - Replace cold/formal with friendly/warm
+    2. NATURAL - Replace robotic with conversational
+    3. ELEGANT - Add beautiful formatting
+    4. ANTICIPATORY - Offer to help with next steps
+    5. PERSONALITY - Make it feel like a smart friend
+    """
+
+    # Formal → Warm transformations
+    GREETING_TRANSFORMS = {
+        r'^Hello\.\s*How can I assist you today\?': 'Hi there! Ready to help - what can I dig into for you?',
+        r'^Hello\.\s*': 'Hi! ',
+        r'^Greetings\.\s*': 'Hey there! ',
+        r'^Good (morning|afternoon|evening)\.\s*': 'Hi! ',
+        r'How may I help you\?': 'What can I help you with?',
+        r'How can I assist you\?': 'What would you like to know?',
+        r'Is there anything else\?': 'Need anything else?',
+    }
+
+    # Robotic → Natural transformations
+    NATURAL_TRANSFORMS = {
+        r'I have analyzed': "I've looked at",
+        r'I have determined': "I found",
+        r'I have located': "I found",
+        r'I have identified': "I see",
+        r'I have processed': "I've checked",
+        r'I have executed': "I ran",
+        r'Processing complete': "All done",
+        r'Execution successful': "Got it",
+        r'Operation completed': "Done",
+        r'Please note that': "Note:",
+        r'It should be noted': "Keep in mind",
+        r'Additionally,': "Also,",
+        r'Furthermore,': "Plus,",
+        r'However,': "But",
+        r'Therefore,': "So",
+        r'Subsequently,': "Then",
+        r'You are welcome': "Happy to help! Let me know if you need anything else",
+    }
+
+    # Cold → Warm phrases
+    WARM_TRANSFORMS = {
+        r'You must': 'You should',
+        r'You need to': "You'll want to",
+        r'It is required': "You'll need to",
+        r'It is necessary': "You'll want to",
+        r'Error:': 'Hmm,',
+        r'Failed to': "Couldn't",
+        r'Unable to': "Can't",
+    }
+
+    # Add anticipatory phrases based on context
+    ANTICIPATORY_PATTERNS = [
+        (r'(I found|Here are|Here\'s)\s+(\d+)\s+(files?|items?|results?)',
+         lambda m: f"{m.group(0)}\n\nWant me to show you what's in any of these?"),
+        (r'(The|This)\s+(file|code|function)\s+(\w+)',
+         lambda m: f"{m.group(0)}. Want me to walk through how it works?"),
+        (r'(Here\'s|Here is)\s+(what|how|the)',
+         lambda m: f"{m.group(0)}"),  # Keep as is, will add offer at end
+    ]
+
+    @classmethod
+    def enhance(cls, response: str, query: str, context: Dict[str, Any]) -> str:
+        """
+        Enhance response style to be pleasant and stylish
+
+        Args:
+            response: Original response
+            query: User's query
+            context: Context including tools, data, etc.
+
+        Returns:
+            Enhanced stylish response
+        """
+        if not response or len(response) < 5:
+            return response
+
+        enhanced = response
+
+        # Step 1: Make greetings warm and friendly
+        enhanced = cls._enhance_greetings(enhanced, query)
+
+        # Step 2: Make language natural instead of robotic
+        enhanced = cls._make_natural(enhanced)
+
+        # Step 3: Add warmth
+        enhanced = cls._add_warmth(enhanced)
+
+        # Step 4: Improve formatting to be elegant
+        enhanced = cls._make_elegant(enhanced, context)
+
+        # Step 5: Add anticipatory offers
+        enhanced = cls._add_anticipatory_offers(enhanced, query, context)
+
+        # Step 6: Add personality touches
+        enhanced = cls._add_personality(enhanced, query)
+
+        return enhanced
+
+    @classmethod
+    def _enhance_greetings(cls, response: str, query: str) -> str:
+        """Replace formal greetings with warm friendly ones"""
+        # Check if query is a greeting
+        query_lower = query.lower().strip()
+        is_greeting = any(g in query_lower for g in ['hi', 'hello', 'hey', 'greetings'])
+
+        if is_greeting and len(query_lower) < 20:
+            # Replace formal greeting responses
+            for pattern, replacement in cls.GREETING_TRANSFORMS.items():
+                response = re.sub(pattern, replacement, response, flags=re.IGNORECASE)
+
+        return response
+
+    @classmethod
+    def _make_natural(cls, response: str) -> str:
+        """Replace robotic phrasing with natural conversation"""
+        enhanced = response
+
+        for pattern, replacement in cls.NATURAL_TRANSFORMS.items():
+            enhanced = re.sub(pattern, replacement, enhanced, flags=re.IGNORECASE)
+
+        return enhanced
+
+    @classmethod
+    def _add_warmth(cls, response: str) -> str:
+        """Replace cold/formal phrases with warm ones"""
+        enhanced = response
+
+        for pattern, replacement in cls.WARM_TRANSFORMS.items():
+            enhanced = re.sub(pattern, replacement, enhanced, flags=re.IGNORECASE)
+
+        return enhanced
+
+    @classmethod
+    def _make_elegant(cls, response: str, context: Dict[str, Any]) -> str:
+        """
+        Add elegant formatting
+
+        - Convert plain lists to bulleted lists
+        - Add proper spacing
+        - Use emphasis where appropriate
+        """
+        # Check if response has lists that aren't bulleted
+        lines = response.split('\n')
+
+        # Detect list patterns like "file1, file2, file3"
+        for i, line in enumerate(lines):
+            # If line has comma-separated items (3+)
+            if line.count(',') >= 2 and len(line) < 200:
+                parts = [p.strip() for p in line.split(',')]
+
+                if len(parts) >= 3:
+                    # Check if these look like filenames or items
+                    if any(ext in line for ext in ['.py', '.js', '.md', '.txt', '.json']) or \
+                       all(len(p) < 50 for p in parts):
+                        # Convert to bulleted list
+                        intro = "I found these:" if i == 0 else ""
+                        bulleted = '\n'.join([f"• {p}" for p in parts])
+                        lines[i] = f"{intro}\n\n{bulleted}" if intro else bulleted
+
+        enhanced = '\n'.join(lines)
+
+        # Add proper paragraph spacing if missing
+        if enhanced.count('\n\n') == 0 and len(enhanced) > 200:
+            # Split into paragraphs at sentence boundaries
+            sentences = re.split(r'(?<=[.!?])\s+', enhanced)
+            if len(sentences) >= 3:
+                # Group into 2-3 sentence paragraphs
+                paragraphs = []
+                current = []
+                for sent in sentences:
+                    current.append(sent)
+                    if len(current) >= 2:
+                        paragraphs.append(' '.join(current))
+                        current = []
+                if current:
+                    paragraphs.append(' '.join(current))
+
+                enhanced = '\n\n'.join(paragraphs)
+
+        return enhanced
+
+    @classmethod
+    def _add_anticipatory_offers(cls, response: str, query: str, context: Dict[str, Any]) -> str:
+        """
+        Add anticipatory offers - BUT IN ACTION-FIRST MODE
+
+        Instead of "Want me to X?", the agent should have ALREADY DONE X
+        So we SKIP adding asking phrases in action-first mode
+
+        DISABLED: User wants action-first, not conversation-first
+        """
+        # ACTION-FIRST MODE: Don't add asking phrases
+        # The agent should have already done the obvious next step
+        # If it didn't, that's a different problem to fix
+
+        return response  # Return unchanged - no asking phrases added
+
+    @classmethod
+    def _add_personality(cls, response: str, query: str) -> str:
+        """Add personality touches to make it feel like a smart friend"""
+        # Check query sentiment
+        query_lower = query.lower()
+
+        # If user said thanks
+        if any(word in query_lower for word in ['thanks', 'thank you', 'appreciate']):
+            # Make response warmer
+            if 'you are welcome' in response.lower() or 'you\'re welcome' in response.lower():
+                response = re.sub(
+                    r"you'?re? welcome\.?",
+                    "Happy to help! Let me know if you need anything else.",
+                    response,
+                    flags=re.IGNORECASE
+                )
+
+        # If user seems excited (exclamation marks)
+        if '!' in query and len(query) < 50:
+            # Match energy slightly
+            if not '!' in response:
+                # Add one exclamation at the end if appropriate
+                response = response.rstrip('.') + '!'
+
+        # If response is very short and abrupt, make it friendlier
+        if len(response) < 20 and '?' not in response:
+            # Add friendly suffix
+            if not any(word in response.lower() for word in ['happy', 'glad', 'sure']):
+                response += " Let me know if you need anything else!"
+
+        return response
+
+
+def enhance_style(response: str, query: str, context: Dict[str, Any] = None) -> str:
+    """Convenience function to enhance response style"""
+    return ResponseStyleEnhancer.enhance(response, query, context or {})