README.md

---
title: ai_vidya Pipeline Agent
emoji: 🤖
colorFrom: purple
colorTo: blue
sdk: docker
app_file: app.py
pinned: false
---

# ai_vidya_bot

Slack agent for the AI Department intern pipeline.
Manages Week 0 through Probation (W1 + W2) in #ai_vidya.

## File structure

```
ai_vidya_bot/
├── main.py          # Flask app + Slack event endpoint
├── router.py        # Event classifier and dispatcher
├── handlers.py      # Four event handlers
├── scheduler.py     # APScheduler cron jobs
├── sheets.py        # Google Sheets read/write layer
├── parser.py        # Report format parser and quality scorer
├── prompts.py       # Claude evaluation prompts (Week 0, W1, W2)
├── requirements.txt
└── .env.example
```

## Setup

### 1. Google Sheets

Create a Google Sheet with these 7 tabs (exact names):
- `candidates`
- `reports_log`
- `signals_log`
- `warnings_log`
- `commitments`
- `evaluations`
- `decisions_log`

Add headers to each tab matching the column names in `sheets.py`.

Create a Google Service Account, download the JSON key,
and share the sheet with the service account email.

### 2. Slack app

Create a Slack app at https://api.slack.com/apps

Required OAuth scopes:
- `chat:write`
- `channels:history`
- `im:write`
- `im:read`
- `users:read`

Enable Event Subscriptions. Set the request URL to:
`https://your-space.hf.space/slack/events`

Subscribe to bot events:
- `message.channels`

Install the app to your workspace and invite it to #ai_vidya.

### 3. HuggingFace Spaces

Create a new Space (SDK: Docker or Gradio).

Add all variables from `.env.example` as Secrets in the Space settings.

Upload the `service_account.json` file and set `GOOGLE_SERVICE_ACCOUNT_PATH`
to its path in the Space filesystem.

### 4. Deploy

```bash
pip install -r requirements.txt
gunicorn main:app --bind 0.0.0.0:7860
```

## Adding a candidate

POST to `/admin/add_candidate`:

```json
{
  "slack_user_id": "U12345",
  "name": "Arjun Mehta",
  "cohort_id": "COHORT_001",
  "ft_slack_id": "U67890",
  "hr_slack_id": "U11111",
  "week0_start_date": "2025-05-12"
}
```

## Logging a Week 2 commitment

POST to `/admin/log_commitment` after the Day 6 FT conversation:

```json
{
  "candidate_id": "CAND_001",
  "description": "Streaming component working and tested",
  "due_date": "2025-05-21",
  "due_time": "EOD"
}
```

## Report format (candidates post this in #ai_vidya)

```
Name: [full name]
Date & Time: [now]
What I worked on: [description]
What I got stuck on: [specific blocker or 'nothing today']
What I tried to resolve it: [what you attempted]
Current status: [where things stand]
```

## Cron schedule (IST)

| Time | Job |
|------|-----|
| 9:00 AM | Morning FT brief |
| 12:30 PM | Missed report check (noon window) |
| 5:30 PM | Missed report check (5pm window) |
| 6:00 PM | EOD signal questions to FT |
| 6:30 PM (Wed) | Deadline check — Wednesday deliverable |
| 12:00 PM (Fri) | Deadline check — Friday deliverable |
| 8:00 PM | End-of-stage evaluation (Day 5 + Day 10) |
| 10:30 PM | Missed report check (10pm window) |