README.md

metadata

title: Atlas - AI Chat API
emoji: 🤖
colorFrom: blue
colorTo: purple
sdk: docker
sdk_version: 4.36.0
app_file: app.py
pinned: false

Atlas - AI Chat API with Anonymous & Authenticated Modes

Atlas 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.

🚀 Quick Start (Anonymous Mode)

Get started immediately without any setup or authentication:

# Simple anonymous chat request
curl -X POST https://your-atlas-api.com/chat \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What is artificial intelligence?",
    "use_search": true
  }'

📋 Features

🤖 AI-Powered Chat

• Uses Google's Gemini 1.5 Flash model
• Configurable parameters (temperature, max tokens)
• Intelligent responses based on web search results
• Session-based conversation tracking

🔍 Advanced Web Search & Optimization

• Dual Search Engine Strategy: Brave Search + DuckDuckGo
• Resilient Fallback: Automatic fallback if one engine fails
• Smart Query Extraction: NLP-powered search term extraction using spaCy and RAKE
• Deduplication: Removes duplicate results across engines
• 🧠 Intelligent Search Optimization: AI-powered search decision engine
• ⚡ Context-Aware Flow: Cache-first for new conversations, smart decisions for follow-ups
• 🗄️ ChromaDB Vector Caching: Semantic similarity matching with persistent storage
• 📊 Search Analytics: Comprehensive search decision and performance tracking

👤 Flexible User Modes

• Anonymous Mode: Use immediately without authentication
• Authenticated Mode: User tracking and personalized history
• Progressive Enhancement: Start anonymous, add auth later
• Privacy-First: No tracking in anonymous mode

📊 Comprehensive Analytics

• Real-time Session Tracking: Monitor user sessions and activity
• Message Analytics: Track response times, search usage, and success rates
• Interactive Dashboard: Beautiful HTML dashboard with charts and metrics
• Data Export: Export analytics data in JSON or CSV format
• Anonymous vs Authenticated: Separate tracking for different user modes

🔧 API Usage Examples

Anonymous Usage (No Authentication)

Basic Request:

const response = await fetch('/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    prompt: "Explain quantum computing",
    use_search: true
  })
});

With Conversation History:

const response = await fetch('/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    prompt: "Can you elaborate on that?",
    use_search: false,
    history: [
      {role: "user", content: "What is machine learning?"},
      {role: "assistant", content: "Machine learning is..."}
    ]
  })
});

With Search Optimization Controls:

const response = await fetch('/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    prompt: "What are the latest AI developments?",
    use_search: true,
    search_decision_mode: "aggressive", // "conservative", "balanced", "aggressive"
    force_search: true // Override smart search optimization
  })
});

Authenticated Usage (With User Tracking)

Authenticated Request:

const response = await fetch('/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    prompt: "What's my chat history?",
    user_id: "user123",
    use_search: true
  })
});

Python Client Example

import requests

def chat_anonymous(prompt, use_search=True):
    """Send anonymous chat request"""
    response = requests.post('https://your-atlas-api.com/chat', 
        json={
            'prompt': prompt,
            'use_search': use_search
        }
    )
    return response.json()

def chat_authenticated(prompt, user_id, use_search=True):
    """Send authenticated chat request"""
    response = requests.post('https://your-atlas-api.com/chat', 
        json={
            'prompt': prompt,
            'user_id': user_id,
            'use_search': use_search
        }
    )
    return response.json()

# Anonymous usage
result = chat_anonymous("What is AI?")
print(result['response'])

# Authenticated usage  
result = chat_authenticated("What is AI?", "user123")
print(result['response'])

🌐 API Endpoints

Core Functionality

• / - Health check and status
• /chat - Main chat endpoint (supports both anonymous and authenticated)
• /search - Direct search functionality
• /docs - Interactive API documentation (Swagger UI)

Analytics & Cache Management

• /analytics/stats - JSON API with analytics statistics
• /analytics/dashboard - Interactive HTML dashboard with charts
• /analytics/export - Export analytics data (JSON/CSV format)
• /analytics/cache - Cache performance metrics and statistics
• /analytics/cache/clear - Cache management and maintenance
• /analytics/users - User statistics and anonymous vs authenticated metrics
• /analytics/user/{user_id} - Individual user analytics and insights
• /analytics/comparison - Detailed authenticated vs anonymous comparison

📖 Documentation

API & Integration

• API Integration Guide - Comprehensive integration examples with new parameters
• Anonymous API Examples - Sample API calls for anonymous usage
• Search Optimization Guide - Smart search features and configuration

Development & Setup

• Setup Guide - Local development setup with all features
• Developer Guide - Search optimization internals and customization
• Deployment Guide - Production deployment instructions

Troubleshooting & Reference

• Optimization Troubleshooting - Search and cache issues
• Migration Guide - Database migration instructions

🔒 Privacy & Security

Anonymous Mode

• No Tracking: Zero personal data collection
• No Registration: Use immediately without accounts
• Privacy-First: Requests processed without user identification
• Same Functionality: Full AI and search capabilities

Authenticated Mode

• Optional: Only when you need user-specific features
• Secure: Proper user ID validation and sanitization
• Flexible: Easy to switch between modes
• Data Control: Users control their data association

🚀 Getting Started

1. Anonymous Usage (Immediate)

curl -X POST https://your-atlas-api.com/chat \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello, how are you?"}'

2. With Session Continuity

curl -X POST https://your-atlas-api.com/chat \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: your-session-id" \
  -d '{"prompt": "Continue our conversation"}'

3. Authenticated Usage

curl -X POST https://your-atlas-api.com/chat \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What is my history?",
    "user_id": "user123"
  }'

📊 Analytics & Monitoring

Access comprehensive analytics at /analytics/dashboard:

• Usage Statistics: Total messages, sessions, active users
• Performance Metrics: Response times, success rates
• Search Analytics: Engine performance, query patterns
• User Modes: Anonymous vs authenticated usage breakdown
• Real-time Updates: Live dashboard with auto-refresh

🛠️ Integration Patterns

Progressive Enhancement

class ChatClient {
  constructor(apiUrl) {
    this.apiUrl = apiUrl;
    this.userId = null; // Start anonymous
  }
  
  authenticate(userId) {
    this.userId = userId; // Enable user tracking
  }
  
  logout() {
    this.userId = null; // Return to anonymous
  }
  
  async sendMessage(prompt) {
    const body = { prompt, use_search: true };
    if (this.userId) body.user_id = this.userId;
    
    return fetch(`${this.apiUrl}/chat`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(body)
    });
  }
}

📄 License

MIT License - see LICENSE file for details.

---

Ready to get started? Try an anonymous request right now, or check out the API Integration Guide for comprehensive examples!