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

cite_agent/request_queue.py

@@ -0,0 +1,390 @@
+"""
+Intelligent Request Queue with Backpressure
+Prioritizes requests, prevents thundering herd, gracefully degrades under load
+"""
+
+import asyncio
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Dict, List, Optional, Callable
+from datetime import datetime, timedelta
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class RequestPriority(Enum):
+    """Request priority levels"""
+    URGENT = 0      # User initiated, blocking
+    NORMAL = 1      # Standard requests
+    BATCH = 2       # Background/analysis
+    MAINTENANCE = 3 # Cleanup, archival
+
+
+@dataclass
+class QueuedRequest:
+    """A request waiting in queue"""
+    request_id: str
+    user_id: str
+    priority: RequestPriority
+    submitted_at: datetime
+    max_wait_time: float  # seconds
+    callback: Callable
+    args: tuple = field(default_factory=tuple)
+    kwargs: dict = field(default_factory=dict)
+    
+    def is_expired(self) -> bool:
+        """Check if request exceeded max wait time"""
+        elapsed = (datetime.now() - self.submitted_at).total_seconds()
+        return elapsed > self.max_wait_time
+
+
+class CircuitStatus(Enum):
+    """Circuit breaker status"""
+    CLOSED = "closed"      # Normal operation
+    OPEN = "open"          # Failing, reject fast
+    HALF_OPEN = "half_open"  # Testing recovery
+
+
+@dataclass
+class RequestQueueMetrics:
+    """Metrics about queue health"""
+    queue_depth: int
+    total_queued: int
+    total_processed: int
+    total_expired: int
+    avg_wait_time: float
+    p95_wait_time: float
+    circuit_status: CircuitStatus
+    active_requests: int
+    max_concurrent: int
+
+
+class IntelligentRequestQueue:
+    """
+    Priority queue with backpressure, circuit breaker integration, and metrics
+    
+    Features:
+    - Priority levels (urgent > normal > batch > maintenance)
+    - Per-user concurrency limits
+    - Queue depth monitoring
+    - Automatic circuit breaker integration
+    - Request expiration (don't serve stale requests)
+    - User notifications about wait time
+    - Graceful degradation under load
+    """
+    
+    def __init__(
+        self,
+        max_concurrent_global: int = 50,
+        max_concurrent_per_user: int = 3,
+        queue_size_limit: int = 1000,
+        warning_threshold: float = 0.7,  # warn when queue at 70%
+        rejection_threshold: float = 0.95  # reject when queue at 95%
+    ):
+        self.max_concurrent_global = max_concurrent_global
+        self.max_concurrent_per_user = max_concurrent_per_user
+        self.queue_size_limit = queue_size_limit
+        self.warning_threshold = warning_threshold
+        self.rejection_threshold = rejection_threshold
+        
+        # Queues by priority
+        self.queues: Dict[RequestPriority, asyncio.Queue] = {
+            priority: asyncio.Queue(maxsize=queue_size_limit)
+            for priority in RequestPriority
+        }
+        
+        # Active requests tracking
+        self.active_requests: Dict[str, datetime] = {}  # request_id -> start_time
+        self.user_active: Dict[str, int] = {}  # user_id -> count
+        
+        # Metrics
+        self.total_processed = 0
+        self.total_queued = 0
+        self.total_expired = 0
+        self.wait_times: List[float] = []  # for p95 calculation
+        
+        # Circuit breaker state
+        self.circuit_status = CircuitStatus.CLOSED
+        self.circuit_open_at: Optional[datetime] = None
+        self.circuit_recovery_timeout = 30  # seconds
+        
+        # Background worker
+        self.worker_task: Optional[asyncio.Task] = None
+        self.is_running = False
+    
+    async def start(self):
+        """Start the queue worker"""
+        if self.is_running:
+            return
+        
+        self.is_running = True
+        self.worker_task = asyncio.create_task(self._process_queue())
+        logger.info("🚀 Request queue started")
+    
+    async def stop(self):
+        """Stop the queue worker"""
+        self.is_running = False
+        if self.worker_task:
+            await self.worker_task
+        logger.info("⛔ Request queue stopped")
+    
+    async def submit(
+        self,
+        user_id: str,
+        callback: Callable,
+        priority: RequestPriority = RequestPriority.NORMAL,
+        max_wait_time: float = 30.0,
+        request_id: Optional[str] = None,
+        *args,
+        **kwargs
+    ) -> tuple[bool, Optional[str]]:
+        """
+        Submit a request to the queue
+        
+        Returns:
+            (success, error_message)
+        """
+        if request_id is None:
+            request_id = f"{user_id}_{time.time()}"
+        
+        # Check queue capacity
+        queue_usage = self._get_queue_usage()
+        
+        if queue_usage > self.rejection_threshold:
+            return False, f"System overloaded (queue at {queue_usage*100:.0f}%). Please try again in 30 seconds."
+        
+        if queue_usage > self.warning_threshold:
+            warning = f"⚠️ System busy. Your request may take up to {max_wait_time:.0f}s."
+        else:
+            warning = None
+        
+        # Check circuit breaker
+        if self.circuit_status == CircuitStatus.OPEN:
+            if self._should_attempt_recovery():
+                self.circuit_status = CircuitStatus.HALF_OPEN
+                logger.info("🔄 Circuit breaker: attempting recovery")
+            else:
+                return False, "System is temporarily unavailable. Retrying in 30s..."
+        
+        # Create queued request
+        request = QueuedRequest(
+            request_id=request_id,
+            user_id=user_id,
+            priority=priority,
+            submitted_at=datetime.now(),
+            max_wait_time=max_wait_time,
+            callback=callback,
+            args=args,
+            kwargs=kwargs
+        )
+        
+        # Add to appropriate priority queue
+        try:
+            self.queues[priority].put_nowait(request)
+            self.total_queued += 1
+            
+            message = f"✓ Queued (position #{self._get_queue_depth()})"
+            if warning:
+                message += f"\n{warning}"
+            
+            return True, message
+        
+        except asyncio.QueueFull:
+            return False, "Queue is full. Please try again soon."
+    
+    async def _process_queue(self):
+        """Main worker: continuously process queued requests"""
+        while self.is_running:
+            try:
+                # Check if we can process more requests
+                if len(self.active_requests) >= self.max_concurrent_global:
+                    await asyncio.sleep(0.1)
+                    continue
+                
+                # Get next request from highest priority queue
+                request = await self._get_next_request()
+                if request is None:
+                    await asyncio.sleep(0.1)
+                    continue
+                
+                # Check expiration
+                if request.is_expired():
+                    self.total_expired += 1
+                    logger.warning(f"⏰ Request {request.request_id} expired (waited too long)")
+                    continue
+                
+                # Check user concurrency limit
+                user_count = self.user_active.get(request.user_id, 0)
+                if user_count >= self.max_concurrent_per_user:
+                    # Re-queue this request with same priority
+                    await self.queues[request.priority].put(request)
+                    await asyncio.sleep(0.5)
+                    continue
+                
+                # Execute the request
+                await self._execute_request(request)
+            
+            except Exception as e:
+                logger.error(f"❌ Queue worker error: {e}", exc_info=True)
+                await asyncio.sleep(1)
+    
+    async def _get_next_request(self) -> Optional[QueuedRequest]:
+        """Get highest priority non-empty request"""
+        # Try each priority level in order
+        for priority in RequestPriority:
+            try:
+                return self.queues[priority].get_nowait()
+            except asyncio.QueueEmpty:
+                continue
+        
+        return None
+    
+    async def _execute_request(self, request: QueuedRequest):
+        """Execute a request and track metrics"""
+        request_id = request.request_id
+        start_time = datetime.now()
+        
+        try:
+            # Track active request
+            self.active_requests[request_id] = start_time
+            self.user_active[request.user_id] = self.user_active.get(request.user_id, 0) + 1
+            
+            wait_time = (start_time - request.submitted_at).total_seconds()
+            self.wait_times.append(wait_time)
+            
+            logger.debug(f"▶️ Executing {request_id} (waited {wait_time:.1f}s)")
+            
+            # Call the callback
+            result = await request.callback(*request.args, **request.kwargs)
+            
+            # Record success
+            self.total_processed += 1
+            
+            # Update circuit breaker
+            if self.circuit_status == CircuitStatus.HALF_OPEN:
+                self.circuit_status = CircuitStatus.CLOSED
+                logger.info("🟢 Circuit breaker: recovered")
+            
+            return result
+        
+        except Exception as e:
+            logger.error(f"❌ Request {request_id} failed: {e}")
+            
+            # Update circuit breaker on failure
+            self._on_request_failure()
+            
+            raise
+        
+        finally:
+            # Clean up tracking
+            self.active_requests.pop(request_id, None)
+            self.user_active[request.user_id] -= 1
+            
+            elapsed = (datetime.now() - start_time).total_seconds()
+            logger.debug(f"✓ Request {request_id} completed in {elapsed:.2f}s")
+    
+    def _on_request_failure(self):
+        """Called when a request fails - updates circuit breaker"""
+        # Track failure rate
+        if len(self.active_requests) > 0:
+            failure_rate = self.total_queued / max(1, self.total_processed + 1)
+            
+            # Open circuit if failure rate high
+            if failure_rate > 0.3:  # >30% failure rate
+                if self.circuit_status != CircuitStatus.OPEN:
+                    logger.error(f"🔴 Circuit breaker: OPEN (failure rate {failure_rate:.1%})")
+                    self.circuit_status = CircuitStatus.OPEN
+                    self.circuit_open_at = datetime.now()
+    
+    def _should_attempt_recovery(self) -> bool:
+        """Check if circuit breaker should attempt recovery"""
+        if not self.circuit_open_at:
+            return True
+        
+        elapsed = (datetime.now() - self.circuit_open_at).total_seconds()
+        return elapsed > self.circuit_recovery_timeout
+    
+    def _get_queue_usage(self) -> float:
+        """Get current queue usage as percentage (0.0 to 1.0)"""
+        total_queued = sum(q.qsize() for q in self.queues.values())
+        return min(1.0, total_queued / self.queue_size_limit)
+    
+    def _get_queue_depth(self) -> int:
+        """Get total requests in queue"""
+        return sum(q.qsize() for q in self.queues.values())
+    
+    def get_metrics(self) -> RequestQueueMetrics:
+        """Get current queue metrics"""
+        queue_depth = self._get_queue_depth()
+        wait_times_sorted = sorted(self.wait_times[-100:])  # Last 100 requests
+        
+        p95_wait = wait_times_sorted[int(len(wait_times_sorted) * 0.95)] if wait_times_sorted else 0
+        avg_wait = sum(self.wait_times) / len(self.wait_times) if self.wait_times else 0
+        
+        return RequestQueueMetrics(
+            queue_depth=queue_depth,
+            total_queued=self.total_queued,
+            total_processed=self.total_processed,
+            total_expired=self.total_expired,
+            avg_wait_time=avg_wait,
+            p95_wait_time=p95_wait,
+            circuit_status=self.circuit_status,
+            active_requests=len(self.active_requests),
+            max_concurrent=self.max_concurrent_global
+        )
+    
+    def get_status_message(self) -> str:
+        """Human-readable queue status"""
+        metrics = self.get_metrics()
+        usage = self._get_queue_usage()
+        
+        lines = [
+            "📊 **Request Queue Status**",
+            f"• Queue depth: {metrics.queue_depth}/{self.queue_size_limit} ({usage*100:.0f}%)",
+            f"• Active requests: {metrics.active_requests}/{metrics.max_concurrent}",
+            f"• Processed: {metrics.total_processed} | Queued: {metrics.total_queued} | Expired: {metrics.total_expired}",
+            f"• Avg wait: {metrics.avg_wait_time:.1f}s | P95 wait: {metrics.p95_wait_time:.1f}s",
+            f"• Circuit breaker: {metrics.circuit_status.value.upper()}",
+        ]
+        
+        return "\n".join(lines)
+
+
+# Example usage
+async def example():
+    """Example of using the queue"""
+    queue = IntelligentRequestQueue(
+        max_concurrent_global=10,
+        max_concurrent_per_user=2
+    )
+    
+    await queue.start()
+    
+    # Simulate a callback
+    async def process_query(query: str) -> str:
+        await asyncio.sleep(1)  # Simulate work
+        return f"Result for: {query}"
+    
+    # Submit requests
+    for i in range(5):
+        success, msg = await queue.submit(
+            user_id="user1",
+            callback=process_query,
+            priority=RequestPriority.NORMAL,
+            args=(f"query_{i}",)
+        )
+        print(f"Request {i}: {msg}")
+    
+    # Wait a bit
+    await asyncio.sleep(10)
+    
+    # Check status
+    print(queue.get_status_message())
+    
+    await queue.stop()
+
+
+if __name__ == "__main__":
+    asyncio.run(example())

