# Sim-Search API Specification

This document provides a comprehensive guide for frontend developers to integrate with the Sim-Search API. The API offers intelligent research capabilities, including query processing, search execution across multiple engines, and report generation.

## API Base URL

```
/api/v1
```

## Authentication

The API uses OAuth2 with Bearer token authentication. All API endpoints except for authentication endpoints require a valid Bearer token.

### Register a New User

```
POST /api/v1/auth/register
```

Register a new user account.

**Request Body**:
```json
{
  "email": "user@example.com",
  "password": "password123",
  "full_name": "User Name",
  "is_active": true,
  "is_superuser": false
}
```

**Response** (200 OK):
```json
{
  "id": "user-uuid",
  "email": "user@example.com",
  "full_name": "User Name",
  "is_active": true,
  "is_superuser": false
}
```

### Login to Get Access Token

```
POST /api/v1/auth/token
```

Obtain an access token for API authentication.

**Request Body (form data)**:
```
username=user@example.com
password=password123
```

**Response** (200 OK):
```json
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "bearer"
}
```

## Query Processing

### Process a Query

```
POST /api/v1/query/process
```

Process a search query to enhance and structure it for better search results.

**Headers**:
- Authorization: Bearer {access_token}

**Request Body**:
```json
{
  "query": "What are the latest advancements in quantum computing?"
}
```

**Response** (200 OK):
```json
{
  "original_query": "What are the latest advancements in quantum computing?",
  "structured_query": {
    "original_query": "What are the latest advancements in quantum computing?",
    "enhanced_query": "What are the recent breakthroughs and developments in quantum computing technology, algorithms, and applications in the past 2 years?",
    "type": "exploratory",
    "intent": "research",
    "domain": "academic",
    "confidence": 0.95,
    "reasoning": "This query is asking about recent developments in a scientific field, which is typical of academic research.",
    "entities": ["quantum computing", "advancements"],
    "sub_questions": [
      {
        "sub_question": "What are the latest hardware advancements in quantum computing?",
        "aspect": "hardware",
        "priority": 0.9
      },
      {
        "sub_question": "What are the recent algorithmic breakthroughs in quantum computing?",
        "aspect": "algorithms",
        "priority": 0.8
      }
    ],
    "search_queries": {
      "google": "latest advancements in quantum computing 2024",
      "scholar": "recent quantum computing breakthroughs",
      "arxiv": "quantum computing hardware algorithms"
    },
    "is_academic": true,
    "is_code": false,
    "is_current_events": false
  }
}
```

### Classify a Query

```
POST /api/v1/query/classify
```

Classify a query by type and intent.

**Headers**:
- Authorization: Bearer {access_token}

**Request Body**:
```json
{
  "query": "What are the latest advancements in quantum computing?"
}
```

**Response** (200 OK):
```json
{
  "original_query": "What are the latest advancements in quantum computing?",
  "structured_query": {
    "original_query": "What are the latest advancements in quantum computing?",
    "type": "exploratory",
    "domain": "academic",
    "confidence": 0.95
  }
}
```

## Search Execution

### Get Available Search Engines

```
GET /api/v1/search/engines
```

Get a list of available search engines.

**Headers**:
- Authorization: Bearer {access_token}

**Response** (200 OK):
```json
["google", "arxiv", "scholar", "news", "openalex", "core", "github", "stackexchange"]
```

### Execute a Search

```
POST /api/v1/search/execute
```

Execute a search with the given parameters.

**Headers**:
- Authorization: Bearer {access_token}

**Request Body**:
```json
{
  "structured_query": {
    "original_query": "What are the environmental impacts of electric vehicles?",
    "enhanced_query": "What are the environmental impacts of electric vehicles?",
    "type": "factual",
    "domain": "environmental"
  },
  "search_engines": ["google", "arxiv"],
  "num_results": 5,
  "timeout": 30
}
```

**Response** (200 OK):
```json
{
  "search_id": "search-uuid",
  "query": "What are the environmental impacts of electric vehicles?",
  "enhanced_query": "What are the environmental impacts of electric vehicles?",
  "results": {
    "google": [
      {
        "title": "Environmental Impacts of Electric Vehicles",
        "url": "https://example.com/article1",
        "snippet": "Electric vehicles have several environmental impacts including...",
        "source": "google",
        "score": 0.95
      }
    ],
    "arxiv": [
      {
        "title": "Lifecycle Analysis of Electric Vehicle Environmental Impact",
        "url": "http://arxiv.org/abs/paper123",
        "pdf_url": "http://arxiv.org/pdf/paper123",
        "snippet": "This paper analyzes the complete lifecycle environmental impact of electric vehicles...",
        "source": "arxiv",
        "authors": ["Researcher Name1", "Researcher Name2"],
        "arxiv_id": "paper123",
        "categories": ["cs.CY", "eess.SY"],
        "published_date": "2023-01-15T10:30:00Z",
        "score": 0.92
      }
    ]
  },
  "total_results": 2,
  "execution_time": 1.25,
  "timestamp": "2024-03-20T14:25:30Z"
}
```

