Update README.md

README.md

@@ -1,13 +1,157 @@
 ---
-title: Problem Decoder
-emoji: 🌖
-colorFrom: purple
+title: Intern Problem Solver API
+emoji: 🧠
+colorFrom: blue
 colorTo: indigo
-sdk: gradio
-sdk_version: 6.14.0
-python_version: '3.13'
-app_file: app.py
+sdk: docker
 pinned: false
+app_port: 7860
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 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