cite-agent 1.0.0__py3-none-any.whl

cite_agent/updater.py

@@ -0,0 +1,187 @@
+#!/usr/bin/env python3
+"""
+Auto-updater for Nocturnal Archive
+Checks for updates and handles installation
+"""
+
+import json
+import subprocess
+import sys
+import urllib.request
+from pathlib import Path
+from typing import Optional, Dict, Any
+
+try:
+    import pkg_resources
+except ImportError:
+    pkg_resources = None
+
+class NocturnalUpdater:
+    """Handles automatic updates for Nocturnal Archive"""
+    
+    def __init__(self):
+        self.current_version = self.get_current_version()
+        self.package_name = "nocturnal-archive"
+        self.pypi_url = f"https://pypi.org/pypi/{self.package_name}/json"
+        self.kill_switch_url = "https://api.nocturnal.dev/api/admin/status"
+    
+    def check_kill_switch(self) -> Dict[str, Any]:
+        """Check if kill switch is activated"""
+        try:
+            with urllib.request.urlopen(self.kill_switch_url, timeout=5) as response:
+                data = json.loads(response.read().decode())
+                return data
+        except Exception:
+            # If we can't reach the kill switch API, allow operation
+            return {"enabled": True, "message": ""}
+    
+    def get_current_version(self) -> str:
+        """Get current installed version"""
+        if pkg_resources:
+            try:
+                return pkg_resources.get_distribution(self.package_name).version
+            except (pkg_resources.DistributionNotFound, Exception):
+                pass
+        
+        # Fallback: try to get version from installed package
+        try:
+            import nocturnal_archive
+            return getattr(nocturnal_archive, '__version__', '1.0.0')
+        except ImportError:
+            return "1.0.0"
+    
+    def check_for_updates(self) -> Optional[Dict[str, Any]]:
+        """Check if updates are available"""
+        try:
+            with urllib.request.urlopen(self.pypi_url, timeout=10) as response:
+                data = json.loads(response.read().decode())
+                
+            latest_version = data["info"]["version"]
+            
+            if self.is_newer_version(latest_version, self.current_version):
+                return {
+                    "current": self.current_version,
+                    "latest": latest_version,
+                    "available": True,
+                    "release_notes": data["info"].get("description", ""),
+                    "download_url": f"https://pypi.org/project/{self.package_name}/{latest_version}/"
+                }
+            
+            return {
+                "current": self.current_version,
+                "latest": latest_version,
+                "available": False
+            }
+            
+        except urllib.error.HTTPError as e:
+            if e.code == 404:
+                # Package not published to PyPI yet - this is normal for development
+                return {
+                    "available": False,
+                    "current": self.current_version,
+                    "latest": self.current_version,
+                    "note": "Development version (not published to PyPI)"
+                }
+            # Silently ignore other HTTP errors
+            return None
+        except (urllib.error.URLError, Exception):
+            # Silently ignore network errors
+            return None
+    
+    def is_newer_version(self, latest: str, current: str) -> bool:
+        """Check if latest version is newer than current"""
+        try:
+            latest_parts = [int(x) for x in latest.split('.')]
+            current_parts = [int(x) for x in current.split('.')]
+            
+            # Pad with zeros if needed
+            max_len = max(len(latest_parts), len(current_parts))
+            latest_parts.extend([0] * (max_len - len(latest_parts)))
+            current_parts.extend([0] * (max_len - len(current_parts)))
+            
+            return latest_parts > current_parts
+        except:
+            return False
+    
+    def update_package(self, force: bool = False) -> bool:
+        """Update the package to latest version"""
+        try:
+            print("🔄 Updating Nocturnal Archive...")
+            
+            # Check if update is needed
+            if not force:
+                update_info = self.check_for_updates()
+                if not update_info or not update_info["available"]:
+                    print("✅ No updates available")
+                    return True
+            
+            # Perform update
+            cmd = [sys.executable, "-m", "pip", "install", "--upgrade", self.package_name]
+            result = subprocess.run(cmd, capture_output=True, text=True)
+            
+            if result.returncode == 0:
+                new_version = self.get_current_version()
+                print(f"✅ Updated to version {new_version}")
+                return True
+            else:
+                print(f"❌ Update failed: {result.stderr}")
+                return False
+                
+        except Exception as e:
+            print(f"❌ Update error: {e}")
+            return False
+    
+    def show_update_status(self):
+        """Show current update status"""
+        print(f"📦 Current version: {self.current_version}")
+        
+        update_info = self.check_for_updates()
+        if update_info:
+            if update_info["available"]:
+                print(f"🆕 Latest version: {update_info['latest']} (available)")
+                print(f"📥 Download: {update_info['download_url']}")
+            else:
+                print(f"✅ Up to date: {update_info['latest']}")
+        else:
+            print("⚠️ Could not check for updates")
+
+def main():
+    """CLI for updater"""
+    import argparse
+    
+    parser = argparse.ArgumentParser(description="Nocturnal Archive Updater")
+    parser.add_argument("--check", action="store_true", help="Check for updates")
+    parser.add_argument("--update", action="store_true", help="Update to latest version")
+    parser.add_argument("--force", action="store_true", help="Force update even if up to date")
+    parser.add_argument("--status", action="store_true", help="Show update status")
+    
+    args = parser.parse_args()
+    
+    updater = NocturnalUpdater()
+    
+    if args.check:
+        update_info = updater.check_for_updates()
+        if update_info and update_info["available"]:
+            print(f"🆕 Update available: {update_info['current']} → {update_info['latest']}")
+        else:
+            print("✅ No updates available")
+    
+    elif args.update:
+        updater.update_package(force=args.force)
+    
+    elif args.status:
+        updater.show_update_status()
+    
+    else:
+        # Default: check and offer update
+        update_info = updater.check_for_updates()
+        if update_info and update_info["available"]:
+            print(f"🆕 Update available: {update_info['current']} → {update_info['latest']}")
+            response = input("Update now? (y/N): ").strip().lower()
+            if response in ['y', 'yes']:
+                updater.update_package()
+        else:
+            print("✅ No updates available")
+
+if __name__ == "__main__":
+    main()

