docs/api/anonymous-examples.md

Anonymous Chat API Examples

This document provides sample API calls for using the Atlas Chat API in anonymous mode (without user authentication).

API Endpoint

Base URL: http://localhost:8000 (or your deployed URL)
Endpoint: POST /chat
Content-Type: application/json

Request Structure

{
  "prompt": "Your question or message here",
  "max_new_tokens": 500,
  "use_search": true,
  "temperature": 0.7,
  "user_id": null,
  "force_search": null,
  "search_decision_mode": "balanced"
}

Parameters

• prompt (required): Your question or message to the AI
• max_new_tokens (optional): Maximum tokens in response (default: 500)
• use_search (optional): Whether to use web search (default: true)
• temperature (optional): Response creativity (0.0-1.0, default: 0.7)
• user_id (optional): User identifier (null/omitted for anonymous)
• force_search (optional): Override smart search optimization (true/false/null)
• search_decision_mode (optional): Search sensitivity ("conservative"/"balanced"/"aggressive")
• history (optional): Conversation history for context-aware responses

Anonymous Request Examples

1. Basic Anonymous Request (No user_id field)

curl -X POST "http://localhost:8000/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What is the capital of France?",
    "use_search": false
  }'

2. Anonymous Request with Explicit null user_id

curl -X POST "http://localhost:8000/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Explain quantum computing in simple terms",
    "user_id": null,
    "use_search": true,
    "temperature": 0.5
  }'

3. Anonymous Request with Search Optimization

curl -X POST "http://localhost:8000/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What are the latest developments in AI?",
    "user_id": null,
    "search_decision_mode": "aggressive",
    "max_new_tokens": 300
  }'

4. Anonymous Request with Forced Search

curl -X POST "http://localhost:8000/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What is 2+2?",
    "force_search": true,
    "max_new_tokens": 200
  }'

5. Anonymous Request with Conversation History

curl -X POST "http://localhost:8000/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Can you elaborate on neural networks?",
    "user_id": null,
    "search_decision_mode": "conservative",
    "history": [
      {"role": "user", "content": "What is machine learning?"},
      {"role": "assistant", "content": "Machine learning is a subset of AI that enables computers to learn from data..."}
    ]
  }'

JavaScript/Fetch Examples

Basic Anonymous Request

const response = await fetch('http://localhost:8000/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prompt: "How does machine learning work?",
    use_search: true,
    temperature: 0.6,
    search_decision_mode: "balanced"
  })
});

const data = await response.json();
console.log(data.response);
console.log('Search decision:', data.search_decision);
console.log('Cache info:', data.cache_info);

Advanced JavaScript Example with Optimization

// Smart chat client with optimization features
async function smartChat(prompt, conversationHistory = []) {
  const requestBody = {
    prompt: prompt,
    use_search: true,
    temperature: 0.7,
    history: conversationHistory
  };

  // Use aggressive mode for news/current events
  if (prompt.includes('latest') || prompt.includes('current') || prompt.includes('today')) {
    requestBody.search_decision_mode = 'aggressive';
  }
  // Use conservative mode for follow-up questions  
  else if (conversationHistory.length > 0 && (
    prompt.includes('elaborate') || 
    prompt.includes('more about') || 
    prompt.includes('explain')
  )) {
    requestBody.search_decision_mode = 'conservative';
  }

  const response = await fetch('http://localhost:8000/chat', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(requestBody)
  });

  const data = await response.json();
  
  // Log optimization details
  console.log(`Search performed: ${data.search_decision?.should_search}`);
  console.log(`Reason: ${data.search_decision?.reason}`);
  console.log(`Cache hit: ${data.cache_info?.cache_hit}`);
  
  return data;
}

// Usage examples
await smartChat("What is artificial intelligence?");
await smartChat("Tell me more about that", previousHistory);
await smartChat("What's the latest AI news?");

Python Examples

Using requests library

import requests

# Basic anonymous request
url = "http://localhost:8000/chat"
payload = {
    "prompt": "Explain the theory of relativity",
    "use_search": False,
    "temperature": 0.5
}

response = requests.post(url, json=payload)
data = response.json()
print(data['response'])

Response Format

All requests return a JSON response with this structure:

{
  "response": "The AI's response to your prompt...",
  "search_results": [
    {
      "title": "Search Result Title",
      "body": "Search result description...",
      "href": "https://example.com",
      "source": "Brave"
    }
  ],
  "search_decision": {
    "should_search": true,
    "reason": "New information request detected",
    "confidence": 0.9,
    "decision_method": "rule_based"
  },
  "cache_info": {
    "cache_hit": false,
    "flow_type": "cache_first_miss",
    "cache_type": "chromadb_vector"
  }
}

Response Fields Explained

• response: The AI's text response to your prompt
• search_results: Array of web search results used (if search was performed)
• search_decision: Details about the search optimization decision
  • should_search: Whether search was determined necessary
  • reason: Human-readable explanation for the decision
  • confidence: Decision confidence score (0.0-1.0)
  • decision_method: Method used ("rule_based", "hybrid", "fallback")
• cache_info: Information about caching and performance
  • cache_hit: Whether results came from cache
  • flow_type: Processing flow used (e.g., "cache_first_miss", "search_decision_skip")
  • cache_type: Type of caching system (e.g., "chromadb_vector")

Session Tracking

Anonymous requests automatically create sessions for analytics purposes:

• Each request gets a unique session ID (returned in X-Session-ID header)
• Sessions are tracked anonymously (no personal data stored)
• Analytics count anonymous vs authenticated usage
• No individual user tracking for anonymous requests

Analytics Endpoints

You can also check anonymous usage analytics:

Get Basic Stats

curl "http://localhost:8000/analytics/stats"

View Dashboard

curl "http://localhost:8000/analytics/dashboard"

Search Optimization Examples

Conservative Mode (Minimize Searches)

# Good for cost optimization and follow-up heavy conversations
curl -X POST "http://localhost:8000/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Can you elaborate on that point?",
    "search_decision_mode": "conservative",
    "history": [
      {"role": "user", "content": "What is renewable energy?"},
      {"role": "assistant", "content": "Renewable energy comes from natural sources..."}
    ]
  }'

Aggressive Mode (Prioritize Fresh Information)

# Good for current events and news
curl -X POST "http://localhost:8000/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What happened in tech today?",
    "search_decision_mode": "aggressive"
  }'

Force Search Override

# Force search even for simple questions
curl -X POST "http://localhost:8000/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What is 2+2?",
    "force_search": true
  }'

# Disable search completely
curl -X POST "http://localhost:8000/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Tell me about this topic",
    "force_search": false,
    "history": [
      {"role": "user", "content": "Explain machine learning"},
      {"role": "assistant", "content": "Machine learning is..."}
    ]
  }'

Notes

• Anonymous requests have identical functionality to authenticated requests
• No user data is stored or tracked for anonymous requests
• Smart search optimization reduces unnecessary searches by 40-60%
• ChromaDB caching provides instant responses for similar queries
• Context-aware processing uses conversation history intelligently
• Response quality and speed are optimized through intelligent search decisions
• Sessions are created automatically for analytics but contain no personal information