### Get Search History

```
GET /api/v1/search/history
```

Get the user's search history.

**Headers**:
- Authorization: Bearer {access_token}

**Query Parameters**:
- skip (optional, default: 0): Number of records to skip
- limit (optional, default: 100): Maximum number of records to return

**Response** (200 OK):
```json
{
  "searches": [
    {
      "id": "search-uuid",
      "query": "What are the environmental impacts of electric vehicles?",
      "enhanced_query": "What are the environmental impacts of electric vehicles?",
      "query_type": "factual",
      "engines": "google,arxiv",
      "results_count": 10,
      "created_at": "2024-03-20T14:25:30Z"
    }
  ],
  "total": 1
}
```

### Get Search Results

```
GET /api/v1/search/{search_id}
```

Get results for a specific search.

**Headers**:
- Authorization: Bearer {access_token}

**Path Parameters**:
- search_id: ID of the search

**Response** (200 OK):
```json
{
  "search_id": "search-uuid",
  "query": "What are the environmental impacts of electric vehicles?",
  "enhanced_query": "What are the environmental impacts of electric vehicles?",
  "results": {
    "google": [
      {
        "title": "Environmental Impacts of Electric Vehicles",
        "url": "https://example.com/article1",
        "snippet": "Electric vehicles have several environmental impacts including...",
        "source": "google",
        "score": 0.95
      }
    ],
    "arxiv": [
      {
        "title": "Lifecycle Analysis of Electric Vehicle Environmental Impact",
        "url": "http://arxiv.org/abs/paper123",
        "pdf_url": "http://arxiv.org/pdf/paper123",
        "snippet": "This paper analyzes the complete lifecycle environmental impact of electric vehicles...",
        "source": "arxiv",
        "authors": ["Researcher Name1", "Researcher Name2"],
        "arxiv_id": "paper123",
        "categories": ["cs.CY", "eess.SY"],
        "published_date": "2023-01-15T10:30:00Z",
        "score": 0.92
      }
    ]
  },
  "total_results": 2,
  "execution_time": 0.0
}
```

### Delete Search

```
DELETE /api/v1/search/{search_id}
```

Delete a search from history.

**Headers**:
- Authorization: Bearer {access_token}

**Path Parameters**:
- search_id: ID of the search to delete

**Response** (204 No Content)

## Report Generation

### Generate a Report

```
POST /api/v1/report/generate
```

Generate a report from search results.

**Headers**:
- Authorization: Bearer {access_token}

**Request Body**:
```json
{
  "search_id": "search-uuid",
  "query": "What are the environmental impacts of electric vehicles?",
  "detail_level": "standard",
  "query_type": "comparative",
  "model": "llama-3.1-8b-instant",
  "title": "Environmental Impacts of Electric Vehicles"
}
```

**Response** (200 OK):
```json
{
  "id": "report-uuid",
  "user_id": "user-uuid",
  "search_id": "search-uuid",
  "title": "Environmental Impacts of Electric Vehicles",
  "content": "Report generation in progress...",
  "detail_level": "standard",
  "query_type": "comparative",
  "model_used": "llama-3.1-8b-instant",
  "created_at": "2024-03-20T14:30:00Z",
  "updated_at": "2024-03-20T14:30:00Z"
}
```

### Get Report Generation Progress

```
GET /api/v1/report/{report_id}/progress
```

Get the progress of a report generation.

**Headers**:
- Authorization: Bearer {access_token}

**Path Parameters**:
- report_id: ID of the report

**Response** (200 OK):
```json
{
  "report_id": "report-uuid",
  "progress": 0.75,
  "status": "Processing chunk 3/4...",
  "current_chunk": 3,
  "total_chunks": 4,
  "current_report": "The environmental impacts of electric vehicles include..."
}
```

### Get Report List

```
GET /api/v1/report/list
```

Get a list of user's reports.

**Headers**:
- Authorization: Bearer {access_token}

**Query Parameters**:
- skip (optional, default: 0): Number of records to skip
- limit (optional, default: 100): Maximum number of records to return

