Apppublic

findEthics/Atlas

sourceHugging Faceupdated 1y agoView on Hugging Face

0likes

App README

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 for comprehensive examples!