Cite-Agent: AI Research Assistant 🚀

Your terminal-based research partner powered by AI. Search 200M+ academic papers, get real-time financial data, analyze datasets, and get clean, citable answers—all without leaving your command line.

✨ Why Cite-Agent?

No more context switching. Stop juggling browser tabs, API docs, and Python scripts. Get research done in one place:

• 🔬 Search 200M+ papers across Semantic Scholar, OpenAlex, PubMed
• � Live financial data from SEC filings, Yahoo Finance
• � Instant data analysis - CSV/Excel → insights in seconds
• 🎯 Truth-seeking AI with confidence scoring and source verification
• ✨ Clean output - no LaTeX gibberish, no formatting artifacts

NEW in v1.5.7: Polished output formatting—numbers look professional, no more decimal spam or weird notation.

🌟 What You Can Do

🔬 Academic Research Made Easy

cite-agent "Find papers on transformer architecture"
cite-agent "What are the latest BERT improvements?"
cite-agent "Compare GPT-3 vs GPT-4 architectures"

• Search 200M+ papers (Semantic Scholar, OpenAlex, PubMed)
• Get abstracts, citations, authors, publication venues
• DOI resolution and metadata extraction
• Multi-source verification

💰 Financial Intelligence

cite-agent "What's Tesla's revenue for 2024?"
cite-agent "Compare Apple and Microsoft P/E ratios"
cite-agent "Show me NVIDIA's earnings trends"

• Real-time stock data via FinSight API
• SEC filings and financial reports
• Company metrics, KPIs, valuation ratios
• Historical analysis and trends

📊 Data Analysis On Demand

cite-agent "Load sales.csv and show top 5 products"
cite-agent "Calculate correlation between age and income"
cite-agent "Plot revenue trends over time"

• CSV, Excel, JSON support
• Statistical analysis (regression, correlation, t-tests)
• Instant visualizations
• Clean, formatted results

🎯 Truth-Seeking AI

• Fact-checking with source verification
• Confidence scoring for every answer
• Multi-language support (English, Chinese, more)
• Temperature-controlled for accuracy (0.2 default)

🔄 Workflow Integration

• Save papers to local library
• Export to BibTeX for Zotero/Mendeley
• Session history and query replay
• Markdown export for notes
• Stay in your terminal—no context switching

🚀 Quick Start

Installation

Option 1: pipx (Recommended - handles PATH automatically)

# 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)

# 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

# Interactive mode
cite-agent

# Single query
cite-agent "Find research papers on machine learning in healthcare"

# Workflow integration (NEW!)
cite-agent "Find BERT paper" --save --format bibtex --copy
cite-agent --library              # View saved papers
cite-agent --export-bibtex        # Export to .bib file
cite-agent --history              # See recent queries

# Get help
cite-agent --help

Python API

import asyncio
from cite_agent import EnhancedNocturnalAgent, ChatRequest

async def main():
    agent = EnhancedNocturnalAgent()
    await agent.initialize()
    
    request = ChatRequest(
        question="What is the current state of AI in healthcare?",
        user_id="user123",
        conversation_id="conv456"
    )
    
    response = await agent.process_request(request)
    print(response.response)
    print(f"Confidence: {response.confidence_score}")
    print(f"Tools used: {response.tools_used}")
    
    await agent.close()

asyncio.run(main())

📖 Documentation

Command Line Interface

Basic Commands

# Show version
cite-agent --version

# Interactive setup
cite-agent --setup

# Show tips
cite-agent --tips

# Check for updates
cite-agent --check-updates

Query Examples

# Academic research
cite-agent "Find papers on transformer architecture"
cite-agent "Verify this citation: Smith, J. (2023). AI in Medicine. Nature, 45(2), 123-145."

# Financial data
cite-agent "What is Apple's current revenue?"
cite-agent "Get Tesla's financial metrics for Q3 2024"

# Fact-checking
cite-agent "Is water's boiling point 100°C at standard pressure?"
cite-agent "Did Shakespeare write Harry Potter?"

# Multi-language
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

The main agent class for programmatic access.

class EnhancedNocturnalAgent:
    async def initialize(self, force_reload: bool = False)
    async def process_request(self, request: ChatRequest) -> ChatResponse
    async def process_request_streaming(self, request: ChatRequest)
    async def search_academic_papers(self, query: str, limit: int = 10) -> Dict[str, Any]
    async def get_financial_data(self, ticker: str, metric: str, limit: int = 12) -> Dict[str, Any]
    async def synthesize_research(self, paper_ids: List[str], max_words: int = 500) -> Dict[str, Any]
    async def close(self)

Data Models

@dataclass
class ChatRequest:
    question: str
    user_id: str = "default"
    conversation_id: str = "default"
    context: Dict[str, Any] = field(default_factory=dict)

