---
title: GCAS Search API
emoji: 🎓
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 8000
pinned: false
---

# GCAS Excel Search Engine

Natural-language search API over Gujarat College Admissions System (GCAS) data. Supports English, Hindi (Hinglish), and Gujarati queries.

---

## Architecture

The engine runs a **two-tier pipeline** — structured lookup first, semantic fallback second.

**Tier 1 — Structured in-memory lookup (~50–200 ms)**
Every query is parsed into a `QueryPlan` (college name, district, university, program, gender, category, medium, type, intent). Resolved entities are matched directly against the in-memory data store with O(n) row scanning. This handles ~95% of real queries with `confidence: high`.

**Tier 2 — FAISS semantic fallback**
Only triggered when Tier 1 produces zero candidates (vague / open-ended queries with no resolved entities). The query is embedded and compared against dense FAISS vectors built over all ~50k rows.

**LLM reranking** is an explicit opt-in (`use_llm_rerank: true`) — it is NOT part of the default path. Default is `false`.

---

## Endpoints

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| `GET` | `/health` | No | Liveness check + index status |
| `GET` | `/schema` | No | Table names, columns, row counts |
| `POST` | `/search` | Bearer token | Natural-language search |
| `POST` | `/reindex` | Bearer token | Rebuild FAISS index from Excel folder |
| `GET` | `/docs` | No | Swagger UI (auto-generated) |
| `GET` | `/redoc` | No | ReDoc UI |

---

## POST /search

### Request body

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `query` | string | *required* | Query in English, Hindi (Hinglish), or Gujarati |
| `top_k` | int | 10 | Max results (1–100). Actual count may be lower — the engine auto-caps based on intent (e.g. hostel → 1, fees → 8) |
| `tables` | list[str] | null | Restrict to specific table name(s). null = all tables |
| `use_llm_rerank` | bool | **false** | Opt-in LLM reranking pass (adds ~3–10s latency) |
| `llm_provider` | string | server default | `"openai"` or `"anthropic"` |
| `llm_model` | string | server default | Model name override |
| `api_key` | string | server default | API key override for chosen provider |

### Response body

| Field | Type | Description |
|-------|------|-------------|
| `query` | string | Original query as submitted |
| `total_results` | int | Number of results returned |
| `results` | list[SearchResult] | Ranked result rows |
| `search_time_ms` | float | End-to-end latency |
| `reranked` | bool | Whether LLM reranking was applied |
| `detected_language` | string | `en` / `hi` / `gu` / `unknown` |
| `corrected_query` | string\|null | Query after alias resolution and entity correction |
| `entity_corrections` | list[EntityCorrection] | Spelling / ASR corrections applied |
| `confidence_level` | string | `high` (structured hit) / `medium` / `low` (FAISS fallback) |
| `detected_intent` | string | `fees` / `hostel` / `cutoff` / `facilities` / `courses` / `naac` / `contact` / `general` |
| `did_you_mean` | list[string] | Suggestions when confidence is low |

### SearchResult fields

| Field | Type | Description |
|-------|------|-------------|
| `table` | string | Source table (Excel filename stem) |
| `row_index` | int | Original row index in the Excel file |
| `score` | float | Relevance score (higher = more relevant) |
| `llm_reason` | string\|null | LLM explanation (only when `reranked: true`) |
| `data` | object | Row data filtered to fields relevant to the detected intent |

`data` is **intent-filtered**: only the columns relevant to your query intent are returned, keeping responses compact. For example, a `fees` query returns fee columns only; a `hostel` query returns hostel-specific fields.

---

## Supported Query Types

The engine is designed around the full GCAS query taxonomy:

**College-level queries**
- "M N College ke baare mein sab batao"
- "GLS College contact number"
- "NAAC A grade colleges in Ahmedabad"
- "Government colleges in Rajkot district"
- "Grant-in-aid Gujarati medium arts colleges"

**Fees queries**
- "Gujarat Commerce College ki fees kitni hai?"
- "B.Com fees in Surat government colleges"
- "SC category ke liye engineering fees"
- "Girls ke liye medical college fees in Vadodara"

**Hostel queries**
- "M N College mein girls hostel hai kya?"
- "Rajkot mein boys hostel wale colleges"
- "Engineering colleges with hostel facility in Ahmedabad"

**Cutoff / admission queries**
- "IMN Law College ka cutoff kya hai?"
- "GTU ke under OBC category computer science cutoff"
- "Mehsana district mein arts college cutoff"

**Program / courses queries**
- "M N College mein evening batch hai kya?"
- "BCA kahan kahan milta hai Gujarat mein?"
- "Rajkot mein law college hai kya?"
- "LLB kitne saal ka course hai?"

**Infrastructure / facilities**
- "Anand district mein library wale colleges"
- "NAAC accredited self-financed colleges under GTU"

---

## Authentication

All `POST` endpoints require a Bearer token:

```
Authorization: Bearer <API_SECRET_TOKEN>
```

The token is configured via the `API_SECRET_TOKEN` environment variable on the server. If not set, the API runs open (dev mode).

---

## Example (curl)

```bash
curl -X POST https://tanmay-bm-gsearch-api.hf.space/search \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "GLS College ki fees kitni hai",
    "top_k": 5
  }'
```

```bash
# With LLM reranking (slower, ~3-10s extra)
curl -X POST https://tanmay-bm-gsearch-api.hf.space/search \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "engineering colleges in Ahmedabad with hostel and NAAC A grade",
    "top_k": 5,
    "use_llm_rerank": true,
    "llm_provider": "openai",
    "api_key": "sk-..."
  }'
```

---

## Data Tables

| Table | Description |
|-------|-------------|
| `CollegeMaster` | College identity, type, district, university, NAAC grade, medium, gender |
| `CollegeIntakeMaster` | Programs offered, intake seats, fees by category |
| `CollegeInfrastructure` | Hostel, library, labs, sports, and other facilities |
| `CutOff_2025-26` | Admission cutoff ranks by program, round, and category |

---

## Multilingual Support

Queries can mix English, Hindi (Hinglish romanised), and Gujarati. The normaliser handles common transliterations:

| Input | Resolved |
|-------|----------|
| `ki fees kitni hai` | fees |
| `ke baare mein sab batao` | (removed) |
| `hostel milta hai kya` | hostel available |
| `kitne saal ka course` | how many years course |
| `kahan milta hai` | where available |

College names, district names, and university names are fuzzy-matched against the database vocabulary (edit distance + phonetic matching), so typos and ASR errors are automatically corrected.