cite-agent 1.2.5__tar.gz → 1.2.7__tar.gz

{cite_agent-1.2.5/cite_agent.egg-info → cite_agent-1.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cite-agent
-Version: 1.2.5
+Version: 1.2.7
 Summary: Terminal AI assistant for academic research with citation verification
 Home-page: https://github.com/Spectating101/cite-agent
 Author: Cite-Agent Team
@@ -23,6 +23,7 @@ Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: pydantic>=2.5.0
 Requires-Dist: rich>=13.7.0
 Requires-Dist: keyring>=24.3.0
+Requires-Dist: ddgs>=1.0.0
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -36,7 +37,7 @@ Dynamic: summary
 
 # Cite-Agent: AI Research Assistant
 
-[![Version](https://img.shields.io/badge/version-1.2.0-blue.svg)](https://pypi.org/project/cite-agent/)
+[![Version](https://img.shields.io/badge/version-1.2.6-blue.svg)](https://pypi.org/project/cite-agent/)
 [![Python](https://img.shields.io/badge/python-3.8+-green.svg)](https://python.org)
 [![License](https://img.shields.io/badge/license-MIT-orange.svg)](LICENSE)
 
@@ -80,10 +81,34 @@ Dynamic: summary
 
 ### Installation
 
+**Option 1: pipx (Recommended - handles PATH automatically)**
 ```bash
-pip install cite-agent
+# Install pipx if you don't have it
+pip install --user pipx
+python3 -m pipx ensurepath
+
+# Install cite-agent
+pipx install cite-agent
+
+# Ready to use (no PATH setup needed)
+cite-agent --version
+```
+
+**Option 2: pip (requires PATH setup)**
+```bash
+# Install
+pip install --user cite-agent
+
+# Add to PATH (one-time setup)
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+
+# Ready to use
+cite-agent --version
 ```
 
+**If cite-agent command not found:** Run `python3 -m cite_agent.cli` instead.
+
 ### Basic Usage
 
 ```bash

{cite_agent-1.2.5 → cite_agent-1.2.7}/README.md

@@ -1,6 +1,6 @@
 # Cite-Agent: AI Research Assistant
 
-[![Version](https://img.shields.io/badge/version-1.2.0-blue.svg)](https://pypi.org/project/cite-agent/)
+[![Version](https://img.shields.io/badge/version-1.2.6-blue.svg)](https://pypi.org/project/cite-agent/)
 [![Python](https://img.shields.io/badge/python-3.8+-green.svg)](https://python.org)
 [![License](https://img.shields.io/badge/license-MIT-orange.svg)](LICENSE)
 
@@ -44,10 +44,34 @@
 
 ### Installation
 
+**Option 1: pipx (Recommended - handles PATH automatically)**
 ```bash
-pip install cite-agent
+# Install pipx if you don't have it
+pip install --user pipx
+python3 -m pipx ensurepath
+
+# Install cite-agent
+pipx install cite-agent
+
+# Ready to use (no PATH setup needed)
+cite-agent --version
+```
+
+**Option 2: pip (requires PATH setup)**
+```bash
+# Install
+pip install --user cite-agent
+
+# Add to PATH (one-time setup)
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+
+# Ready to use
+cite-agent --version
 ```
 
+**If cite-agent command not found:** Run `python3 -m cite_agent.cli` instead.
+
 ### Basic Usage
 
 ```bash

cite_agent-1.2.7/cite_agent/__main__.py

@@ -0,0 +1,11 @@
+#!/usr/bin/env python3
+"""
+Entry point for python -m cite_agent
+Allows running: python3 -m cite_agent
+"""
+
+from cite_agent.cli import main
+
+if __name__ == "__main__":
+    main()
+

cite_agent-1.2.7/cite_agent/__version__.py

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

{cite_agent-1.2.5 → cite_agent-1.2.7}/cite_agent/cli.py

@@ -95,10 +95,15 @@ class NocturnalCLI:
             from pathlib import Path
             session_file = Path.home() / ".nocturnal_archive" / "session.json"
             has_env_creds = os.getenv("NOCTURNAL_ACCOUNT_EMAIL") and os.getenv("NOCTURNAL_ACCOUNT_PASSWORD")
+            use_local_keys = os.getenv("USE_LOCAL_KEYS", "").lower() == "true"
             
-            if session_file.exists() or has_env_creds:
-                # Skip interactive setup if session exists or env vars present
-                self.console.print("[success]⚙️  Using saved credentials.[/success]")
+            if session_file.exists() or has_env_creds or use_local_keys:
+                # Skip interactive setup if session exists, env vars present, or using local keys
+                if use_local_keys and not session_file.exists():
+                    # Only show dev mode if explicitly in dev mode (no session)
+                    self.console.print("[success]⚙️  Dev mode - using local API keys.[/success]")
+                else:
+                    self.console.print("[success]⚙️  Using saved credentials.[/success]")
             else:
                 # Need interactive setup
                 if non_interactive:
@@ -604,6 +609,16 @@ class NocturnalCLI:
 
 def main():
     """Main CLI entry point"""
+    # Check if ~/.local/bin is in PATH and warn if not
+    import sys
+    from pathlib import Path
+    local_bin = Path.home() / ".local" / "bin"
+    if local_bin.exists() and str(local_bin) not in os.environ.get("PATH", ""):
+        print("⚠️  NOTE: ~/.local/bin is not in your PATH")
+        print("   Add this to ~/.bashrc or ~/.zshrc:")
+        print('   export PATH="$HOME/.local/bin:$PATH"')
+        print("")
+    
     parser = argparse.ArgumentParser(
         description="Cite Agent - AI Research Assistant with real data",
         formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -743,7 +758,7 @@ Examples:
     
     # Handle version
     if args.version:
-        print("Cite Agent v1.2.5")
+        print("Cite Agent v1.2.7")
         print("AI Research Assistant with real data integration")
         return
 

{cite_agent-1.2.5 → cite_agent-1.2.7}/cite_agent/enhanced_ai_agent.py

@@ -72,6 +72,14 @@ class EnhancedNocturnalAgent:
         self.daily_limit = 100000
         self.daily_query_limit = self._resolve_daily_query_limit()
         self.per_user_query_limit = self.daily_query_limit
+        
+        # Initialize web search for fallback
+        self.web_search = None
+        try:
+            from .web_search import WebSearchIntegration
+            self.web_search = WebSearchIntegration()
+        except Exception:
+            pass  # Web search optional
         self.daily_query_count = 0
         self.total_cost = 0.0
         self.cost_per_1k_tokens = 0.0001  # Groq pricing estimate
@@ -477,12 +485,17 @@ class EnhancedNocturnalAgent:
 
         try:
             from dotenv import load_dotenv
-
-            load_dotenv('.env.local')
+            from pathlib import Path
+            
+            # ONLY load from user's config directory (never from cwd/project root)
+            # Project .env.local is for developers, not end users
+            env_local = Path.home() / ".nocturnal_archive" / ".env.local"
+            if env_local.exists():
+                load_dotenv(env_local, override=False)  # Don't override existing env vars
         except ImportError:
-            print("⚠️ python-dotenv not installed, using system environment variables")
+            pass  # python-dotenv not installed
         except Exception as exc:
-            print(f"⚠️ Could not load .env.local: {exc}")
+            pass  # Silently fail - not critical
         finally:
             self._env_loaded = True
 
@@ -856,7 +869,7 @@ class EnhancedNocturnalAgent:
             serialized = json.dumps(api_results, indent=2)
         except Exception:
             serialized = str(api_results)
-        max_len = 8000  # Keep under 12K token limit (backend + context)
+        max_len = 3000  # Aggressive limit to prevent token explosion
         if len(serialized) > max_len:
             serialized = serialized[:max_len] + "\n... (truncated for length)"
 
@@ -896,12 +909,24 @@ class EnhancedNocturnalAgent:
                 "You have access to production data sources and can write/execute code (Python, R, SQL)."
             )
         else:  # quantitative
-            intro = (
-                "You are Cite Agent, a truth-seeking research and finance AI. "
-                "PRIMARY DIRECTIVE: Accuracy > Agreeableness. Ask clarifying questions when context is missing. "
-                "You are a fact-checker and analyst, NOT a people-pleaser. "
-                "You have direct access to production-grade data sources and can write/execute code (Python, R, SQL)."
-            )
+            # Check if we're in dev mode (has local LLM client)
+            dev_mode = self.client is not None
+            
+            if dev_mode:
+                intro = (
+                    "You are Cite Agent, a data analysis and research assistant with CODE EXECUTION. "
+                    "PRIMARY DIRECTIVE: Execute code when needed. You have a persistent shell session. "
+                    "When user asks for data analysis, calculations, or file operations: WRITE and EXECUTE the code. "
+                    "Languages available: Python, R, SQL, Bash. "
+                    "You can read files, run scripts, perform calculations, and show results."
+                )
+            else:
+                intro = (
+                    "You are Cite Agent, a truth-seeking research and finance AI. "
+                    "PRIMARY DIRECTIVE: Accuracy > Agreeableness. Ask clarifying questions when context is missing. "
+                    "You are a fact-checker and analyst, NOT a people-pleaser. "
+                    "You have access to research (Archive) and financial data (FinSight SEC filings)."
+                )
         
         sections.append(intro)
 
@@ -930,16 +955,20 @@ class EnhancedNocturnalAgent:
 
         # ENHANCED TRUTH-SEEKING RULES (adapt based on mode)
         base_rules = [
-            "🚨 BE PATIENT: Don't rush to tools. Have a conversation to understand intent FIRST.",
-            "🚨 CLARIFY BEFORE SEARCH: If you see '2008, 2015, 2019' → ask 'Are you looking for crisis patterns? Economic events? Papers published in those years?' DON'T just search '2008'.",
-            "🚨 KNOW YOUR TOOLS' LIMITS: SEC has revenue, not market share. Archive has papers, not market data. If tool can't answer, say 'I don't have that data' or use web search.",
-            "🚨 TOOL != ANSWER: Don't use tools just because you have them. Revenue ≠ Market Share. Published year ≠ Subject matter.",
+            "🚨 BE RESOURCEFUL: You have Archive, FinSight (SEC+Yahoo), and Web Search. USE them to find answers.",
+            "🚨 TRY TOOLS FIRST: Before asking user for clarification, try your tools to find the answer.",
+            "🚨 WEB SEARCH IS YOUR FRIEND: Market share? Industry size? Current prices? → Web search can find it.",
+            "🚨 ONLY ask clarification if tools can't help AND query is truly ambiguous.",
+            "",
+            "💬 AUTONOMOUS FLOW:",
+            "1. User asks question → YOU use tools to find data",
+            "2. If partial data → YOU web search for missing pieces",  
+            "3. YOU synthesize → Present complete answer",
+            "4. ONLY if impossible → Ask for clarification",
             "",
-            "💬 CONVERSATIONAL FLOW:",
-            "1. User asks vague question → YOU ask clarifying questions",
-            "2. User provides context → YOU confirm understanding",
-            "3. YOU make tool calls → Present results",
-            "NEVER skip step 1 or 2. Be deliberate, not eager.",
+            "Examples:",
+            "❌ BAD: 'Snowflake market share?' → 'Which market?' (when web search can tell you!)",
+            "✅ GOOD: 'Snowflake market share?' → [web search] → '18.33% in cloud data warehouses'",
             "",
             "🚨 ANTI-APPEASEMENT: If user states something incorrect, CORRECT THEM immediately. Do not agree to be polite.",
             "🚨 UNCERTAINTY: If you're uncertain, SAY SO explicitly. 'I don't know' is better than a wrong answer.",
@@ -1407,18 +1436,23 @@ class EnhancedNocturnalAgent:
             # DISABLED for beta testing - set USE_LOCAL_KEYS=false to enable backend-only mode
 
             # SECURITY: Production users MUST use backend for monetization
-            # Dev mode only available via undocumented env var (not in user docs)
+            # Priority: 1) Session exists → backend, 2) USE_LOCAL_KEYS → dev mode
+            from pathlib import Path
+            session_file = Path.home() / ".nocturnal_archive" / "session.json"
+            has_session = session_file.exists()
             use_local_keys_env = os.getenv("USE_LOCAL_KEYS", "").lower()
 
-            if use_local_keys_env == "true":
-                # Dev mode - use local keys
+            if has_session:
+                # Session exists → ALWAYS use backend mode (ignore USE_LOCAL_KEYS)
+                use_local_keys = False
+            elif use_local_keys_env == "true":
+                # No session but dev mode requested → use local keys
                 use_local_keys = True
             elif use_local_keys_env == "false":
                 # Explicit backend mode
                 use_local_keys = False
             else:
                 # Default: Always use backend (for monetization)
-                # Even if session doesn't exist, we'll prompt for login
                 use_local_keys = False
 
             if not use_local_keys:
@@ -1986,59 +2020,61 @@ class EnhancedNocturnalAgent:
         return results
     
     def execute_command(self, command: str) -> str:
-        """Execute command in persistent shell session and return output"""
+        """Execute command and return output - improved with echo markers"""
         try:
             if self.shell_session is None:
                 return "ERROR: Shell session not initialized"
             
-            # Send command to persistent shell
-            self.shell_session.stdin.write(command + '\n')
-            self.shell_session.stdin.flush()
+            # Clean command - remove natural language prefixes
+            command = command.strip()
+            prefixes_to_remove = [
+                'run this bash:', 'execute this:', 'run command:', 'execute:', 
+                'run this:', 'run:', 'bash:', 'command:', 'this bash:', 'this:',
+                'r code to', 'R code to', 'python code to', 'in r:', 'in R:',
+                'in python:', 'in bash:', 'with r:', 'with bash:'
+            ]
+            for prefix in prefixes_to_remove:
+                if command.lower().startswith(prefix.lower()):
+                    command = command[len(prefix):].strip()
+                    # Try again in case of nested prefixes
+                    for prefix2 in prefixes_to_remove:
+                        if command.lower().startswith(prefix2.lower()):
+                            command = command[len(prefix2):].strip()
+                            break
+                    break
             
-            # Read output with timeout
-            try:
-                import select
-                use_select = True
-            except ImportError:
-                # Windows doesn't have select module
-                use_select = False
+            # Use echo markers to detect when command is done
+            import uuid
+            marker = f"CMD_DONE_{uuid.uuid4().hex[:8]}"
+            
+            # Send command with marker
+            full_command = f"{command}; echo '{marker}'\n"
+            self.shell_session.stdin.write(full_command)
+            self.shell_session.stdin.flush()
             
+            # Read until we see the marker
             output_lines = []
             start_time = time.time()
-            timeout = 10  # seconds
+            timeout = 30  # Increased for R scripts
             
-            if use_select:
-                while time.time() - start_time < timeout:
-                    if select.select([self.shell_session.stdout], [], [], 0.1)[0]:
-                        line = self.shell_session.stdout.readline()
-                        if line:
-                            output_lines.append(line.rstrip())
-                        else:
-                            break
-                    else:
-                        # No more output available
+            while time.time() - start_time < timeout:
+                try:
+                    line = self.shell_session.stdout.readline()
+                    if not line:
                         break
-            else:
-                # Fallback for Windows - simpler approach
-                import threading
-                
-                def read_output():
-                    try:
-                        while True:
-                            line = self.shell_session.stdout.readline()
-                            if line:
-                                output_lines.append(line.rstrip())
-                            else:
-                                break
-                    except:
-                        pass
-                
-                reader_thread = threading.Thread(target=read_output, daemon=True)
-                reader_thread.start()
-                reader_thread.join(timeout=timeout)
+                    
+                    line = line.rstrip()
+                    
+                    # Check if we hit the marker
+                    if marker in line:
+                        break
+                    
+                    output_lines.append(line)
+                except Exception:
+                    break
             
-            output = '\n'.join(output_lines)
-            return output if output else "Command executed successfully"
+            output = '\n'.join(output_lines).strip()
+            return output if output else "Command executed (no output)"
             
         except Exception as e:
             return f"ERROR: {e}"
@@ -2515,21 +2551,30 @@ class EnhancedNocturnalAgent:
             if debug_mode:
                 print(f"🔍 Request analysis: {request_analysis}")
             
-            # Check if query is too vague - skip API calls to save tokens
+            # Check if query is too vague - skip EXPENSIVE API calls to save tokens
+            # But still allow web search (cheap and flexible)
             is_vague = self._is_query_too_vague_for_apis(request.question)
             if debug_mode and is_vague:
-                print(f"🔍 Query detected as VAGUE - skipping API calls, asking for clarification")
+                print(f"🔍 Query detected as VAGUE - skipping Archive/FinSight, but may use web search")
             
             # Call appropriate APIs (Archive, FinSight) - BOTH production and dev mode
             api_results = {}
             tools_used = []
             
-            # Skip API calls if query is too vague
+            # Skip Archive/FinSight if query is too vague, but still allow web search later
             if not is_vague:
                 # Archive API for research
                 if "archive" in request_analysis.get("apis", []):
-                    result = await self.search_academic_papers(request.question, 5)
+                    result = await self.search_academic_papers(request.question, 3)  # Reduced from 5 to save tokens
                     if "error" not in result:
+                        # Strip abstracts to save tokens - only keep essential fields
+                        if "results" in result:
+                            for paper in result["results"]:
+                                # Remove heavy fields
+                                paper.pop("abstract", None)
+                                paper.pop("tldr", None)
+                                paper.pop("full_text", None)
+                                # Keep only: title, authors, year, doi, url
                         api_results["research"] = result
                         tools_used.append("archive_api")
                 
@@ -2552,10 +2597,25 @@ class EnhancedNocturnalAgent:
                         print(f"🔍 Extracted tickers: {tickers}")
                     
                     if tickers:
-                        # Call FinSight with proper endpoint format
+                        # Detect what metric user is asking for
+                        question_lower = request.question.lower()
+                        metric = "revenue"  # Default
+                        
+                        if any(word in question_lower for word in ['market cap', 'marketcap', 'market value', 'valuation']):
+                            metric = "marketCap"
+                        elif any(word in question_lower for word in ['stock price', 'share price', 'current price', 'trading at']):
+                            metric = "price"
+                        elif 'profit' in question_lower and 'gross' not in question_lower:
+                            metric = "netIncome"
+                        elif 'earnings' in question_lower or 'eps' in question_lower:
+                            metric = "eps"
+                        elif any(word in question_lower for word in ['cash flow', 'cashflow']):
+                            metric = "freeCashFlow"
+                        
+                        # Call FinSight with detected metric
                         if debug_mode:
-                            print(f"🔍 Calling FinSight API: calc/{tickers[0]}/revenue")
-                        financial_data = await self._call_finsight_api(f"calc/{tickers[0]}/revenue")
+                            print(f"🔍 Calling FinSight API: calc/{tickers[0]}/{metric}")
+                        financial_data = await self._call_finsight_api(f"calc/{tickers[0]}/{metric}")
                         if debug_mode:
                             print(f"🔍 FinSight returned: {list(financial_data.keys()) if financial_data else None}")
                         if financial_data and "error" not in financial_data:
@@ -2565,6 +2625,35 @@ class EnhancedNocturnalAgent:
                             if debug_mode and financial_data:
                                 print(f"🔍 FinSight error: {financial_data.get('error')}")
             
+            # Web Search fallback - ALWAYS available even for vague queries
+            # Use for: market share, industry data, current events, prices, anything not in APIs
+            if self.web_search:
+                question_lower = request.question.lower()
+                # Only search if query needs data and APIs didn't provide it
+                needs_web_search = (
+                    ('market share' in question_lower) or
+                    ('market size' in question_lower) or
+                    ('industry' in question_lower and not api_results.get('research')) or
+                    ('price' in question_lower and ('today' in question_lower or 'current' in question_lower or 'now' in question_lower)) or
+                    ('bitcoin' in question_lower or 'btc' in question_lower or 'crypto' in question_lower) or
+                    ('exchange rate' in question_lower or 'forex' in question_lower) or
+                    (not api_results and 'latest' in question_lower)  # Latest news/data
+                )
+                
+                if needs_web_search or (not api_results and len(request.question.split()) > 5):
+                    try:
+                        if debug_mode:
+                            print(f"🔍 Using web search for: {request.question[:50]}...")
+                        web_results = await self.web_search.search_web(request.question, num_results=3)
+                        if web_results and "results" in web_results:
+                            api_results["web_search"] = web_results
+                            tools_used.append("web_search")
+                            if debug_mode:
+                                print(f"🔍 Web search returned: {len(web_results.get('results', []))} results")
+                    except Exception as e:
+                        if debug_mode:
+                            print(f"🔍 Web search failed: {e}")
+            
             # PRODUCTION MODE: Send to backend LLM with API results
             if self.client is None:
                 return await self.call_backend_query(

{cite_agent-1.2.5 → cite_agent-1.2.7}/cite_agent/session_manager.py

@@ -179,17 +179,36 @@ class SessionManager:
     
     def setup_environment_variables(self):
         """Set up environment variables for backend mode"""
-        # PRODUCTION MODE: Force backend, ensure monetization
-        # NEVER load user's .env files in production
-        
-        # Set backend URL if not already set
-        if "NOCTURNAL_API_URL" not in os.environ:
-            os.environ["NOCTURNAL_API_URL"] = "https://cite-agent-api-720dfadd602c.herokuapp.com/api"
-        
-        # SECURITY: Default to backend mode (USE_LOCAL_KEYS=false)
-        # This ensures users MUST authenticate and pay
-        if "USE_LOCAL_KEYS" not in os.environ:
-            os.environ["USE_LOCAL_KEYS"] = "false"
+        # Load .env.local FIRST if it exists (for dev mode)
+        try:
+            from dotenv import load_dotenv
+            from pathlib import Path
+            env_local = Path.home() / ".nocturnal_archive" / ".env.local"
+            if env_local.exists():
+                load_dotenv(env_local)
+                import os
+                debug = os.getenv("NOCTURNAL_DEBUG", "").lower() == "1"
+                if debug:
+                    print(f"🔍 Loaded .env.local: USE_LOCAL_KEYS={os.getenv('USE_LOCAL_KEYS')}")
+        except Exception as e:
+            import os
+            debug = os.getenv("NOCTURNAL_DEBUG", "").lower() == "1"
+            if debug:
+                print(f"⚠️ Failed to load .env.local: {e}")
+        
+        # Check if dev mode is enabled
+        dev_mode = os.getenv("CITE_AGENT_DEV_MODE", "").lower() == "true"
+        
+        if not dev_mode:
+            # PRODUCTION MODE: Force backend, ensure monetization
+            # Set backend URL if not already set
+            if "NOCTURNAL_API_URL" not in os.environ:
+                os.environ["NOCTURNAL_API_URL"] = "https://cite-agent-api-720dfadd602c.herokuapp.com/api"
+            
+            # SECURITY: Default to backend mode (USE_LOCAL_KEYS=false)
+            # This ensures users MUST authenticate and pay
+            if "USE_LOCAL_KEYS" not in os.environ:
+                os.environ["USE_LOCAL_KEYS"] = "false"
     
     def get_session_status(self) -> Dict[str, Any]:
         """Get current session status for debugging"""

{cite_agent-1.2.5 → cite_agent-1.2.7}/cite_agent/web_search.py

@@ -23,23 +23,14 @@ class WebSearchIntegration:
         self._initialized = False
     
     async def _ensure_initialized(self):
-        """Lazy initialization of SearchEngine"""
+        """Lazy initialization with duckduckgo-search"""
         if not self._initialized:
             try:
-                # Import here to avoid circular dependencies
-                import sys
-                from pathlib import Path
-                
-                # Add src to path if needed
-                repo_root = Path(__file__).parent.parent.parent
-                src_path = repo_root / "src"
-                if str(src_path) not in sys.path:
-                    sys.path.insert(0, str(src_path))
-                
-                from services.search_service.search_engine import SearchEngine
-                self.search_engine = SearchEngine()
+                # Use ddgs (duckduckgo search)
+                from ddgs import DDGS
+                self.search_engine = DDGS()
                 self._initialized = True
-                logger.info("Web search engine initialized successfully")
+                logger.info("Web search engine initialized (DuckDuckGo)")
             except Exception as e:
                 logger.error(f"Failed to initialize web search: {e}")
                 self.search_engine = None
@@ -74,9 +65,17 @@ class WebSearchIntegration:
             }
         
         try:
-            results = await self.search_engine.web_search(query, num_results=num_results)
+            # Use DDGS.text() for web search
+            results_list = []
+            for result in self.search_engine.text(query, max_results=num_results):
+                results_list.append({
+                    "title": result.get("title", ""),
+                    "url": result.get("href", ""),
+                    "snippet": result.get("body", ""),
+                    "source": "DuckDuckGo"
+                })
             
-            if not results:
+            if not results_list:
                 return {
                     "success": True,
                     "results": [],
@@ -87,13 +86,13 @@ class WebSearchIntegration:
                 }
             
             # Format results conversationally
-            formatted = self._format_conversational_results(query, results)
+            formatted = self._format_conversational_results(query, results_list)
             
             return {
                 "success": True,
-                "results": results,
+                "results": results_list,
                 "formatted_response": formatted,
-                "count": len(results)
+                "count": len(results_list)
             }
             
         except Exception as e:

{cite_agent-1.2.5 → cite_agent-1.2.7/cite_agent.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cite-agent
-Version: 1.2.5
+Version: 1.2.7
 Summary: Terminal AI assistant for academic research with citation verification
 Home-page: https://github.com/Spectating101/cite-agent
 Author: Cite-Agent Team
@@ -23,6 +23,7 @@ Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: pydantic>=2.5.0
 Requires-Dist: rich>=13.7.0
 Requires-Dist: keyring>=24.3.0
+Requires-Dist: ddgs>=1.0.0
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -36,7 +37,7 @@ Dynamic: summary
 
 # Cite-Agent: AI Research Assistant
 
-[![Version](https://img.shields.io/badge/version-1.2.0-blue.svg)](https://pypi.org/project/cite-agent/)
+[![Version](https://img.shields.io/badge/version-1.2.6-blue.svg)](https://pypi.org/project/cite-agent/)
 [![Python](https://img.shields.io/badge/python-3.8+-green.svg)](https://python.org)
 [![License](https://img.shields.io/badge/license-MIT-orange.svg)](LICENSE)
 
@@ -80,10 +81,34 @@ Dynamic: summary
 
 ### Installation
 
+**Option 1: pipx (Recommended - handles PATH automatically)**
 ```bash
-pip install cite-agent
+# Install pipx if you don't have it
+pip install --user pipx
+python3 -m pipx ensurepath
+
+# Install cite-agent
+pipx install cite-agent
+
+# Ready to use (no PATH setup needed)
+cite-agent --version
+```
+
+**Option 2: pip (requires PATH setup)**
+```bash
+# Install
+pip install --user cite-agent
+
+# Add to PATH (one-time setup)
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+
+# Ready to use
+cite-agent --version
 ```
 
+**If cite-agent command not found:** Run `python3 -m cite_agent.cli` instead.
+
 ### Basic Usage
 
 ```bash

{cite_agent-1.2.5 → cite_agent-1.2.7}/cite_agent.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ requirements-dev.txt
 requirements.txt
 setup.py
 cite_agent/__init__.py
+cite_agent/__main__.py
 cite_agent/__version__.py
 cite_agent/account_client.py
 cite_agent/agent_backend_only.py

{cite_agent-1.2.5 → cite_agent-1.2.7}/cite_agent.egg-info/requires.txt

@@ -6,3 +6,4 @@ python-dotenv>=1.0.0
 pydantic>=2.5.0
 rich>=13.7.0
 keyring>=24.3.0
+ddgs>=1.0.0

{cite_agent-1.2.5 → cite_agent-1.2.7}/setup.py

@@ -7,7 +7,7 @@ long_description = readme_path.read_text() if readme_path.exists() else "Termina
 
 setup(
     name="cite-agent",
-    version="1.2.5",
+    version="1.2.7",
     author="Cite-Agent Team",
     author_email="contact@citeagent.dev",
     description="Terminal AI assistant for academic research with citation verification",
@@ -34,6 +34,7 @@ setup(
         "pydantic>=2.5.0",
         "rich>=13.7.0",
         "keyring>=24.3.0",
+        "ddgs>=1.0.0",  # For web search fallback (DuckDuckGo)
     ],
     entry_points={
         "console_scripts": [

cite_agent-1.2.5/cite_agent/__version__.py

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