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

```json
{
  "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)

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```javascript
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

```javascript
// 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

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

```json
{
  "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

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

### View Dashboard

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

## Search Optimization Examples

### Conservative Mode (Minimize Searches)

```bash
# 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)

```bash  
# 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

```bash
# 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