scripts/README.md

# Scripts Directory

This directory contains utility scripts for the AI Agents Final Assignment.

## fetch_questions.py

A script to fetch all questions from the API and store them in JSON format.

### Features

- Fetches all questions from the default API endpoint
- Stores questions in JSON format with metadata
- Creates timestamped files for version tracking
- Maintains a `questions_latest.json` file with the most recent fetch
- Displays sample questions for verification
- Handles errors gracefully

### Usage

```bash
# Run from the project root directory
python3 scripts/fetch_questions.py
```

### Output

The script creates JSON files in the `data/` directory:

- `questions_YYYYMMDD_HHMMSS.json` - Timestamped version
- `questions_latest.json` - Always contains the most recent fetch

### JSON Structure

```json
{
  "metadata": {
    "fetch_timestamp": "2026-02-18T06:57:43.123456",
    "api_url": "https://agents-course-unit4-scoring.hf.space",
    "total_questions": 20
  },
  "questions": [
    {
      "task_id": "unique-task-id",
      "question": "The question text...",
      "Level": "1",
      "file_name": "optional-file.png"
    }
  ]
}
```

### Question Properties

Each question object contains:

- **task_id**: Unique identifier for the question
- **question**: The question text
- **Level**: Difficulty level (e.g., "1")
- **file_name**: Associated file (if any) - could be images (.png), audio (.mp3), Python files (.py), or Excel files (.xlsx)

### API Configuration

The script uses the following API configuration:

- **Base URL**: `https://agents-course-unit4-scoring.hf.space`
- **Endpoint**: `/questions`
- **Method**: GET
- **Response Format**: JSON (application/json)

### Error Handling

The script handles:

- Network errors
- JSON decoding errors
- Empty responses
- File system errors

All errors are logged to the console with descriptive messages.