README.md

---
title: Intern Problem Solver API
emoji: 🧠
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false
app_port: 7860
---

# Intern Problem-Solving API

A multi-agent FastAPI backend that helps interns understand real-world problems and build structured thinking. Five specialized agents run in sequence — each feeding context to the next — to deliver a complete analysis with actionable next steps.

## Agent Pipeline

```
Input → [1] Problem Analyst → [2] Root Cause → [3] Solutions → [4] Action Plan → [5] Thinking Coach
```

| Agent | Job |
|-------|-----|
| Problem Analyst | Identifies core problem, stakeholders, known vs unknown |
| Root Cause Analyst | Breaks down WHY the problem exists across technical, process, and people dimensions |
| Solution Brainstorm | Generates 7 diverse ideas — quick wins, medium-term, strategic, and unconventional |
| Action Planner | 3 concrete next steps the intern can start immediately |
| Thinking Coach | Honest feedback on the intern's framing — are they a problem solver or task executor? |

---

## Endpoints

| Method | Endpoint | Returns |
|--------|----------|---------|
| `GET` | `/` | API info and endpoint list |
| `GET` | `/health` | Health check |
| `POST` | `/analyze` | Full analysis as JSON |
| `POST` | `/analyze/stream` | Server-sent events — streams each agent live |
| `POST` | `/analyze/pdf` | Downloadable PDF report |

---

## Request Body

All three `POST` endpoints accept the same JSON body:

```json
{
  "content": "Paste your problem, transcript, or blocker here",
  "intern_name": "Your Name",
  "intern_role": "AI Developer Intern",
  "intern_goal": "What you are trying to achieve this week"
}
```

| Field | Required | Default |
|-------|----------|---------|
| `content` | ✅ Yes | — |
| `intern_name` | No | `"Intern"` |
| `intern_role` | No | `"AI Developer Intern"` |
| `intern_goal` | No | `""` |

---

## Response — `/analyze`

```json
{
  "problem_statement": "## Core Problem\n...",
  "root_causes": "## Root Cause Analysis\n...",
  "solutions": "## Solution Ideas\n...",
  "action_plan": "## Your Next Steps\n...",
  "thinking_feedback": "## Thinking Feedback\n..."
}
```

---

## Response — `/analyze/stream`

Server-sent events. Each event is a JSON object on a `data:` line:

```
data: {"event": "agent_start", "agent": "analyst", "label": "Problem Analyst"}

data: {"event": "token", "agent": "analyst", "text": "## Core Problem\n"}

data: {"event": "agent_done", "agent": "analyst"}

data: {"event": "done"}
```

Event types:

| Event | Fields | Meaning |
|-------|--------|---------|
| `agent_start` | `agent`, `label` | Agent has started running |
| `token` | `agent`, `text` | Next streamed token from this agent |
| `agent_done` | `agent` | Agent finished |
| `done` | — | All 5 agents complete |

---

## Setup

### Environment Variable

Set this as a **Secret** in your HuggingFace Space settings:

```
ANTHROPIC_API_KEY=sk-ant-...
```

Do not put it in the Dockerfile or commit it to the repo.

### Files Required

```
main.py
requirements.txt
Dockerfile
README.md
```

---

## Local Development

```bash
# Install dependencies
pip install -r requirements.txt

# Run with your API key
ANTHROPIC_API_KEY=sk-ant-... uvicorn main:app --reload --port 7860
```

API docs available at `http://localhost:7860/docs` once running.

---

## Client

The frontend (`client.html`) is a standalone HTML file — no build step, no framework. Host it anywhere: a second HF Space (static SDK), GitHub Pages, or just open it locally in a browser.

Point the **Backend API URL** field in the client to this Space's URL:
```
https://your-username-intern-problem-solver.hf.space
```

---

## Stack

- **FastAPI** — API framework
- **Anthropic SDK** — claude-sonnet-4-6 for all agents
- **ReportLab** — PDF generation
- **Uvicorn** — ASGI server