FLASK_API_DEPLOYMENT_FILES.md

# Flask API Only - Required Files List

This document lists all files needed for a **Flask API-only deployment** (no Gradio UI).

## 📋 Essential Files (Required)

### Core Application Files
```
Research_AI_Assistant/
├── flask_api_standalone.py          # Main Flask application (REQUIRED)
├── Dockerfile.flask                  # Dockerfile for Flask deployment (rename to Dockerfile)
├── README_FLASK_API.md              # README with HF Spaces frontmatter (rename to README.md)
└── requirements.txt                 # Python dependencies (REQUIRED)
```

### Source Code Directory (`src/`)
```
Research_AI_Assistant/src/
├── __init__.py                      # Package initialization
├── config.py                        # Configuration settings
├── llm_router.py                    # LLM routing (local GPU models)
├── local_model_loader.py            # GPU model loader (NEW - for local inference)
├── orchestrator_engine.py           # Main orchestrator
├── context_manager.py               # Context management
├── models_config.py                 # Model configurations
├── agents/
│   ├── __init__.py
│   ├── intent_agent.py              # Intent recognition agent
│   ├── synthesis_agent.py            # Response synthesis agent
│   ├── safety_agent.py               # Safety checking agent
│   └── skills_identification_agent.py # Skills identification agent
└── database.py                      # Database management (if used)
```

### Configuration Files (Optional but Recommended)
```
Research_AI_Assistant/
├── .env                             # Environment variables (optional, use HF Secrets instead)
└── .gitignore                       # Git ignore rules
```

## 📦 File Descriptions

### 1. `flask_api_standalone.py` ⭐ REQUIRED
- **Purpose**: Main Flask application entry point
- **Contains**: API endpoints, orchestrator initialization, request handling
- **Key Features**: 
  - Local GPU model loading
  - Async orchestrator support
  - Health checks
  - Error handling

### 2. `Dockerfile.flask` → `Dockerfile` ⭐ REQUIRED
- **Purpose**: Container configuration
- **Action**: Rename to `Dockerfile` when deploying
- **Includes**: Python 3.10, system dependencies, health checks

### 3. `README_FLASK_API.md` → `README.md` ⭐ REQUIRED
- **Purpose**: HF Spaces configuration and API documentation
- **Action**: Rename to `README.md` when deploying
- **Contains**: Frontmatter with `sdk: docker`, API endpoints, usage examples

### 4. `requirements.txt` ⭐ REQUIRED
- **Purpose**: Python package dependencies
- **Includes**: Flask, transformers, torch (GPU), sentence-transformers, etc.

### 5. `src/local_model_loader.py` ⭐ REQUIRED (NEW)
- **Purpose**: Loads models locally on GPU
- **Features**: GPU detection, model caching, FP16 optimization

### 6. `src/llm_router.py` ⭐ REQUIRED (UPDATED)
- **Purpose**: Routes inference requests
- **Features**: Tries local models first, falls back to HF API

### 7. `src/orchestrator_engine.py` ⭐ REQUIRED
- **Purpose**: Main AI orchestration engine
- **Contains**: Agent coordination, request processing

### 8. `src/context_manager.py` ⭐ REQUIRED
- **Purpose**: Manages conversation context
- **Features**: Session management, context retrieval

### 9. `src/agents/*.py` ⭐ REQUIRED
- **Purpose**: Individual AI agents
- **Agents**: Intent, Synthesis, Safety, Skills Identification

### 10. `src/config.py` ⭐ REQUIRED
- **Purpose**: Application configuration
- **Settings**: MAX_WORKERS=4, model paths, etc.

## ❌ Files NOT Needed (Gradio/UI Related)

These files can be **excluded** from Flask API deployment:

```
Research_AI_Assistant/
├── app.py                           # Gradio UI (NOT NEEDED)
├── main.py                           # Gradio + Flask launcher (NOT NEEDED)
├── flask_api.py                      # Flask API (use standalone instead)
├── Dockerfile                        # Main Dockerfile (use Dockerfile.flask)
├── Dockerfile.hf                     # Alternative Dockerfile (NOT NEEDED)
├── README.md                         # Main README (use README_FLASK_API.md)
└── All .md files except this one     # Documentation (optional)
```

## 🚀 Quick Deployment Checklist

### Step 1: Prepare Files
```bash
# In your Flask API Space directory:
cp Dockerfile.flask Dockerfile
cp README_FLASK_API.md README.md
```

### Step 2: Verify Structure
```
Your Space/
├── Dockerfile                        # ✅ Renamed from Dockerfile.flask
├── README.md                         # ✅ Renamed from README_FLASK_API.md
├── flask_api_standalone.py          # ✅ Main Flask app
├── requirements.txt                  # ✅ Dependencies
└── src/                              # ✅ All source files
    ├── __init__.py
    ├── config.py
    ├── llm_router.py
    ├── local_model_loader.py
    ├── orchestrator_engine.py
    ├── context_manager.py
    ├── models_config.py
    └── agents/
        ├── __init__.py
        ├── intent_agent.py
        ├── synthesis_agent.py
        ├── safety_agent.py
        └── skills_identification_agent.py
```

### Step 3: Set Environment Variables
In HF Spaces Settings → Secrets:
- `HF_TOKEN` - Your Hugging Face token

### Step 4: Deploy
- Select **NVIDIA T4 Medium** GPU
- Set **SDK: docker**
- Deploy

## 📊 File Size Considerations

### Minimal Deployment (Essential Only)
- Core files: ~50 KB
- Source code: ~500 KB
- **Total**: ~550 KB code

### With Models (First Load)
- Code: ~550 KB
- Models (downloaded on first run): ~14-16 GB
- **Total**: ~14-16 GB (first build)

### Subsequent Builds
- Models cached by HF Spaces
- Code only: ~550 KB

## 🔍 Verification

After deployment, verify these files exist:

```bash
# Check main files
ls -la Dockerfile README.md flask_api_standalone.py requirements.txt

# Check source directory
ls -la src/
ls -la src/agents/

# Verify key components
grep -r "local_model_loader" src/llm_router.py
grep -r "MAX_WORKERS" src/config.py
```

## 📝 Summary

**Minimum Required Files:**
1. `flask_api_standalone.py`
2. `Dockerfile` (from Dockerfile.flask)
3. `README.md` (from README_FLASK_API.md)
4. `requirements.txt`
5. All files in `src/` directory

**Total: ~15-20 files** (excluding documentation)

---

**Note**: This is a minimal deployment. All Gradio UI files, documentation, and test files are optional and can be excluded to reduce repository size.