@dataclass
class ChatResponse:
    response: str
    tools_used: List[str] = field(default_factory=list)
    reasoning_steps: List[str] = field(default_factory=list)
    model: str = "enhanced-nocturnal-agent"
    timestamp: str = field(default_factory=lambda: datetime.now().isoformat())
    tokens_used: int = 0
    confidence_score: float = 0.0
    execution_results: Dict[str, Any] = field(default_factory=dict)
    api_results: Dict[str, Any] = field(default_factory=dict)
    error_message: Optional[str] = None

API Endpoints

Authentication

• POST /api/auth/register - Register new user
• POST /api/auth/login - User login
• POST /api/auth/refresh - Refresh token
• GET /api/auth/me - Get current user info
• POST /api/auth/logout - Logout user

Research

• POST /api/search - Search academic papers
• POST /api/synthesize - Synthesize research papers
• POST /api/format - Format citations

Financial Data

• GET /v1/finance/calc/{ticker}/{metric} - Get financial metrics
• GET /v1/finance/kpis/{ticker} - Get company KPIs
• GET /v1/finance/reports/{ticker} - Get financial reports

Analytics

• GET /api/download/stats/summary - Download statistics
• GET /api/analytics/overview - Usage overview
• GET /api/analytics/users - User statistics

Download Tracking

• GET /api/download/windows - Track Windows downloads
• GET /api/download/macos - Track macOS downloads
• GET /api/download/linux - Track Linux downloads

🔧 Configuration

Environment Variables

# Authentication
NOCTURNAL_ACCOUNT_EMAIL=your@email.edu
NOCTURNAL_ACCOUNT_PASSWORD=your_password

# API Configuration
NOCTURNAL_API_URL=https://cite-agent-api-720dfadd602c.herokuapp.com
ARCHIVE_API_URL=https://cite-agent-api-720dfadd602c.herokuapp.com/api
FINSIGHT_API_URL=https://cite-agent-api-720dfadd602c.herokuapp.com/v1/finance

# Optional
NOCTURNAL_DEBUG=1  # Enable debug logging
NOCTURNAL_QUERY_LIMIT=25  # Default query limit

Session Management

Sessions are automatically managed and stored in:

• Linux/macOS: ~/.nocturnal_archive/session.json
• Windows: %USERPROFILE%\.nocturnal_archive\session.json

📊 Analytics & Monitoring

User Tracking

The system automatically tracks:

• User registrations and logins
• Query history and usage patterns
• Token consumption and costs
• Response quality and citation accuracy

Download Analytics

Track installer downloads across platforms:

• Windows, macOS, Linux downloads
• Geographic distribution (IP-based)
• Referrer tracking
• Download trends and patterns

Dashboard Access

Access the analytics dashboard at:

https://cite-agent-api-720dfadd602c.herokuapp.com/dashboard

💰 Monetization & Pricing

Current Pricing Tiers

Revenue Model

• Subscription-based: Monthly recurring revenue
• Usage-based: Pay-per-query options available
• API licensing: Enterprise customers
• White-label: Custom deployments

🛠️ Development

Local Development

# Clone repository
git clone https://github.com/yourusername/cite-agent.git
cd cite-agent

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Run tests
pytest

# Start development server
python -m cite_agent.dashboard

Building from Source

# Build wheel
python setup.py bdist_wheel

# Install locally
pip install dist/cite_agent-1.0.5-py3-none-any.whl

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

🔒 Security & Privacy

Data Protection

• All user data encrypted in transit and at rest
• JWT-based authentication with 30-day expiration
• No storage of sensitive personal information
• GDPR compliant data handling

API Security

• Rate limiting per user tier
• Input validation and sanitization
• SQL injection prevention
• CORS protection

📈 Performance

Benchmarks

• Average response time: 2-5 seconds
• Citation verification: 95%+ accuracy
• Uptime: 99.9% SLA
• Concurrent users: 1000+ supported

Optimization

• Async/await architecture
• Connection pooling
• Response caching
• CDN distribution

🐛 Troubleshooting

Common Issues

CLI Hangs on Startup

# Clear session and reconfigure
rm -rf ~/.nocturnal_archive
cite-agent --setup

Authentication Errors

# Check credentials
cite-agent --setup

# Verify email format (must be academic)
# Valid: user@university.edu, student@ac.uk
# Invalid: user@gmail.com, user@company.com

API Connection Issues

# Check network connectivity
curl https://cite-agent-api-720dfadd602c.herokuapp.com/api/health

# Verify API keys
echo $NOCTURNAL_ACCOUNT_EMAIL

Debug Mode

# Enable debug logging
export NOCTURNAL_DEBUG=1
cite-agent "your query"

Support

• Documentation: Full docs
• Issues: GitHub Issues
• Email: support@cite-agent.com
• Discord: Community Server

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• OpenAlex for academic data
• Semantic Scholar for research papers
• FinSight for financial data
• Groq for LLM processing
• FastAPI for the backend framework

📞 Contact

• Website: https://cite-agent.com
• Email: contact@cite-agent.com
• Twitter: @cite_agent
• LinkedIn: Cite-Agent

Made with ❤️ for the research community