README.md

---
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:

```bash
# 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:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
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

```python
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](docs/api/integration-guide.md)** - Comprehensive integration examples with new parameters
- **[Anonymous API Examples](docs/api/anonymous-examples.md)** - Sample API calls for anonymous usage
- **[Search Optimization Guide](docs/features/search-optimization.md)** - Smart search features and configuration

### Development & Setup  
- **[Setup Guide](docs/setup/SETUP.md)** - Local development setup with all features
- **[Developer Guide](docs/developer/search-optimizer-guide.md)** - Search optimization internals and customization
- **[Deployment Guide](docs/deployment/DEPLOYMENT.md)** - Production deployment instructions

### Troubleshooting & Reference
- **[Optimization Troubleshooting](docs/troubleshooting/optimization-troubleshooting.md)** - Search and cache issues
- **[Migration Guide](docs/reference/migration-guide.md)** - 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)
```bash
curl -X POST https://your-atlas-api.com/chat \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello, how are you?"}'
```

### 2. With Session Continuity
```bash
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
```bash
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
```javascript
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](docs/api/integration-guide.md) for comprehensive examples!