> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olis-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Server

> Python-based backend with RAG capabilities

## Overview

The Olis API Server is a FastAPI-based backend service that provides the core intelligence behind Olis. It includes a sophisticated RAG (Retrieval-Augmented Generation) pipeline for document understanding and intelligent responses.

## Technology Stack

<CardGroup cols={2}>
  <Card title="FastAPI" icon="bolt">
    Modern, fast Python web framework
  </Card>

  <Card title="Uvicorn" icon="server">
    Lightning-fast ASGI server
  </Card>

  <Card title="RAG Pipeline" icon="brain">
    Document retrieval and generation system
  </Card>

  <Card title="Vector Database" icon="database">
    Semantic search capabilities
  </Card>
</CardGroup>

## Project Structure

```bash theme={null}
apps/api-server/
├── src/
│   └── backend/
│       ├── routers/          # API route handlers
│       ├── utils/
│       │   └── retrievers/   # RAG components
│       │       └── document_db/
│       │           ├── reranker.py
│       │           └── retriever.py
│       ├── models/           # Pydantic models
│       └── middleware/       # Custom middleware
├── tests/
│   └── integration_tests/    # Integration tests
├── scripts/
│   ├── preflight_rag.sh     # Unix RAG preflight
│   └── preflight_rag.ps1    # Windows RAG preflight
├── requirements.txt          # Python dependencies
└── main.py                   # Application entry point
```

## Development Setup

### Prerequisites

* Python 3.9+
* pip or poetry
* Redis (optional, for caching)
* Vector database (optional, for RAG)

### Installation

<Steps>
  <Step title="Navigate to the API server directory">
    ```bash theme={null}
    cd apps/api-server
    ```
  </Step>

  <Step title="Create a virtual environment (recommended)">
    ```bash theme={null}
    # Create virtual environment
    python -m venv venv

    # Activate it
    # Windows
    .\venv\Scripts\activate

    # macOS/Linux
    source venv/bin/activate
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    pip install -r requirements.txt
    ```
  </Step>

  <Step title="Set up environment variables">
    Create a `.env` file:

    ```bash theme={null}
    # API Configuration
    API_HOST=0.0.0.0
    API_PORT=8000
    DEBUG=True

    # Database
    DATABASE_URL=postgresql://user:pass@localhost/olis

    # Redis Cache
    REDIS_URL=redis://localhost:6379

    # RAG Configuration
    VECTOR_DB_URL=http://localhost:8080
    EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
    ```
  </Step>

  <Step title="Run the server">
    ```bash theme={null}
    uvicorn main:app --reload --host 0.0.0.0 --port 8000
    ```

    The API will be available at `http://localhost:8000`.
  </Step>
</Steps>

## API Endpoints

### Core Endpoints

<AccordionGroup>
  <Accordion title="GET /health" icon="heart-pulse">
    Health check endpoint

    **Response**:

    ```json theme={null}
    {
      "status": "healthy",
      "timestamp": "2024-01-01T00:00:00Z",
      "version": "0.1.0"
    }
    ```
  </Accordion>

  <Accordion title="POST /api/chat" icon="message">
    Send a chat message and receive AI response

    **Request**:

    ```json theme={null}
    {
      "message": "What is Olis?",
      "context": [],
      "sessionId": "uuid-string"
    }
    ```

    **Response**:

    ```json theme={null}
    {
      "response": "Olis is an AI assistant...",
      "sources": ["doc1.pdf", "doc2.md"],
      "confidence": 0.95
    }
    ```
  </Accordion>

  <Accordion title="POST /api/search" icon="magnifying-glass">
    Search documents semantically

    **Request**:

    ```json theme={null}
    {
      "query": "machine learning basics",
      "limit": 10,
      "filters": {
        "type": "pdf"
      }
    }
    ```

    **Response**:

    ```json theme={null}
    {
      "results": [
        {
          "id": "doc1",
          "content": "...",
          "score": 0.92,
          "metadata": {...}
        }
      ],
      "total": 42
    }
    ```
  </Accordion>

  <Accordion title="POST /api/ingest" icon="upload">
    Ingest documents into the RAG system

    **Request**: Multipart form data with file uploads

    **Response**:

    ```json theme={null}
    {
      "success": true,
      "documentsProcessed": 5,
      "jobId": "job-uuid"
    }
    ```
  </Accordion>