cite_agent/web_search.py

@@ -0,0 +1,203 @@
+#!/usr/bin/env python3
+"""
+Web Search Integration for Enhanced AI Agent
+Simple wrapper around existing SearchEngine for web browsing capability
+"""
+
+import asyncio
+import logging
+from typing import Dict, Any, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class WebSearchIntegration:
+    """
+    Lightweight web search integration using DuckDuckGo
+    Formats results conversationally for the agent
+    """
+    
+    def __init__(self):
+        """Initialize web search - lazy load SearchEngine to avoid import issues"""
+        self.search_engine = None
+        self._initialized = False
+    
+    async def _ensure_initialized(self):
+        """Lazy initialization of SearchEngine"""
+        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()
+                self._initialized = True
+                logger.info("Web search engine initialized successfully")
+            except Exception as e:
+                logger.error(f"Failed to initialize web search: {e}")
+                self.search_engine = None
+                self._initialized = False
+    
+    async def search_web(
+        self, 
+        query: str, 
+        num_results: int = 5
+    ) -> Dict[str, Any]:
+        """
+        Search the web using DuckDuckGo
+        
+        Args:
+            query: Search query
+            num_results: Number of results to return (1-10)
+        
+        Returns:
+            Dict with 'success', 'results', 'formatted_response'
+        """
+        await self._ensure_initialized()
+        
+        if not self.search_engine:
+            return {
+                "success": False,
+                "error": "Web search unavailable",
+                "formatted_response": (
+                    "I apologize, but web search is temporarily unavailable. "
+                    "I can still help with local data analysis, file operations, "
+                    "and answering questions based on my knowledge."
+                )
+            }
+        
+        try:
+            results = await self.search_engine.web_search(query, num_results=num_results)
+            
+            if not results:
+                return {
+                    "success": True,
+                    "results": [],
+                    "formatted_response": (
+                        f"I searched for '{query}' but didn't find relevant results. "
+                        "Could you rephrase or provide more specific terms?"
+                    )
+                }
+            
+            # Format results conversationally
+            formatted = self._format_conversational_results(query, results)
+            
+            return {
+                "success": True,
+                "results": results,
+                "formatted_response": formatted,
+                "count": len(results)
+            }
+            
+        except Exception as e:
+            logger.error(f"Web search failed: {e}")
+            return {
+                "success": False,
+                "error": str(e),
+                "formatted_response": (
+                    "I encountered an issue while searching the web. "
+                    "Let me try to help using other available resources."
+                )
+            }
+    
+    def _format_conversational_results(
+        self, 
+        query: str, 
+        results: List[Dict[str, Any]]
+    ) -> str:
+        """
+        Format web search results in a natural, conversational way
+        Not as bullet-point list, but as synthesized information
+        
+        Args:
+            query: Original search query
+            results: List of search results
+        
+        Returns:
+            Formatted string for natural conversation
+        """
+        if not results:
+            return f"I couldn't find any results for '{query}'."
+        
+        # Build conversational response
+        response_parts = []
+        
+        # Opening
+        response_parts.append(
+            f"I found {len(results)} relevant results for '{query}':"
+        )
+        response_parts.append("")
+        
+        # Format each result
+        for i, result in enumerate(results, 1):
+            title = result.get("title", "Untitled")
+            url = result.get("url", "")
+            snippet = result.get("snippet", "")
+            
+            # Format naturally
+            response_parts.append(f"**{i}. {title}**")
+            if snippet:
+                response_parts.append(f"   {snippet}")
+            if url:
+                response_parts.append(f"   Source: {url}")
+            response_parts.append("")
+        
+        return "\n".join(response_parts)
+    
+    async def close(self):
+        """Clean up resources"""
+        if self.search_engine:
+            try:
+                await self.search_engine.close()
+            except Exception as e:
+                logger.error(f"Error closing search engine: {e}")
+
+
+# Convenience function for direct usage
+async def search_web_simple(query: str, num_results: int = 5) -> str:
+    """
+    Simple web search that returns formatted string
+    
+    Args:
+        query: Search query
+        num_results: Number of results (1-10)
+    
+    Returns:
+        Formatted search results as string
+    """
+    integration = WebSearchIntegration()
+    try:
+        result = await integration.search_web(query, num_results)
+        return result.get("formatted_response", "No results found.")
+    finally:
+        await integration.close()
+
+
+# Example usage
+async def example_usage():
+    """Example of how to use web search integration"""
+    
+    integration = WebSearchIntegration()
+    
+    # Search for something
+    result = await integration.search_web("Federal Reserve interest rates 2024", num_results=5)
+    
+    if result["success"]:
+        print("✅ Search successful!")
+        print(f"\nFormatted response:\n{result['formatted_response']}")
+        print(f"\nRaw results: {len(result.get('results', []))} items")
+    else:
+        print(f"❌ Search failed: {result.get('error')}")
+    
+    await integration.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(example_usage())

