prepspsc-pyq

当用户询问印度竞争性考试准备、锡金 PSC (SPSC) 问题、往年问题 (PYQ)、模拟考试生成、考试模式练习或需要用于 AI 驱动的问题生成的参考问题时使用。调用 SPSC 考试准备、PYQ 搜索、模拟测试、学科练习或印度政府工作考试学习。

## 概述（中文）

当用户询问印度竞争性考试准备、锡金 PSC (SPSC) 问题、往年问题 (PYQ)、模拟考试生成、考试模式练习或需要用于 AI 驱动的问题生成的参考问题时使用。调用 SPSC 考试准备、PYQ 搜索、模拟测试、学科练习或印度政府工作考试学习。

## 原文

# PrepSPSC PYQ API

Search 7,400+ real previous year questions from Sikkim PSC (SPSC) exams and generate mock tests across 64 exam patterns. Returns MCQ questions with options, correct answers, explanations, topics, cognitive levels, and difficulty metadata.

## Quick Reference

| Detail | Value |
|--------|-------|
| Base URL | `https://qqqditxzghqzodvauxth.supabase.co/functions/v1/pyq-api` |
| Auth | `Authorization: Bearer sk_live_YOUR_KEY` |
| Questions | 7,442 across 27 subjects |
| Exam Patterns | 64 (Civil Services, Police, Medical, Engineering, Education, IT, and more) |
| Get API Key | [prepspsc.com/developers](https://prepspsc.com/developers) |

## Authentication

All requests require a Bearer token in the `Authorization` header. API keys start with `sk_live_`.

### Check Existing Setup First

Before guiding the user through setup, check if the API key is already available:

```bash
if [ -n "$PREPSPSC_API_KEY" ]; then
  echo "Configured"
else
  echo "No API key found. Get one at https://prepspsc.com/developers"
fi
```

If no key is found, direct the user to https://prepspsc.com/developers to generate a free API key.

### Making Requests

```bash
curl -X POST "https://qqqditxzghqzodvauxth.supabase.co/functions/v1/pyq-api" \
  -H "Authorization: Bearer $PREPSPSC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "fundamental rights", "subject": "Indian Polity", "limit": 5}'
```

---

## Endpoints

### 1. List Available Subjects

**`GET /pyq-api`** — Returns all subjects with question counts. Call this first to see what's available.

```bash
curl "https://qqqditxzghqzodvauxth.supabase.co/functions/v1/pyq-api" \
  -H "Authorization: Bearer $PREPSPSC_API_KEY"
```

**Response:**
```json
{
  "subjects": [
    { "subject": "Indian Polity", "count": 842 },
    { "subject": "History", "count": 756 },
    { "subject": "General Knowledge", "count": 698 }
  ],
  "total_questions": 7442
}
```

Available subjects: General English, General Knowledge, Indian Polity, History, Geography, Science, Environment, Indian Economy, Arithmetic and Logical Reasoning, Agriculture, Botany, Zoology, Nepali Literature, Current Affairs, and more (27 total).

---

### 2. Search Questions (Semantic Search)

**`POST /pyq-api`** — Search PYQs using natural language. Uses vector similarity + keyword hybrid matching.

```bash
curl -X POST "https://qqqditxzghqzodvauxth.supabase.co/functions/v1/pyq-api" \
  -H "Authorization: Bearer $PREPSPSC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Fundamental Rights Article 21",
    "subject": "Indian Polity",
    "limit": 5,
    "threshold": 0.3
  }'
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Natural language search (min 3 chars) |
| `subject` | string | Yes | Subject to search within |
| `limit` | integer | No | Max results, 1-20 (default: 5) |
| `threshold` | number | No | Min similarity 0-1 (default: 0.3, lower = more results) |
| `year_min` | integer | No | Exclude time-sensitive questions older than this year |
| `exclude_ids` | string[] | No | Question UUIDs to exclude (for pagination) |

**Response:**
```json
{
  "questions": [
    {
      "id": "uuid",
      "question": "Which Article of the Indian Constitution guarantees the Right to Life?",
      "options": [
        { "id": "a", "text": "Article 14" },
        { "id": "b", "text": "Article 19" },
        { "id": "c", "text": "Article 21" },
        { "id": "d", "text": "Article 32" }
      ],
      "correct_option_id": "c",
      "explanation": "Article 21 states that no person shall be deprived of his life or personal liberty...",
      "subject": "Indian Polity",
      "topics": ["Fundamental Rights", "Article 21", "Right to Life"],
      "difficulty": "easy",
      "cognitive_level": "remember",
      "is_time_sensitive": false,
      "high_yield": true,
      "similarity": 0.89
    }
  ],
  "count": 5
}
```

---

### 3. Generate Mock Test

**`POST /pyq-api/mock-test`** — Generate a complete mock test following real SPSC exam patterns with difficulty balancing.

```bash
curl -X POST "https://qqqditxzghqzodvauxth.supabase.co/functions/v1/pyq-api/mock-test" \
  -H "Authorization: Bearer $PREPSPSC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pattern": "undersecretary-prelims",
    "difficulty_mix": { "easy": 30, "medium": 50, "hard": 20 }
  }'
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pattern` | string | Yes | Exam pattern ID (64 available, see below) |
| `difficulty_mix` | object | No | Custom difficulty % (default: 30/50/20) |
| `year_min` | integer | No | Exclude stale current affairs |
| `exclude_ids` | string[] | No | Skip questions from previous tests |

**Response includes:** test metadata (name, total questions, duration, marking scheme) + sections with difficulty-balanced questions.

#### Available Exam Patterns (64 Total)

**Core / General:** `undersecretary-prelims`, `general-prelims`, `spsc-mains-gs1`, `spsc-mains-gs2`, `quick-practice-30`

**Civil Services:** `sscs-prelims`, `combined-mains-gs3`, `combined-mains-english`

**Police / Law:** `si-police-prelims`, `si-police-mains`, `si-excise`, `sub-jailer`

**Fire Service:** `sub-fire-officer`

**Engineering:** `junior-engineer-prelims`, `assistant-engineer-civil`, `assistant-engineer-electrical`, `assistant-engineer-mechanical`, `assistant-engineer-agriculture`

**Medical / Health:** `gdmo`, `veterinary-officer`, `dental-surgeon`, `specialist-sr-grade`, `staff-nurse`, `paramedical`, `health-educator`, `mphw`, `drug-inspector`, `food-safety-officer`, `pharmacist-ayush`, `yoga-instructor-ayush`, `scientific-officer-ayush`, `tutor-clinical-instructor`

**Administrative:** `ldc-prelims`, `accounts-clerk`, `stenographer`, `cooperative-inspector`, `statistical-inspector`, `revenue-inspector`, `revenue-surveyor`, `commercial-tax-inspector`

**Forestry / Fisheries:** `forest-ranger-prelims`, `fisheries-officer`, `assistant-director-fisheries`, `livestock-assistant`

**Education:** `lecturer-diet`, `iti-instructor`, `principal-iti`, `assistant-professor-sheda`

**Other Specialized:** `assistant-town-planner`, `assistant-architect`, `assistant-geologist`, `digital-analyst`, `assistant-programmer`, `assistant-director-it`, `lab-assistant`, `field-assistant`, `ado-wdo-hdo`, `senior-information-assistant`, `sub-editor`, `inspector-legal-metrology`, `photographer`, `script-writer`, `feed-mill-operator`, `printing-stationery`

Use `GET /pyq-api/patterns` to get full details with subject distribution, duration, and marking scheme for each pattern.

---

### 4. List Exam Patterns

**`GET /pyq-api/patterns`** — Returns all 64 exam patterns with subject distribution, question counts, duration, and marking scheme.

```bash
curl "https://qqqditxzghqzodvauxth.supabase.co/functions/v1/pyq-api/patterns" \
  -H "Authorization: Bearer $PREPSPSC_API_KEY"
```

---

### 5. Record Progress

**`POST /pyq-api/progress`** — Record a user's answer to a question.

```bash
curl -X POST "https://qqqditxzghqzodvauxth.supabase.co/functions/v1/pyq-api/progress" \
  -H "Authorization: Bearer $PREPSPSC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "user123",
    "question_id": "uuid-here",
    "selected_option": "c",
    "is_correct": true,
    "time_spent_seconds": 45
  }'
```

### 6. Get User Progress

**`GET /pyq-api/progress?user_id=user123`** — Retrieve a user's complete answer history.

```bash
curl "https://qqqditxzghqzodvauxth.supabase.co/functions/v1/pyq-api/progress?user_id=user123" \
  -H "Authorization: Bearer $PREPSPSC_API_KEY"
```

---

### 7. Performance Analytics

**`GET /pyq-api/analytics?user_id=user123`** — Get accuracy by subject, difficulty breakdown, and recent activity.

```bas