cite_agent/response_enhancer.py

@@ -0,0 +1,257 @@
+"""
+Response Enhancer - Polish responses to 0.80+ quality
+Takes good responses and makes them great
+
+Target: Every response should score 0.80+ on quality metrics
+"""
+
+import re
+from typing import Dict, Any, List
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class ResponseEnhancer:
+    """
+    Enhances responses to maximize quality scores
+
+    Focus areas:
+    1. Completeness - Address all key terms from query
+    2. Structure - Add bullets, headers, emphasis
+    3. Clarity - Make more direct and specific
+    4. Scannability - Break up walls of text
+    """
+
+    @classmethod
+    def enhance(cls, response: str, query: str, context: Dict[str, Any]) -> str:
+        """
+        Enhance a response to maximize quality
+
+        Args:
+            response: Original response
+            query: User's query
+            context: Context including tools, data, etc.
+
+        Returns:
+            Enhanced response
+        """
+        if not response or len(response) < 10:
+            return response
+
+        enhanced = response
+
+        # Enhancement 1: Add structure if missing
+        enhanced = cls._add_structure(enhanced, query)
+
+        # Enhancement 2: Make more complete by addressing key terms
+        enhanced = cls._improve_completeness(enhanced, query, context)
+
+        # Enhancement 3: Improve clarity
+        enhanced = cls._improve_clarity(enhanced)
+
+        # Enhancement 4: Make more scannable
+        enhanced = cls._improve_scannability(enhanced)
+
+        # Enhancement 5: Add specificity
+        enhanced = cls._add_specificity(enhanced, context)
+
+        return enhanced
+
+    @classmethod
+    def _add_structure(cls, response: str, query: str) -> str:
+        """Add structure if response is unstructured"""
+        # Check if response lacks structure
+        has_bullets = '•' in response or '- ' in response
+        has_emphasis = '**' in response
+        has_paragraphs = '\n\n' in response
+
+        if has_bullets and has_emphasis:
+            return response  # Already well-structured
+
+        lines = response.split('\n')
+
+        # If it's a short response (< 100 words), structure is less important
+        if len(response.split()) < 100:
+            return response
+
+        # If it's listing things but not using bullets, add them
+        if len(lines) > 1 and not has_bullets:
+            # Check if lines look like a list
+            list_indicators = ['1.', '2.', 'first', 'second', 'also', 'additionally']
+            looks_like_list = sum(1 for line in lines if any(ind in line.lower() for ind in list_indicators))
+
+            if looks_like_list >= 2:
+                # Convert to bulleted list
+                enhanced_lines = []
+                for line in lines:
+                    stripped = line.strip()
+                    if stripped and not stripped.endswith(':'):
+                        if not stripped.startswith('•'):
+                            enhanced_lines.append(f"• {stripped}")
+                        else:
+                            enhanced_lines.append(stripped)
+                    else:
+                        enhanced_lines.append(stripped)
+
+                return '\n'.join(enhanced_lines)
+
+        return response
+
+    @classmethod
+    def _improve_completeness(cls, response: str, query: str, context: Dict[str, Any]) -> str:
+        """Make response more complete by addressing key query terms"""
+        # Extract key terms from query
+        stop_words = {'the', 'a', 'an', 'is', 'are', 'was', 'were', 'what', 'how', 'why', 'when', 'where', 'who', 'which', 'do', 'does', 'did', 'can', 'could', 'would', 'should', 'me', 'my', 'you', 'your', 'in', 'on', 'at', 'to', 'for', 'of', 'with', 'from'}
+
+        query_terms = [
+            word.lower().strip('?.,!:;')
+            for word in query.split()
+            if len(word) > 3 and word.lower() not in stop_words
+        ]
+
+        if not query_terms:
+            return response
+
+        response_lower = response.lower()
+
+        # Find terms that aren't addressed
+        missing_terms = [term for term in query_terms if term not in response_lower]
+
+        # If we're missing major terms, try to add context
+        if len(missing_terms) > len(query_terms) * 0.5:  # Missing > 50% of key terms
+            # Check if we have context that addresses these terms
+            if context.get('api_results') or context.get('tools_used'):
+                # Add note about what was checked
+                tools_used = context.get('tools_used', [])
+
+                if 'shell_execution' in tools_used:
+                    # File/directory query
+                    if any(term in query.lower() for term in ['file', 'directory', 'folder']):
+                        if 'file' in missing_terms or 'directory' in missing_terms:
+                            # Make it clear we checked files/directories
+                            response = response.replace(
+                                "We're in",
+                                "I checked the current directory. We're in"
+                            )
+
+        return response
+
+    @classmethod
+    def _improve_clarity(cls, response: str) -> str:
+        """Make response more clear and direct"""
+        # Remove excessive hedging
+        hedge_phrases = {
+            'i think maybe': 'probably',
+            'i believe that possibly': 'likely',
+            'it seems like perhaps': 'it appears',
+            'i might suggest': 'i suggest',
+            'it could potentially be': 'it may be',
+        }
+
+        enhanced = response
+        for wordy, concise in hedge_phrases.items():
+            enhanced = enhanced.replace(wordy, concise)
+
+        # Remove filler phrases at start
+        filler_starters = [
+            'Well, ',
+            'So, ',
+            'Basically, ',
+            'Actually, ',
+            'You know, ',
+        ]
+
+        for filler in filler_starters:
+            if enhanced.startswith(filler):
+                enhanced = enhanced[len(filler):]
+                # Capitalize first letter
+                if enhanced:
+                    enhanced = enhanced[0].upper() + enhanced[1:]
+
+        return enhanced
+
+    @classmethod
+    def _improve_scannability(cls, response: str) -> str:
+        """Make response more scannable"""
+        # Break up very long paragraphs
+        if '\n\n' not in response and len(response) > 300:
+            # Split into sentences
+            sentences = re.split(r'(?<=[.!?])\s+', response)
+
+            if len(sentences) >= 4:
+                # Group into paragraphs of 2-3 sentences
+                paragraphs = []
+                current = []
+
+                for sent in sentences:
+                    current.append(sent)
+                    if len(current) >= 2:
+                        paragraphs.append(' '.join(current))
+                        current = []
+
+                if current:
+                    paragraphs.append(' '.join(current))
+
+                if len(paragraphs) > 1:
+                    return '\n\n'.join(paragraphs)
+
+        # Check line length - break up super long lines
+        lines = response.split('\n')
+        enhanced_lines = []
+
+        for line in lines:
+            if len(line) > 200 and ',' in line:
+                # Split on commas for readability
+                parts = line.split(', ')
+                if len(parts) >= 3:
+                    # Make it a bulleted list
+                    enhanced_lines.append(parts[0] + ':')
+                    for part in parts[1:]:
+                        enhanced_lines.append(f"  • {part.strip()}")
+                else:
+                    enhanced_lines.append(line)
+            else:
+                enhanced_lines.append(line)
+
+        return '\n'.join(enhanced_lines)
+
+    @classmethod
+    def _add_specificity(cls, response: str, context: Dict[str, Any]) -> str:
+        """Add specific details from context if response is vague"""
+        # Check if response is vague
+        vague_phrases = [
+            'some files',
+            'a few',
+            'several',
+            'multiple',
+            'various',
+        ]
+
+        response_lower = response.lower()
+        is_vague = any(phrase in response_lower for phrase in vague_phrases)
+
+        if not is_vague:
+            return response
+
+        # Try to add specifics from context
+        api_results = context.get('api_results', {})
+
+        # If we have file data, be specific about count
+        if 'files' in response_lower and isinstance(api_results, dict):
+            # Look for file lists in results
+            for key, value in api_results.items():
+                if isinstance(value, (list, tuple)) and len(value) > 0:
+                    # Found a list - add count
+                    count = len(value)
+                    response = response.replace('some files', f'{count} files')
+                    response = response.replace('a few files', f'{count} files')
+                    response = response.replace('several files', f'{count} files')
+                    break
+
+        return response
+
+
+def enhance_response(response: str, query: str, context: Dict[str, Any] = None) -> str:
+    """Convenience function to enhance a response"""
+    return ResponseEnhancer.enhance(response, query, context or {})