cite_agent-1.0.0.dist-info/METADATA

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: cite-agent
+Version: 1.0.0
+Summary: AI Research Assistant - Backend-Only Distribution
+Home-page: https://github.com/Spectating101/cite-agent
+Author: Cite-Agent Team
+Author-email: contact@citeagent.dev
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: aiohttp>=3.9.0
+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
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Cite-Agent
+
+> A fast, affordable AI research assistant with built-in citation capabilities
+
+**Cite-Agent** is a terminal-based AI assistant designed for research and finance, offering 70B model access at half the cost of comparable services.
+
+---
+
+## 🎯 What is Cite-Agent?
+
+Cite-Agent is an AI-powered research tool that:
+- Answers complex questions using state-of-the-art 70B language models
+- Provides accurate, source-grounded responses (hence "cite")
+- Executes code (Python, R, SQL) for data analysis
+- Operates through a beautiful terminal interface
+- Costs $10/month (vs $20+ for Claude/ChatGPT)
+
+---
+
+## ✨ Key Features
+
+### 🧠 **Powerful AI**
+- Access to Llama 3.3 70B via Cerebras & Groq
+- Multi-provider fallback for 99.9% uptime
+- 50 queries/day (50,000 tokens)
+- 2-5 second response times
+
+### 🎓 **Truth-Seeking**
+- Explicitly designed to correct user errors
+- Admits uncertainty instead of guessing
+- Cites sources and reasoning
+- Anti-appeasement prompts
+
+### 💻 **Code Execution**
+- Python, R, and SQL support
+- Data analysis and visualization
+- Financial calculations
+- Research automation
+
+### 🔒 **Secure & Private**
+- API keys never leave the backend
+- JWT-based authentication
+- Rate limiting per user
+- HTTPS-only communication
+
+### 📊 **Analytics**
+- Track your usage
+- Monitor token consumption
+- View query history
+- Download statistics
+
+---
+
+## 💰 Pricing
+
+| Plan | Price | Queries/Day | Features |
+|------|-------|-------------|----------|
+| **Student** | $10/month (300 NTD) | 50 | Full access |
+| **Public** | $10/month (400 NTD) | 50 | Full access |
+
+**Beta**: First 50 users get 3 months free
+
+---
+
+## 🚀 Quick Start
+
+### For Users
+
+1. **Download** for your OS:
+   - [Windows](https://cite-agent-api.herokuapp.com/api/downloads/windows)
+   - [macOS](https://cite-agent-api.herokuapp.com/api/downloads/macos)
+   - [Linux](https://cite-agent-api.herokuapp.com/api/downloads/linux)
+
+2. **Install** the downloaded package
+
+3. **Run** `cite-agent` in your terminal
+
+4. **Register** with email + password
+
+5. **Start asking questions!**
+
+### For Developers
+
+See [DEVELOPMENT.md](./docs/DEVELOPMENT.md) for setup instructions.
+
+---
+
+## 🏗️ Architecture
+
+```
+User's Machine                Backend (Heroku)              AI Providers
+┌─────────────┐              ┌──────────────┐              ┌──────────┐
+│             │              │              │              │          │
+│   Terminal  │─────────────▶│   FastAPI    │─────────────▶│ Cerebras │
+│     UI      │              │     API      │              │  (70B)   │
+│             │◀─────────────│              │◀─────────────│          │
+│   (cite_    │              │  - Auth      │              └──────────┘
+│   agent/)   │              │  - Rate      │              
+│             │              │    Limiting  │              ┌──────────┐
+└─────────────┘              │  - Analytics │              │          │
+                             │  - Proxy     │─────────────▶│   Groq   │
+                             │              │              │  (70B)   │
+                             └──────────────┘              │          │
+                                    │                      └──────────┘
+                             ┌──────────────┐
+                             │  PostgreSQL  │
+                             │   Database   │
+                             └──────────────┘
+```
+
+### Components
+
+**Frontend (cite_agent/)**
+- Terminal UI using `rich` library
+- JWT authentication
+- Query management
+- Local session storage
+
+**Backend (cite-agent-api/)**
+- FastAPI REST API
+- User authentication & rate limiting
+- Multi-provider LLM routing
+- Analytics & tracking
+- PostgreSQL database
+
+**AI Providers**
+- **Primary**: Cerebras (14,400 RPD × 3 keys = 43,200/day)
+- **Backup**: Groq (1,000 RPD × 3 keys = 3,000/day)
+- **Total capacity**: ~46,000 queries/day
+
+---
+
+## 📖 Documentation
+
+- **[DEVELOPMENT.md](./docs/DEVELOPMENT.md)** - Developer setup guide
+- **[DEPLOYMENT.md](./DEPLOYMENT.md)** - How to deploy (Heroku)
+- **[API_REFERENCE.md](./docs/API_REFERENCE.md)** - API endpoints
+- **[ARCHITECTURE.md](./ARCHITECTURE.md)** - System design details
+- **[ROADMAP.md](./ROADMAP.md)** - Future plans
+
+---
+
+## 🛠️ Tech Stack
+
+**Frontend**
+- Python 3.13+
+- `rich` for terminal UI
+- `httpx` for async HTTP
+- `pydantic` for data validation
+
+**Backend**
+- FastAPI
+- PostgreSQL
+- JWT authentication
+- Multi-provider LLM integration
+
+**AI Providers**
+- Cerebras Inference API
+- Groq Cloud
+- Cloudflare Workers AI (fallback)
+- OpenRouter (fallback)
+
+**Deployment**
+- Heroku (backend + database)
+- GitHub Releases (installers)
+
+---
+
+## 🤝 Contributing
+
+We're not accepting contributions yet (private beta), but stay tuned!
+
+---
+
+## 📜 License
+
+Proprietary - All rights reserved
+
+---
+
+## 📧 Support
+
+- **Email**: s1133958@mail.yzu.edu.tw
+- **Issues**: Coming soon
+- **Documentation**: See `/docs` directory
+
+---
+
+## 🙏 Acknowledgments
+
+- **Cerebras** for generous free tier (14,400 RPD)
+- **Groq** for fast 70B inference
+- **GitHub Student Pack** for free hosting credits
+- **FastAPI** for excellent async framework
+
+---
+
+**Built with ❤️ for researchers and analysts**
+
+*Cite-Agent - Because accuracy matters more than agreeableness*

cite_agent-1.0.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+cite_agent/__distribution__.py,sha256=U7-p-qBMX7WrQD6WWjRC5b-PswXnlrqAox7EYnLogqI,178
+cite_agent/__init__.py,sha256=wAXV2v8nNOmIAd0rh8196ItBl9hHWBVOBl5Re4VB77I,1645
+cite_agent/account_client.py,sha256=_-3QS_gUSRj3689hE1GuEHXgb9JzaXGZ3o6klkuRQ2Y,4876
+cite_agent/agent_backend_only.py,sha256=Rmi3cUCcTMSHRxZu6MK2rZwme5SCfilxqn0BsoIds_U,5375
+cite_agent/ascii_plotting.py,sha256=lk8BaECs6fmjtp4iH12G09-frlRehAN7HLhHt2crers,8570
+cite_agent/auth.py,sha256=CYBNv8r1_wfdhsx-YcWOiXCiKvPBymaMca6w7JV__FQ,9809
+cite_agent/backend_only_client.py,sha256=WqLF8x7aXTro2Q3ehqKMsdCg53s6fNk9Hy86bGxqmmw,2561
+cite_agent/cli.py,sha256=03GMqjKGosrIvHfUlWBQrFEoPZr563EI6rfTX8YDWmc,18526
+cite_agent/cli_enhanced.py,sha256=EAaSw9qtiYRWUXF6_05T19GCXlz9cCSz6n41ASnXIPc,7407
+cite_agent/dashboard.py,sha256=VGV5XQU1PnqvTsxfKMcue3j2ri_nvm9Be6O5aVays_w,10502
+cite_agent/enhanced_ai_agent.py,sha256=Rmi3cUCcTMSHRxZu6MK2rZwme5SCfilxqn0BsoIds_U,5375
+cite_agent/rate_limiter.py,sha256=-0fXx8Tl4zVB4O28n9ojU2weRo-FBF1cJo9Z5jC2LxQ,10908
+cite_agent/setup_config.py,sha256=kNZNr5cZmCXr43rGWNenNJXZ1Kfz7PrdLXpAqxM7WgM,16404
+cite_agent/telemetry.py,sha256=55kXdHvI24ZsEkbFtihcjIfJt2oiSXcEpLzTxQ3KCdQ,2916
+cite_agent/ui.py,sha256=r1OAeY3NSeqhAjJYmEBH9CaennBuibFAz1Mur6YF80E,6134
+cite_agent/updater.py,sha256=kL2GYL1AKoZ9JoTXxFT5_AkvYvObcCrO2sIVyBw9JgU,7057
+cite_agent/web_search.py,sha256=j-BRhT8EBC6BEPgACQPeVwB1SVGKDz4XLM7sowacvSc,6587
+cite_agent-1.0.0.dist-info/licenses/LICENSE,sha256=XJkyO4IymhSUniN1ENY6lLrL2729gn_rbRlFK6_Hi9M,1074
+cite_agent-1.0.0.dist-info/METADATA,sha256=flKpEvukTe-iqaNmp03t32EseZHxed_rf_nKM09_980,6856
+cite_agent-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+cite_agent-1.0.0.dist-info/entry_points.txt,sha256=bJ0u28nFIxQKH1PWQ2ak4PV-FAjhoxTC7YADEdDenFw,83
+cite_agent-1.0.0.dist-info/top_level.txt,sha256=NNfD8pxDZzBK8tjDIpCs2BW9Va-OQ5qUFbEx0SgmyIE,11
+cite_agent-1.0.0.dist-info/RECORD,,

cite_agent-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cite_agent-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+cite-agent = cite_agent.cli:main
+nocturnal = cite_agent.cli:main

cite_agent-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nocturnal Archive
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cite_agent-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cite_agent