findEthics/Atlas

1---2title: Atlas - AI Chat API3emoji: 🤖4colorFrom: blue5colorTo: purple6sdk: docker7sdk_version: "4.36.0"8app_file: app.py9pinned: false10---11 12# Atlas - AI Chat API with Anonymous & Authenticated Modes13 14Atlas is an enhanced chat API service that provides intelligent question-answering capabilities with web search augmentation and comprehensive analytics. It supports both anonymous usage (no authentication required) and authenticated user tracking.15 16## 🚀 Quick Start (Anonymous Mode)17 18Get started immediately without any setup or authentication:19 20```bash21# Simple anonymous chat request22curl -X POST https://your-atlas-api.com/chat \23  -H "Content-Type: application/json" \24  -d '{25    "prompt": "What is artificial intelligence?",26    "use_search": true27  }'28```29 30## 📋 Features31 32### 🤖 AI-Powered Chat33- Uses Google's Gemini 1.5 Flash model34- Configurable parameters (temperature, max tokens)35- Intelligent responses based on web search results36- Session-based conversation tracking37 38### 🔍 Advanced Web Search & Optimization39- **Dual Search Engine Strategy**: Brave Search + DuckDuckGo40- **Resilient Fallback**: Automatic fallback if one engine fails41- **Smart Query Extraction**: NLP-powered search term extraction using spaCy and RAKE42- **Deduplication**: Removes duplicate results across engines43- **🧠 Intelligent Search Optimization**: AI-powered search decision engine44- **⚡ Context-Aware Flow**: Cache-first for new conversations, smart decisions for follow-ups45- **🗄️ ChromaDB Vector Caching**: Semantic similarity matching with persistent storage46- **📊 Search Analytics**: Comprehensive search decision and performance tracking47 48### 👤 Flexible User Modes49- **Anonymous Mode**: Use immediately without authentication50- **Authenticated Mode**: User tracking and personalized history51- **Progressive Enhancement**: Start anonymous, add auth later52- **Privacy-First**: No tracking in anonymous mode53 54### 📊 Comprehensive Analytics55- **Real-time Session Tracking**: Monitor user sessions and activity56- **Message Analytics**: Track response times, search usage, and success rates57- **Interactive Dashboard**: Beautiful HTML dashboard with charts and metrics58- **Data Export**: Export analytics data in JSON or CSV format59- **Anonymous vs Authenticated**: Separate tracking for different user modes60 61## 🔧 API Usage Examples62 63### Anonymous Usage (No Authentication)64 65**Basic Request:**66```javascript67const response = await fetch('/chat', {68  method: 'POST',69  headers: { 'Content-Type': 'application/json' },70  body: JSON.stringify({71    prompt: "Explain quantum computing",72    use_search: true73  })74});75```76 77**With Conversation History:**78```javascript79const response = await fetch('/chat', {80  method: 'POST',81  headers: { 'Content-Type': 'application/json' },82  body: JSON.stringify({83    prompt: "Can you elaborate on that?",84    use_search: false,85    history: [86      {role: "user", content: "What is machine learning?"},87      {role: "assistant", content: "Machine learning is..."}88    ]89  })90});91```92 93**With Search Optimization Controls:**94```javascript95const response = await fetch('/chat', {96  method: 'POST',97  headers: { 'Content-Type': 'application/json' },98  body: JSON.stringify({99    prompt: "What are the latest AI developments?",100    use_search: true,101    search_decision_mode: "aggressive", // "conservative", "balanced", "aggressive"102    force_search: true // Override smart search optimization103  })104});105```106 107### Authenticated Usage (With User Tracking)108 109**Authenticated Request:**110```javascript111const response = await fetch('/chat', {112  method: 'POST',113  headers: { 'Content-Type': 'application/json' },114  body: JSON.stringify({115    prompt: "What's my chat history?",116    user_id: "user123",117    use_search: true118  })119});120```121 122### Python Client Example123 124```python125import requests126 127def chat_anonymous(prompt, use_search=True):128    """Send anonymous chat request"""129    response = requests.post('https://your-atlas-api.com/chat', 130        json={131            'prompt': prompt,132            'use_search': use_search133        }134    )135    return response.json()136 137def chat_authenticated(prompt, user_id, use_search=True):138    """Send authenticated chat request"""139    response = requests.post('https://your-atlas-api.com/chat', 140        json={141            'prompt': prompt,142            'user_id': user_id,143            'use_search': use_search144        }145    )146    return response.json()147 148# Anonymous usage149result = chat_anonymous("What is AI?")150print(result['response'])151 152# Authenticated usage  153result = chat_authenticated("What is AI?", "user123")154print(result['response'])155```156 157## 🌐 API Endpoints158 159### Core Functionality160- **`/`** - Health check and status161- **`/chat`** - Main chat endpoint (supports both anonymous and authenticated)162- **`/search`** - Direct search functionality163- **`/docs`** - Interactive API documentation (Swagger UI)164 165### Analytics & Cache Management166- **`/analytics/stats`** - JSON API with analytics statistics167- **`/analytics/dashboard`** - Interactive HTML dashboard with charts168- **`/analytics/export`** - Export analytics data (JSON/CSV format)169- **`/analytics/cache`** - Cache performance metrics and statistics170- **`/analytics/cache/clear`** - Cache management and maintenance171- **`/analytics/users`** - User statistics and anonymous vs authenticated metrics172- **`/analytics/user/{user_id}`** - Individual user analytics and insights173- **`/analytics/comparison`** - Detailed authenticated vs anonymous comparison174 175## 📖 Documentation176 177### API & Integration178- **[API Integration Guide](docs/api/integration-guide.md)** - Comprehensive integration examples with new parameters179- **[Anonymous API Examples](docs/api/anonymous-examples.md)** - Sample API calls for anonymous usage180- **[Search Optimization Guide](docs/features/search-optimization.md)** - Smart search features and configuration181 182### Development & Setup  183- **[Setup Guide](docs/setup/SETUP.md)** - Local development setup with all features184- **[Developer Guide](docs/developer/search-optimizer-guide.md)** - Search optimization internals and customization185- **[Deployment Guide](docs/deployment/DEPLOYMENT.md)** - Production deployment instructions186 187### Troubleshooting & Reference188- **[Optimization Troubleshooting](docs/troubleshooting/optimization-troubleshooting.md)** - Search and cache issues189- **[Migration Guide](docs/reference/migration-guide.md)** - Database migration instructions190 191## 🔒 Privacy & Security192 193### Anonymous Mode194- **No Tracking**: Zero personal data collection195- **No Registration**: Use immediately without accounts196- **Privacy-First**: Requests processed without user identification197- **Same Functionality**: Full AI and search capabilities198 199### Authenticated Mode200- **Optional**: Only when you need user-specific features201- **Secure**: Proper user ID validation and sanitization202- **Flexible**: Easy to switch between modes203- **Data Control**: Users control their data association204 205## 🚀 Getting Started206 207### 1. Anonymous Usage (Immediate)208```bash209curl -X POST https://your-atlas-api.com/chat \210  -H "Content-Type: application/json" \211  -d '{"prompt": "Hello, how are you?"}'212```213 214### 2. With Session Continuity215```bash216curl -X POST https://your-atlas-api.com/chat \217  -H "Content-Type: application/json" \218  -H "X-Session-ID: your-session-id" \219  -d '{"prompt": "Continue our conversation"}'220```221 222### 3. Authenticated Usage223```bash224curl -X POST https://your-atlas-api.com/chat \225  -H "Content-Type: application/json" \226  -d '{227    "prompt": "What is my history?",228    "user_id": "user123"229  }'230```231 232## 📊 Analytics & Monitoring233 234Access comprehensive analytics at `/analytics/dashboard`:235 236- **Usage Statistics**: Total messages, sessions, active users237- **Performance Metrics**: Response times, success rates238- **Search Analytics**: Engine performance, query patterns239- **User Modes**: Anonymous vs authenticated usage breakdown240- **Real-time Updates**: Live dashboard with auto-refresh241 242## 🛠️ Integration Patterns243 244### Progressive Enhancement245```javascript246class ChatClient {247  constructor(apiUrl) {248    this.apiUrl = apiUrl;249    this.userId = null; // Start anonymous250  }251  252  authenticate(userId) {253    this.userId = userId; // Enable user tracking254  }255  256  logout() {257    this.userId = null; // Return to anonymous258  }259  260  async sendMessage(prompt) {261    const body = { prompt, use_search: true };262    if (this.userId) body.user_id = this.userId;263    264    return fetch(`${this.apiUrl}/chat`, {265      method: 'POST',266      headers: { 'Content-Type': 'application/json' },267      body: JSON.stringify(body)268    });269  }270}271```272 273## 📄 License274 275MIT License - see LICENSE file for details.276 277---278 279**Ready to get started?** Try an anonymous request right now, or check out the [API Integration Guide](docs/api/integration-guide.md) for comprehensive examples!280