---
title: GitConnect FastAPI Service
emoji: "🚀"
colorFrom: blue
colorTo: green
sdk: docker
sdk_version: "1.0.0"
python_version: "3.12"
app_file: app.py
pinned: false
---

# GitConnect FastAPI Service

FastAPI backend with two primary features:

- Syllabus processing from PDF URLs with FAISS indexing and multilingual AI summaries.
- Chatbot responses grounded with RAG from both syllabus content and student performance data.

## Core Stack

- API: FastAPI + Uvicorn
- Embeddings: sentence-transformers/all-MiniLM-L6-v2
- Vector Search: FAISS (IndexFlatIP with normalized vectors)
- LLM generation/summarization: Gemini

RAG index persistence:

- Runtime retrieval uses semester FAISS files plus semester PKL records.
- Optional cloud persistence to Neon is enabled with RAG_INDEX_DB_URL.
- On syllabus processing, updated semester FAISS and PKL are uploaded to Neon.
- On server restart, if local files are missing, the server hydrates them from Neon automatically.

About stored artifacts:

- Needed for RAG runtime: semester_x.faiss and semester_x.pkl.
- Raw text files under data/raw_text are not required for search-time RAG.
- Raw text is mainly useful for debugging/auditing ingestion outputs.

## Local Setup

1. Create and activate a virtual environment.
2. Install dependencies:

```bash
pip install -r requirements.txt
```

3. Create `.env` from `.env.example` and set `GEMINI_API_KEY`.
4. Run the service:

```bash
uvicorn app.main:app --reload
```

## Endpoints

- `GET /health`
- `POST /api/syllabus/process`
- `POST /api/chat`

Student performance source:

- `STUDENT_PERFORMANCE_URL_TEMPLATE` (default)
- `https://git-connect-backend-v2.vercel.app/api/student/{student_id}/performance`

## Hugging Face Spaces Deployment

This repository is set up for Docker Spaces deployment.

Deployment-critical files:

- `Dockerfile`
- `requirements.txt`
- `app/`
- `.github/workflows/deploy-hf-space.yml`

Files excluded from git push:

- `.env` and `app/.env`
- generated `data/` files
- local caches and `__pycache__/`

GitHub Action deployment workflow:

- Trigger: push to `main` or manual run
- Workflow: `.github/workflows/deploy-hf-space.yml`
- Required repository secrets:
  - `HF_TOKEN`
  - `HF_SPACE_REPO_ID` (format: `username/space-name`)

## Sample Requests

Syllabus processing:

```json
[
  {
    "course_code": "22CS501",
    "name": "Database Management Systems",
    "course_type": "theory",
    "syllabus_url": "https://example.com/dbms.pdf",
    "semester": 5
  }
]
```

Chat:

```json
{
  "query": "How can I improve attendance this semester?",
  "history": [
    {"role": "user", "content": "Hi"},
    {"role": "assistant", "content": "Hello"}
  ],
  "student_id": 2,
  "lang_code": "en",
  "semester": 5
}
```

Configuration reference:

- https://huggingface.co/docs/hub/spaces-config-reference