**Response** (200 OK):
```json
{
  "reports": [
    {
      "id": "report-uuid",
      "user_id": "user-uuid",
      "search_id": "search-uuid",
      "title": "Environmental Impacts of Electric Vehicles",
      "content": "# Environmental Impacts of Electric Vehicles\n\n## Introduction\n\nElectric vehicles (EVs) have gained popularity...",
      "detail_level": "standard",
      "query_type": "comparative",
      "model_used": "llama-3.1-8b-instant",
      "created_at": "2024-03-20T14:30:00Z",
      "updated_at": "2024-03-20T14:35:00Z"
    }
  ],
  "total": 1
}
```

### Get Report

```
GET /api/v1/report/{report_id}
```

Get a specific report.

**Headers**:
- Authorization: Bearer {access_token}

**Path Parameters**:
- report_id: ID of the report

**Response** (200 OK):
```json
{
  "id": "report-uuid",
  "user_id": "user-uuid",
  "search_id": "search-uuid",
  "title": "Environmental Impacts of Electric Vehicles",
  "content": "# Environmental Impacts of Electric Vehicles\n\n## Introduction\n\nElectric vehicles (EVs) have gained popularity...",
  "detail_level": "standard",
  "query_type": "comparative",
  "model_used": "llama-3.1-8b-instant",
  "created_at": "2024-03-20T14:30:00Z",
  "updated_at": "2024-03-20T14:35:00Z"
}
```

### Download Report

```
GET /api/v1/report/{report_id}/download
```

Download a report in the specified format.

**Headers**:
- Authorization: Bearer {access_token}

**Path Parameters**:
- report_id: ID of the report

**Query Parameters**:
- format (optional, default: "markdown"): Format of the report (markdown, html, pdf)

**Response** (200 OK):
- Content-Type: application/octet-stream
- Content-Disposition: attachment; filename="report_{report_id}.{format}"
- Binary file content

### Delete Report

```
DELETE /api/v1/report/{report_id}
```

Delete a report.

**Headers**:
- Authorization: Bearer {access_token}

**Path Parameters**:
- report_id: ID of the report to delete

**Response** (204 No Content)

## Error Handling

The API returns standard HTTP status codes to indicate the success or failure of a request.

### Common Error Codes

- 400 Bad Request: The request was invalid or cannot be served
- 401 Unauthorized: Authentication is required or has failed
- 403 Forbidden: The authenticated user doesn't have the necessary permissions
- 404 Not Found: The requested resource was not found
- 422 Unprocessable Entity: The request data failed validation
- 500 Internal Server Error: An error occurred on the server

### Error Response Format

```json
{
  "detail": "Error message explaining what went wrong"
}
```

## Best Practices for Frontend Integration

1. **Authentication Flow**:
   - Implement a login form that sends credentials to `/api/v1/auth/token`
   - Store the received token securely (HTTP-only cookies or secure storage)
   - Include the token in the Authorization header for all subsequent requests
   - Implement token expiration handling and refresh mechanism

2. **Query Processing Workflow**:
   - Allow users to enter natural language queries
   - Use the `/api/v1/query/process` endpoint to enhance the query
   - Display the enhanced query to the user for confirmation

3. **Search Execution**:
   - Use the processed query for search execution
   - Allow users to select which search engines to use
   - Implement a loading state while waiting for search results
   - Display search results grouped by search engine

4. **Report Generation**:
   - Allow users to generate reports from search results
   - Provide options for detail level and report type
   - Implement progress tracking using the progress endpoint
   - Allow users to download reports in different formats

5. **Error Handling**:
   - Implement proper error handling for API responses
   - Display meaningful error messages to users
   - Implement retry mechanisms for transient errors

## Available Search Engines

- **google**: General web search
- **arxiv**: Academic papers from arXiv
- **scholar**: Academic papers from various sources
- **news**: News articles
- **openalex**: Open access academic content
- **core**: Open access research papers
- **github**: Code repositories
- **stackexchange**: Q&A from Stack Exchange network

## Report Detail Levels

- **brief**: Short summary (default model: llama-3.1-8b-instant)
- **standard**: Comprehensive overview (default model: llama-3.1-8b-instant)
- **detailed**: In-depth analysis (default model: llama-3.3-70b-versatile)
- **comprehensive**: Extensive research report (default model: llama-3.3-70b-versatile)

## Query Types

- **factual**: Seeking facts or information
- **comparative**: Comparing multiple items or concepts
- **exploratory**: Open-ended exploration of a topic
- **procedural**: How to do something
- **causal**: Seeking cause-effect relationships

## Models

- **llama-3.1-8b-instant**: Fast, lightweight model
- **llama-3.3-70b-versatile**: High-quality, comprehensive model
- **Other models may be available based on server configuration**