</AccordionGroup>

### Interactive API Documentation

FastAPI automatically generates interactive API documentation:

* **Swagger UI**: `http://localhost:8000/docs`
* **ReDoc**: `http://localhost:8000/redoc`

## RAG Pipeline

### Architecture

```mermaid theme={null}
graph LR
    Query[User Query] --> Embed[Embedding]
    Embed --> Search[Vector Search]
    Search --> Rerank[Reranking]
    Rerank --> Context[Context Assembly]
    Context --> LLM[LLM Generation]
    LLM --> Response[Response]
```

### Components

<Tabs>
  <Tab title="Document Ingestion">
    **Process**:

    1. Document upload via API
    2. Text extraction (PDF, DOCX, etc.)
    3. Chunking into manageable pieces
    4. Embedding generation
    5. Storage in vector database

    **Supported Formats**:

    * PDF
    * DOCX
    * TXT
    * MD (Markdown)
    * JSON
    * CSV
  </Tab>

  <Tab title="Retrieval">
    **Process**:

    1. Query embedding generation
    2. Semantic similarity search
    3. Top-k document retrieval
    4. Metadata filtering

    **Configuration**:

    ```python theme={null}
    # src/backend/utils/retrievers/document_db/retriever.py
    class DocumentRetriever:
        def __init__(
            self,
            top_k: int = 10,
            similarity_threshold: float = 0.7
        ):
            self.top_k = top_k
            self.threshold = similarity_threshold
    ```
  </Tab>

  <Tab title="Reranking">
    **Purpose**: Improve retrieval quality by reordering results

    **Reranker Types**:

    * **Cross-encoder**: Deep semantic understanding
    * **BM25**: Traditional keyword-based
    * **Hybrid**: Combine multiple signals

    **Implementation**:

    ```python theme={null}
    # src/backend/utils/retrievers/document_db/reranker.py
    class Reranker:
        def rerank(
            self,
            query: str,
            documents: List[Document]
        ) -> List[Document]:
            # Reranking logic
            pass
    ```
  </Tab>

  <Tab title="Generation">
    **Process**:

    1. Context assembly from retrieved docs
    2. Prompt construction
    3. LLM generation
    4. Response post-processing

    **Features**:

    * Streaming responses
    * Citation tracking
    * Confidence scoring
    * Fallback handling
  </Tab>
</Tabs>

## RAG Preflight Testing

Before deploying, run the RAG preflight check to catch issues early:

<CodeGroup>
  ```bash Bash (Unix/Linux/Mac) theme={null}
  cd apps/api-server
  ./scripts/preflight_rag.sh
  ```

  ```powershell PowerShell (Windows) theme={null}
  cd apps/api-server
  .\scripts\preflight_rag.ps1
  ```
</CodeGroup>

### Environment Overrides

```bash theme={null}
# Set custom timeout (default: 300 seconds)
PREFLIGHT_TIMEOUT_SECONDS=600 ./scripts/preflight_rag.sh

# Keep containers running for debugging
KEEP_PREFLIGHT_RUNNING=1 ./scripts/preflight_rag.sh
```

### What It Tests

<AccordionGroup>
  <Accordion title="Import Checks">
    * All Python modules import successfully
    * No missing dependencies
    * Correct Python version
  </Accordion>

  <Accordion title="Runtime Checks">
    * API server starts without errors
    * Database connections work
    * Redis cache is accessible
    * Vector database is reachable
  </Accordion>

  <Accordion title="Integration Tests">
    * Document ingestion pipeline
    * Query retrieval
    * Reranking functionality
    * End-to-end RAG flow
  </Accordion>
</AccordionGroup>

## Docker Deployment

### Local Development

Use Docker Compose for local development:

```yaml theme={null}
# docker-compose.local.yml
version: '3.8'

services:
  api:
    build: ./apps/api-server
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_URL=redis://redis:6379
    depends_on:
      - redis
      - vector-db

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

  vector-db:
    image: qdrant/qdrant
    ports:
      - "6333:6333"
```

**Start services**:

```bash theme={null}
docker-compose -f docker-compose.local.yml up
```

### Production Build

```dockerfile theme={null}
# Dockerfile
FROM python:3.11-slim

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application
COPY . .

# Run with uvicorn
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
```

**Build and run**:

```bash theme={null}
docker build -t olis-api:latest .
docker run -p 8000:8000 olis-api:latest
```

## Testing

### Running Tests

<CodeGroup>
  ```bash All Tests theme={null}
  cd apps/api-server
  pytest
  ```

  ```bash Integration Tests theme={null}
  pytest tests/integration_tests/
  ```

  ```bash With Coverage theme={null}
  pytest --cov=src --cov-report=html
  ```

  ```bash Specific Test theme={null}
  pytest tests/integration_tests/test_fastapi.py::test_chat_endpoint
  ```
</CodeGroup>

### Test Structure

```python theme={null}
# tests/integration_tests/test_fastapi.py
import pytest
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_health_endpoint():
    response = client.get("/health")
    assert response.status_code == 200
    assert response.json()["status"] == "healthy"

def test_chat_endpoint():
    response = client.post(
        "/api/chat",
        json={"message": "Hello", "sessionId": "test"}
    )
    assert response.status_code == 200
    assert "response" in response.json()
```

## Configuration

### Environment Variables

<AccordionGroup>
  <Accordion title="API Settings">
    ```bash theme={null}
    API_HOST=0.0.0.0
    API_PORT=8000
    DEBUG=False
    LOG_LEVEL=INFO
    CORS_ORIGINS=["http://localhost:3000"]
    ```
  </Accordion>

  <Accordion title="Database Settings">
    ```bash theme={null}
    DATABASE_URL=postgresql://user:pass@localhost/olis
    DATABASE_POOL_SIZE=20
    DATABASE_MAX_OVERFLOW=10
    ```
  </Accordion>

  <Accordion title="Redis Settings">
    ```bash theme={null}
    REDIS_URL=redis://localhost:6379
    REDIS_CACHE_TTL=3600
    REDIS_MAX_CONNECTIONS=50
    ```
  </Accordion>

  <Accordion title="RAG Settings">
    ```bash theme={null}
    VECTOR_DB_URL=http://localhost:6333
    EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
    CHUNK_SIZE=512
    CHUNK_OVERLAP=50
    TOP_K_DOCUMENTS=10
    RERANK_ENABLED=True
    ```
  </Accordion>
</AccordionGroup>

## Performance Optimization

<CardGroup cols={2}>
  <Card title="Caching" icon="bolt">
    * Redis for query results
    * Embedding cache
    * Response caching
    * Connection pooling
  </Card>

  <Card title="Async Operations" icon="arrows-spin">
    * Async/await throughout
    * Non-blocking I/O
    * Background tasks
    * Parallel processing
  </Card>

  <Card title="Database Optimization" icon="database">
    * Connection pooling
    * Query optimization
    * Index management
    * Batch operations
  </Card>

  <Card title="Monitoring" icon="chart-line">
    * Prometheus metrics
    * Request logging
    * Error tracking
    * Performance profiling
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Server Won't Start">
    **Problem**: `uvicorn` fails to start

    **Solution**:

    ```bash theme={null}
    # Check port availability
    netstat -an | grep 8000

    # Try different port
    uvicorn main:app --port 8001

    # Check Python version
    python --version  # Should be 3.9+
    ```
  </Accordion>

  <Accordion title="Import Errors">
    **Problem**: Module import failures

    **Solution**:

    ```bash theme={null}
    # Verify virtual environment is activated
    which python

    # Reinstall dependencies
    pip install --force-reinstall -r requirements.txt

    # Check for missing packages
    pip list
    ```
  </Accordion>

  <Accordion title="Database Connection Issues">
    **Problem**: Cannot connect to database

    **Solution**:

    ```bash theme={null}
    # Verify DATABASE_URL format
    # postgresql://user:password@host:port/database

    # Test connection directly
    psql $DATABASE_URL

    # Check firewall/network settings
    telnet host port
    ```
  </Accordion>

  <Accordion title="RAG Pipeline Failures">
    **Problem**: Document ingestion or retrieval fails

    **Solution**:

    1. Run preflight check: `./scripts/preflight_rag.sh`
    2. Check vector database is running
    3. Verify embedding model is downloaded
    4. Check logs for specific errors
    5. Test with simple document first
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Explore detailed API documentation
  </Card>

  <Card title="Electron Client" icon="desktop" href="/apps/electron-client">
    Learn about the desktop client
  </Card>
</CardGroup>