cite-agent 1.3.3__tar.gz → 1.4.3__tar.gz

{cite_agent-1.3.3/cite_agent.egg-info → cite_agent-1.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cite-agent
-Version: 1.3.3
+Version: 1.4.3
 Summary: Terminal AI assistant for academic research with citation verification
 Home-page: https://github.com/Spectating101/cite-agent
 Author: Cite-Agent Team
@@ -194,6 +194,11 @@ cite-agent "我的p值是0.05，這顯著嗎？"
 cite-agent "天空是藍色的嗎？"
 ```
 
+#### Runtime Controls
+
+- Responses render immediately—there’s no artificial typing delay.
+- Press `Ctrl+C` while the agent is thinking or streaming to interrupt and ask a different question on the spot.
+
 ### Python API Reference
 
 #### EnhancedNocturnalAgent
@@ -436,6 +441,15 @@ export NOCTURNAL_DEBUG=1
 cite-agent "your query"
 ```
 
+### Documentation
+
+For developers and contributors:
+- **[SYSTEM_STATUS.md](SYSTEM_STATUS.md)** - Current system status, test results, how to run
+- **[ARCHITECTURE_EXPLAINED.md](ARCHITECTURE_EXPLAINED.md)** - Why the codebase is complex
+- **[CHANGELOG.md](CHANGELOG.md)** - Version history and changes
+- **[INSTALL.md](INSTALL.md)** - Detailed installation instructions
+- **[TESTING.md](TESTING.md)** - How to run tests
+
 ### Support
 
 - **Documentation**: [Full docs](https://docs.cite-agent.com)

{cite_agent-1.3.3 → cite_agent-1.4.3}/README.md

@@ -157,6 +157,11 @@ cite-agent "我的p值是0.05，這顯著嗎？"
 cite-agent "天空是藍色的嗎？"
 ```
 
+#### Runtime Controls
+
+- Responses render immediately—there’s no artificial typing delay.
+- Press `Ctrl+C` while the agent is thinking or streaming to interrupt and ask a different question on the spot.
+
 ### Python API Reference
 
 #### EnhancedNocturnalAgent
@@ -399,6 +404,15 @@ export NOCTURNAL_DEBUG=1
 cite-agent "your query"
 ```
 
+### Documentation
+
+For developers and contributors:
+- **[SYSTEM_STATUS.md](SYSTEM_STATUS.md)** - Current system status, test results, how to run
+- **[ARCHITECTURE_EXPLAINED.md](ARCHITECTURE_EXPLAINED.md)** - Why the codebase is complex
+- **[CHANGELOG.md](CHANGELOG.md)** - Version history and changes
+- **[INSTALL.md](INSTALL.md)** - Detailed installation instructions
+- **[TESTING.md](TESTING.md)** - How to run tests
+
 ### Support
 
 - **Documentation**: [Full docs](https://docs.cite-agent.com)
@@ -427,4 +441,4 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ---
 
-**Made with ❤️ for the research community**
+**Made with ❤️ for the research community**

{cite_agent-1.3.3 → cite_agent-1.4.3}/cite_agent/__init__.py

@@ -7,9 +7,9 @@ prior stacks preserved only in Git history, kept out of the runtime footprint.
 
 from .enhanced_ai_agent import EnhancedNocturnalAgent, ChatRequest, ChatResponse
 
-__version__ = "0.9.0b1"
-__author__ = "Nocturnal Archive Team"
-__email__ = "contact@nocturnal.dev"
+__version__ = "1.4.0"
+__author__ = "Cite Agent Team"
+__email__ = "contact@citeagent.dev"
 
 __all__ = [
     "EnhancedNocturnalAgent",
@@ -18,10 +18,10 @@ __all__ = [
 ]
 
 # Package metadata
-PACKAGE_NAME = "nocturnal-archive"
+PACKAGE_NAME = "cite-agent"
 PACKAGE_VERSION = __version__
-PACKAGE_DESCRIPTION = "Beta CLI agent for finance + research workflows"
-PACKAGE_URL = "https://github.com/Spectating101/nocturnal-archive"
+PACKAGE_DESCRIPTION = "Research and finance CLI copilot with shell, Archive, and FinSight tools"
+PACKAGE_URL = "https://github.com/Spectating101/cite-agent"
 
 def get_version():
     """Get the package version"""
@@ -30,22 +30,22 @@ def get_version():
 def quick_start():
     """Print quick start instructions"""
     print("""
-🚀 Nocturnal Archive Quick Start
-================================
+🚀 Cite Agent Quick Start
+=========================
 
 1. Install the package and CLI:
-   pip install nocturnal-archive
+   pip install cite-agent
 
-2. Configure your Groq key:
-   nocturnal --setup
+2. Configure your account or local keys:
+   cite-agent --setup
 
 3. Ask a question:
-   nocturnal "Compare Apple and Microsoft net income this quarter"
+   cite-agent "Compare Apple and Microsoft net income this quarter"
 
 4. Prefer embedding in code? Minimal example:
    ```python
    import asyncio
-   from nocturnal_archive import EnhancedNocturnalAgent, ChatRequest
+   from cite_agent import EnhancedNocturnalAgent, ChatRequest
 
    async def main():
        agent = EnhancedNocturnalAgent()

cite_agent-1.4.3/cite_agent/__version__.py

@@ -0,0 +1 @@
+__version__ = "1.4.1"

cite_agent-1.4.3/cite_agent/action_first_mode.py

@@ -0,0 +1,150 @@
+"""
+Action-First Response Mode
+
+Makes agent SHOW results proactively instead of just talking about them
+
+Key principles:
+1. DO the obvious next step without asking
+2. SHOW data, don't just describe it
+3. Less talk, more action
+4. Proactive, not reactive
+"""
+
+import logging
+from typing import Dict, Any, List
+
+logger = logging.getLogger(__name__)
+
+
+class ActionFirstMode:
+    """
+    Transforms agent from conversation-first to action-first
+
+    BEFORE (conversation-first):
+    User: "List Python files"
+    Agent: "I found 3 files. Want me to show you what's in them?"
+
+    AFTER (action-first):
+    User: "List Python files"
+    Agent: [Shows list + Shows preview of main file + Shows key functions]
+    """
+
+    @classmethod
+    def should_auto_expand(cls, query: str, response: str, context: Dict[str, Any]) -> bool:
+        """
+        Determine if agent should automatically show more detail
+
+        Returns True if:
+        - Listed files → should preview main one
+        - Listed papers → should show abstracts
+        - Listed code → should show key functions
+        - Found data → should show sample
+        """
+        query_lower = query.lower()
+        response_lower = response.lower()
+
+        # If response just lists things without details, should expand
+        if any(word in response_lower for word in ['found', 'here are', 'listed']):
+            # Check if it's a list without details
+            has_bullets = '•' in response or '\n-' in response
+            is_short = len(response) < 300
+
+            if has_bullets and is_short:
+                return True
+
+        # If listing files, should preview
+        if any(word in query_lower for word in ['list', 'show', 'find']) and \
+           any(word in query_lower for word in ['file', 'files', 'code']):
+            return True
+
+        # If finding papers, should show abstracts
+        if 'papers' in query_lower or 'research' in query_lower:
+            return True
+
+        # If data query, should show sample
+        if any(word in query_lower for word in ['data', 'revenue', 'metrics', 'stats']):
+            return True
+
+        return False
+
+    @classmethod
+    def get_auto_expansion_prompt(cls, query: str, initial_response: str, context: Dict[str, Any]) -> str:
+        """
+        Generate prompt for automatic expansion
+
+        This tells the agent to SHOW more detail proactively
+        """
+        query_lower = query.lower()
+
+        # File listing → preview main file
+        if 'file' in query_lower and any(ext in initial_response for ext in ['.py', '.js', '.md']):
+            return "Now show a preview (first 50 lines) of the most important file automatically. Don't ask - just show it."
+
+        # Papers → show abstracts
+        if 'paper' in query_lower:
+            return "Now show the abstract/summary of the top 2-3 papers automatically. Don't ask - just show them."
+
+        # Code → show key functions
+        if 'code' in query_lower or 'function' in query_lower:
+            return "Now show the key functions/classes in the main file automatically. Don't ask - just show them."
+
+        # Data → show sample
+        if 'data' in query_lower or 'revenue' in query_lower:
+            return "Now show a sample/visualization of the data automatically. Don't ask - just show it."
+
+        return "Show the most useful additional detail automatically without asking permission."
+
+    @classmethod
+    def remove_asking_phrases(cls, response: str) -> str:
+        """
+        Remove phrases that ASK instead of DO
+
+        "Want me to..." → Just do it
+        "Should I..." → Just do it
+        "Would you like..." → Just do it
+        """
+        import re
+
+        asking_patterns = [
+            r'Want me to[^?]+\?',
+            r'Should I[^?]+\?',
+            r'Would you like[^?]+\?',
+            r'Need me to[^?]+\?',
+            r'Let me know if you want me to[^.]+\.',
+            r'Let me know if you need[^.]+\.',
+        ]
+
+        cleaned = response
+        for pattern in asking_patterns:
+            cleaned = re.sub(pattern, '', cleaned, flags=re.IGNORECASE)
+
+        # Clean up extra whitespace/newlines
+        cleaned = re.sub(r'\n\n+', '\n\n', cleaned)
+        cleaned = cleaned.strip()
+
+        return cleaned
+
+    @classmethod
+    def make_action_first(cls, response: str, query: str, context: Dict[str, Any]) -> str:
+        """
+        Transform response to be action-first
+
+        1. Remove asking phrases
+        2. If response is just a list, it should have been auto-expanded
+        3. Focus on SHOWING not TELLING
+        """
+        # Remove asking phrases
+        action_response = cls.remove_asking_phrases(response)
+
+        # If response is still too conversation-heavy, make it data-heavy
+        if len(action_response) < 200 and not any(marker in action_response for marker in ['```', '•', '\n-']):
+            # Response is short and has no data structure - flag for expansion
+            logger.warning("Response is conversation-heavy, should be more action-first")
+
+        return action_response
+
+
+# Convenience function
+def make_action_first(response: str, query: str, context: Dict[str, Any] = None) -> str:
+    """Quick action-first transformation"""
+    return ActionFirstMode.make_action_first(response, query, context or {})

cite_agent-1.4.3/cite_agent/adaptive_providers.py

@@ -0,0 +1,413 @@
+"""
+Adaptive Provider Selection System
+Learns which provider is best for different query types and auto-switches
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Dict, List, Optional, Tuple
+from datetime import datetime, timedelta
+import logging
+import json
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class QueryType(Enum):
+    """Categories of queries handled"""
+    ACADEMIC_PAPER = "academic_paper"      # Paper search, citations
+    FINANCIAL_DATA = "financial_data"      # Stock prices, metrics
+    WEB_SEARCH = "web_search"              # General web search
+    CODE_GENERATION = "code_generation"    # Write/debug code
+    DATA_ANALYSIS = "data_analysis"        # CSV, statistical analysis
+    CONVERSATION = "conversation"          # General chat
+    SHELL_EXECUTION = "shell_execution"    # System commands
+
+
+@dataclass
+class ProviderPerformanceProfile:
+    """Performance metrics for a provider on a specific query type"""
+    provider_name: str
+    query_type: QueryType
+    total_requests: int = 0
+    successful_requests: int = 0
+    avg_latency_ms: float = 0.0
+    p95_latency_ms: float = 0.0
+    accuracy_score: float = 1.0  # 0.0 to 1.0
+    cost_per_request: float = 0.0
+    last_used: Optional[datetime] = None
+    latency_history: List[float] = field(default_factory=list)
+    error_history: List[str] = field(default_factory=list)
+    
+    def get_success_rate(self) -> float:
+        """Success rate for this provider on this query type"""
+        if self.total_requests == 0:
+            return 0.0
+        return self.successful_requests / self.total_requests
+    
+    def get_score(self) -> float:
+        """Composite score for this provider (higher is better)"""
+        success_rate = self.get_success_rate()
+        latency_penalty = min(self.avg_latency_ms / 1000, 10)  # Cap at 10s penalty
+        cost_penalty = self.cost_per_request * 100  # Cost in cents
+        
+        # Score = (success_rate * accuracy) - latency_penalty - cost_penalty
+        score = (success_rate * self.accuracy_score * 100) - latency_penalty - cost_penalty
+        return max(0, score)  # Never negative
+    
+    def add_result(
+        self,
+        success: bool,
+        latency_ms: float,
+        accuracy_score: float = 1.0,
+        cost: float = 0.0,
+        error: Optional[str] = None
+    ):
+        """Record a result for this provider"""
+        self.total_requests += 1
+        self.latency_history.append(latency_ms)
+        
+        # Keep only last 100 latencies for p95 calculation
+        if len(self.latency_history) > 100:
+            self.latency_history = self.latency_history[-100:]
+        
+        # Update p95 latency
+        sorted_latencies = sorted(self.latency_history)
+        idx = int(len(sorted_latencies) * 0.95)
+        self.p95_latency_ms = sorted_latencies[min(idx, len(sorted_latencies) - 1)]
+        
+        # Update average
+        self.avg_latency_ms = sum(self.latency_history) / len(self.latency_history)
+        
+        if success:
+            self.successful_requests += 1
+            self.accuracy_score = (self.accuracy_score + accuracy_score) / 2
+        else:
+            self.error_history.append(error or "unknown")
+            # Keep last 10 errors
+            if len(self.error_history) > 10:
+                self.error_history = self.error_history[-10:]
+        
+        self.cost_per_request = cost
+        self.last_used = datetime.now()
+
+
+@dataclass
+class ProviderSelectionPolicy:
+    """Policy for selecting providers"""
+    always_prefer: Optional[str] = None  # Force specific provider (e.g., "cerebras")
+    avoid_providers: List[str] = field(default_factory=list)  # Never use these
+    cost_sensitive: bool = False  # Prefer cheaper if performance similar
+    latency_sensitive: bool = True  # Prefer faster
+    reliability_weight: float = 0.7  # How much to weight success rate
+    latency_weight: float = 0.3  # How much to weight latency
+
+
+class AdaptiveProviderSelector:
+    """
+    Intelligently selects providers based on:
+    - Query type (different providers excel at different tasks)
+    - Historical performance (learns what works)
+    - Current system state (avoid degraded providers)
+    - User preferences (cost vs speed)
+    - Time of day (some providers have peak hours)
+    """
+    
+    def __init__(self, storage_dir: Optional[Path] = None):
+        self.storage_dir = storage_dir or Path.home() / ".nocturnal_archive" / "provider_selection"
+        self.storage_dir.mkdir(parents=True, exist_ok=True)
+        
+        # Performance profiles: provider -> query_type -> profile
+        self.profiles: Dict[str, Dict[QueryType, ProviderPerformanceProfile]] = {}
+        
+        # Provider health status
+        self.provider_health: Dict[str, float] = {}  # provider -> health (0.0-1.0)
+        self.provider_last_degraded: Dict[str, datetime] = {}
+        
+        # Load historical data
+        self._load_profiles()
+    
+    def select_provider(
+        self,
+        query_type: QueryType,
+        available_providers: List[str],
+        policy: Optional[ProviderSelectionPolicy] = None,
+        exclude: Optional[List[str]] = None
+    ) -> Tuple[str, Optional[str]]:
+        """
+        Select best provider for this query type
+        
+        Returns:
+            (provider_name, fallback_provider)
+        """
+        policy = policy or ProviderSelectionPolicy()
+        exclude = exclude or []
+        
+        # Filter available providers
+        candidates = [
+            p for p in available_providers
+            if p not in exclude and p not in policy.avoid_providers
+        ]
+        
+        if not candidates:
+            # Fall back to anything available
+            candidates = available_providers
+        
+        # If policy says use specific provider, use it
+        if policy.always_prefer and policy.always_prefer in candidates:
+            fallback = next((p for p in candidates if p != policy.always_prefer), None)
+            return policy.always_prefer, fallback
+        
+        # Score each candidate
+        scores = {}
+        for provider in candidates:
+            profile = self._get_or_create_profile(provider, query_type)
+            health = self.provider_health.get(provider, 1.0)
+            
+            # Composite score
+            score = profile.get_score() * health
+            scores[provider] = score
+            
+            logger.debug(
+                f"Provider '{provider}' for {query_type.value}: "
+                f"score={profile.get_score():.1f}, health={health:.1%}"
+            )
+        
+        # Select top 2
+        sorted_providers = sorted(scores.items(), key=lambda x: x[1], reverse=True)
+        
+        if sorted_providers:
+            best = sorted_providers[0][0]
+            fallback = sorted_providers[1][0] if len(sorted_providers) > 1 else None
+            
+            logger.info(
+                f"📊 Selected provider '{best}' for {query_type.value} "
+                f"(fallback: {fallback})"
+            )
+            
+            return best, fallback
+        
+        # Emergency fallback
+        return candidates[0] if candidates else "cerebras", None
+    
+    def record_result(
+        self,
+        provider: str,
+        query_type: QueryType,
+        success: bool,
+        latency_ms: float,
+        accuracy_score: float = 1.0,
+        cost: float = 0.0,
+        error: Optional[str] = None
+    ):
+        """Record result of using a provider for a query type"""
+        profile = self._get_or_create_profile(provider, query_type)
+        profile.add_result(success, latency_ms, accuracy_score, cost, error)
+        
+        # Update provider health based on success
+        current_health = self.provider_health.get(provider, 1.0)
+        if success:
+            # Improve health (back toward 1.0)
+            new_health = min(1.0, current_health + 0.05)
+        else:
+            # Degrade health
+            new_health = max(0.0, current_health - 0.1)
+        
+        self.provider_health[provider] = new_health
+        
+        if new_health < 0.5:
+            self.provider_last_degraded[provider] = datetime.now()
+            logger.warning(f"⚠️ Provider '{provider}' degraded (health: {new_health:.1%})")
+        
+        # Save updated profiles
+        self._save_profiles()
+    
+    def get_provider_recommendation(
+        self,
+        query_type: QueryType,
+        available_providers: List[str]
+    ) -> Dict[str, any]:
+        """Get detailed recommendation for a query type"""
+        recommendations = {}
+        
+        for provider in available_providers:
+            profile = self._get_or_create_profile(provider, query_type)
+            health = self.provider_health.get(provider, 1.0)
+            
+            recommendations[provider] = {
+                "score": profile.get_score(),
+                "success_rate": profile.get_success_rate(),
+                "avg_latency_ms": profile.avg_latency_ms,
+                "p95_latency_ms": profile.p95_latency_ms,
+                "requests_used": profile.total_requests,
+                "health": health,
+                "recommendation": "✅ Excellent" if profile.get_score() > 80 else
+                                 "✓ Good" if profile.get_score() > 50 else
+                                 "⚠️ Fair" if profile.get_score() > 20 else
+                                 "❌ Poor"
+            }
+        
+        return recommendations
+    
+    def get_provider_rankings(self, query_type: QueryType) -> List[Tuple[str, float]]:
+        """Rank providers for a specific query type"""
+        rankings = []
+        
+        for provider, profiles_by_type in self.profiles.items():
+            if query_type in profiles_by_type:
+                profile = profiles_by_type[query_type]
+                health = self.provider_health.get(provider, 1.0)
+                score = profile.get_score() * health
+                rankings.append((provider, score))
+        
+        return sorted(rankings, key=lambda x: x[1], reverse=True)
+    
+    def should_switch_provider(
+        self,
+        current_provider: str,
+        query_type: QueryType
+    ) -> Tuple[bool, Optional[str]]:
+        """
+        Check if we should switch from current provider
+        
+        Returns:
+            (should_switch, better_provider)
+        """
+        current_profile = self._get_or_create_profile(current_provider, query_type)
+        current_health = self.provider_health.get(current_provider, 1.0)
+        current_score = current_profile.get_score() * current_health
+        
+        # If health is very low, definitely switch
+        if current_health < 0.3:
+            rankings = self.get_provider_rankings(query_type)
+            if rankings and rankings[0][0] != current_provider:
+                return True, rankings[0][0]
+        
+        # If there's a significantly better option, switch
+        rankings = self.get_provider_rankings(query_type)
+        for provider, score in rankings[:3]:
+            if provider != current_provider and score > current_score * 1.2:
+                return True, provider
+        
+        return False, None
+    
+    def _get_or_create_profile(
+        self,
+        provider: str,
+        query_type: QueryType
+    ) -> ProviderPerformanceProfile:
+        """Get or create performance profile"""
+        if provider not in self.profiles:
+            self.profiles[provider] = {}
+        
+        if query_type not in self.profiles[provider]:
+            self.profiles[provider][query_type] = ProviderPerformanceProfile(
+                provider_name=provider,
+                query_type=query_type
+            )
+        
+        return self.profiles[provider][query_type]
+    
+    def _load_profiles(self):
+        """Load historical performance data"""
+        profile_file = self.storage_dir / "provider_profiles.json"
+        if not profile_file.exists():
+            return
+        
+        try:
+            with open(profile_file, 'r') as f:
+                data = json.load(f)
+            
+            for provider, query_types in data.items():
+                for query_type_str, profile_data in query_types.items():
+                    try:
+                        query_type = QueryType(query_type_str)
+                        profile = ProviderPerformanceProfile(**profile_data)
+                        
+                        if provider not in self.profiles:
+                            self.profiles[provider] = {}
+                        self.profiles[provider][query_type] = profile
+                    except ValueError:
+                        continue
+            
+            logger.info(f"📥 Loaded {len(self.profiles)} provider profiles")
+        
+        except Exception as e:
+            logger.error(f"Failed to load profiles: {e}")
+    
+    def _save_profiles(self):
+        """Save performance data to disk"""
+        try:
+            profile_file = self.storage_dir / "provider_profiles.json"
+            
+            data = {}
+            for provider, query_types in self.profiles.items():
+                data[provider] = {}
+                for query_type, profile in query_types.items():
+                    data[provider][query_type.value] = {
+                        'provider_name': profile.provider_name,
+                        'query_type': query_type.value,
+                        'total_requests': profile.total_requests,
+                        'successful_requests': profile.successful_requests,
+                        'avg_latency_ms': profile.avg_latency_ms,
+                        'p95_latency_ms': profile.p95_latency_ms,
+                        'accuracy_score': profile.accuracy_score,
+                        'cost_per_request': profile.cost_per_request,
+                    }
+            
+            with open(profile_file, 'w') as f:
+                json.dump(data, f, indent=2)
+        
+        except Exception as e:
+            logger.error(f"Failed to save profiles: {e}")
+    
+    def get_status_message(self) -> str:
+        """Human-readable status"""
+        lines = ["📊 **Provider Selection Status**"]
+        
+        # Provider health
+        if self.provider_health:
+            lines.append("\n🏥 **Provider Health**")
+            for provider, health in sorted(self.provider_health.items()):
+                emoji = "🟢" if health > 0.7 else "🟡" if health > 0.3 else "🔴"
+                lines.append(f"  • {provider}: {emoji} {health:.1%}")
+        
+        # Best providers per query type
+        lines.append("\n⭐ **Best Providers by Query Type**")
+        for query_type in QueryType:
+            rankings = self.get_provider_rankings(query_type)
+            if rankings:
+                best_provider, score = rankings[0]
+                lines.append(f"  • {query_type.value}: {best_provider} (score: {score:.1f})")
+        
+        return "\n".join(lines)
+
+
+# Global instance
+adaptive_selector = AdaptiveProviderSelector()
+
+
+if __name__ == "__main__":
+    # Test the adaptive selector
+    selector = AdaptiveProviderSelector()
+    
+    # Simulate some usage
+    for i in range(20):
+        provider = selector.select_provider(
+            QueryType.CODE_GENERATION,
+            ["cerebras", "groq", "mistral"]
+        )[0]
+        
+        # Simulate result (groq should be slightly better)
+        success = (i % 5) != 0  # 80% success
+        latency = 100 + (i % 10) * 10
+        
+        selector.record_result(provider, QueryType.CODE_GENERATION, success, latency)
+    
+    print(selector.get_status_message())
+    print("\n" + json.dumps(
+        selector.get_provider_recommendation(QueryType.CODE_GENERATION, ["cerebras", "groq"]),
+        indent=2,
+        default=str
+    ))