# Flask API Documentation

## 1. Setup

### 1.1 Create Virtual Environment
```bash
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate

1.2 Install Dependencies

pip install -r requirements.txt

1.3 Environment Variables

Create a .env file in the root directory:

GROQ_API_KEY=your_groq_api_key
MONGODB_URI=your_mongodb_uri

Do NOT commit .env to Git.

---

2. Run Server

python main.py

Server runs on:

http://localhost:5000

Base API path:

/api

---

3. Users API

Create / Get User (Idempotent)

POST /api/users

Request Body (JSON)

{
  "clerkUserId": "user_123"
}

Response

{
  "id": "mongodb_user_id",
  "clerkUserId": "user_123",
  "createdAt": "2025-01-01T10:00:00"
}

---

4. Documents API

4.1 Upload & Process Document

POST /api/documents/upload

Form Data

Key	Required
clerkUserId	yes
file (csv/xlsx)	yes
nickname	no

Response

{
  "message": "file uploaded and processed successfully",
  "original_filename": "sales.csv",
  "stored_filename": "uuid.csv",
  "nickname": "Sales Data",
  "processed_path": "storage/processed/xxx.json",
  "context_path": "storage/context/xxx.json"
}

---

4.2 List Documents (Metadata Only)

GET /api/documents?clerkUserId=user_123

Response

[
  {
    "documentId": "doc_id",
    "nickname": "Sales Data",
    "originalFileName": "sales.csv",
    "data_confidence": 0.91,
    "ai_confidence": 0.88,
    "createdAt": "2025-01-01T12:00:00"
  }
]

---

4.3 Get Processed Data + Group Summary

GET /api/documents/processed?clerkUserId=user_123

Response

{
  "datasets": [
    { "...": "processed dataset" }
  ],
  "group_summary": "AI generated summary"
}

---

4.4 Delete Document

DELETE /api/documents/{documentId}?clerkUserId=user_123

Response

{
  "message": "Document deleted successfully"
}

---

5. Chat API

5.1 Ask Question on Document

POST /api/chat/ask

Request Body (JSON)

{
  "clerkUserId": "user_123",
  "documentId": "doc_id",
  "question": "What insights can you derive?"
}

Response

{
  "answer": "AI generated response",
  "category": "analysis"
}

---

5.2 Get Chat History

GET /api/chat/history?clerkUserId=user_123&documentId=doc_id

Response

{
  "messages": [
    { "role": "user", "content": "Question?" },
    { "role": "assistant", "content": "Answer." }
  ]
}

Endpoint

POST http://127.0.0.1:5000/documents/upload/google-sheet

Body

{
  "clerkUserId": "user_12345",
  "sheetUrl": "https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
  "nickname": "class data"
}

---

6. Notes

• clerkUserId is mandatory for all endpoints
• Files are stored internally using UUIDs
• Nickname is only for UI display
• Supported file types: csv, xlsx
• Chat is scoped per document

If you want, next I can:
- add **Postman collection**
- add **curl examples**
- write **Swagger/OpenAPI**
- make a **frontend flow doc for Next.js + Clerk**

Just tell me 🚀