1. Start here: what this assignment is

This guide has two paths. Path A is the basic submission: enough to pass. Do that first. Path B is add-ons: choose one or two only if you have time and energy.

By the end of the basic path, you will have a live `/ask` endpoint on the internet that returns structured JSON with an answer, token usage, and cost — plus a Streamlit UI that calls it. That is already a real deployed AI service with a demo front end.

Basic submission: what counts

2. Before you build: what you are building

• Someone sends your service a question, for example: "What is RAG in one sentence?"
• Your service asks an AI model for the answer.
• It sends back a clean, predictable response with `answer`, `tokens_used`, and `cost_usd`.
• Done means a public HTTPS URL someone else can hit, not just localhost.

Preflight: accounts and safety

3. Path A: Basic submission

Do these steps first. When the basic checklist is done, you have passed the assignment. Stop there if you are tired.

Step 1: Get the starter code

1. Open the Week 1 `/ask` demo repo link from the syllabus page.
2. Click Fork (top right on GitHub) to create your own copy.
3. On your fork, click the green Code button and copy the fork URL.

I am a complete beginner. Please clone this GitHub repository to my computer and open it: [PASTE YOUR FORK URL HERE].
Then give me a one-paragraph plain-English summary of what this project does and what the 5 stages are.

Read the AI’s summary. You now understand the project you’re deploying.

Step 2: Set up your environment

When you get the setup prompt, create your venv, install dependencies, and edit your `.env` file locally. Paste your OpenAI key only where it belongs.

Set this project up for me step by step:
1. Create a Python virtual environment and activate it
2. Install everything in requirements.txt
3. Copy .env.example to .env and tell me exactly where to paste my OpenAI API key
4. Do NOT print my API key back to me at any point

Explain each step in one simple sentence as you go. I have never done this before.

Step 3: Run locally and test once

Now:
1. Start the stage 5 server with uvicorn on port 8000
2. Run python test_all_stages.py and show me the results
3. Send a test question to the /ask endpoint using curl and show me the JSON response
4. Confirm the response contains three things: answer, tokens_used, and cost_usd

If anything fails, fix it and explain what was wrong in simple terms.

Step 4: Push your code back to GitHub

Before doing anything else, run git status and confirm that .env does NOT appear in the list of files to be committed, and that .env is listed inside the .gitignore file.
If .env is not in .gitignore, add it first.
Only then commit all my changes with a sensible commit message and push them to my fork on GitHub.
After pushing, confirm once more that .env was not uploaded.

Double-check with your own eyes: after pushing, open my repo on github.com in the browser and look at the file list. You should see .env.example but you should NOT see .env.

If you can see .env on GitHub, your key has leaked. Revoke the key at platform.openai.com, create a new one, update `.env` locally and on Render, and ask me to remove the old secret from the repo and its history immediately.

Step 5: Deploy to Render (in your browser)

This part happens in your web browser, not inside Claude Code or Cursor.

1. Go to render.com and log in.
2. Click New + → Web Service.
3. Connect your GitHub account (if asked), then select your forked repo.
4. Fill in the settings: - Runtime: Python - Build Command: `pip install -r requirements.txt` - Start Command: `uvicorn main:app --host 0.0.0.0 --port $PORT`
5. Add Environment Variables: - Key: `OPENAI_API_KEY` - Value: your key (paste it here in Render; this is the safe place for it).
6. Click Create Web Service and wait for it to turn green (“Live”).
7. Copy your public URL (looks like `https://your-service.onrender.com`).

Step 6: Prove it works from the outside

My service is now live at https://YOUR-SERVICE.onrender.com.
Run this exact curl command and show me the full response.

Confirm the response is valid JSON with answer, tokens_used, and cost_usd.

curl -s -X POST https://YOUR-SERVICE.onrender.com/ask \
  -H "Content-Type: application/json" \
  -d '{"question": "What is RAG in one sentence?", "model": "gpt-4o-mini"}'

Screenshot the curl request and the JSON response. This is your headline proof.

Step 7: Run the Streamlit UI

The Week 1 starter includes a Streamlit demo. Run it so it calls your `/ask` API (local or live). A curl-only submission without a UI does not pass.

This repo includes a Streamlit demo UI. Please:
1. Show me how to run it locally (exact command)
2. Point it at my /ask API (local http://127.0.0.1:8000 or my live Render URL)
3. Confirm I can type a question in the UI and get back answer, tokens_used, and cost_usd
4. Tell me what screenshot to take for Maven proof

If the Streamlit app is missing or broken, create a minimal one-page Streamlit UI that POSTs to /ask and displays the JSON fields.

4. Stop point: basic submission is done

5. Path B: Optional add-ons

Add-on prompt: prove the guardrail works

The repo includes a built-in switch called `force_bad` to make the model produce deliberately malformed output.

This repo has a force_bad option (stage 3 and above) that makes the model produce deliberately malformed output. Please:
1. Show me how to trigger it
2. Trigger it and show me what the guardrail does when validation fails
3. Explain in two sentences what would have happened WITHOUT the guardrail

Then turn force_bad off again.

Add-on prompt: explain your choices

Based on this project, help me write three short answers in my own plain words:
1. Which model this uses by default and a one-sentence justification (quality vs cost vs latency)
2. The approximate cost per call, using the real cost_usd from my live response
3. What the guardrail does when validation fails (retry, safe default, or controlled error), based on what the code actually does

Keep each answer to one or two sentences. No jargon.

6. Share + troubleshoot

• In Maven: post your live URL, the curl command, a Streamlit screenshot, and one specific thing you want feedback on.
• On LinkedIn: attach 2 to 4 screenshots (curl request, JSON response with answer + tokens + cost, Streamlit UI, optional guardrail demo). Credit the program. Do not include your live URL.

Troubleshooting (6 common problems)

• Command not found: python / pip: paste the error into your coding tool and ask it to detect your OS and install Python 3.11+ + venv.
• Invalid API key / 401: your key is missing or wrong. Check Render environment variables and your local `.env` (no spaces, no quotes).
• Insufficient quota / 429: you need more credit. Go to platform.openai.com → Billing and add ~$5 manually (keep auto-recharge off).
• You think the key leaked: revoke immediately, create a new key, update `.env` locally and Render, and remove the secret from GitHub history if needed.
• Render deploy fails: copy the Render log error, paste it into your AI tool, and ask what you need to change.
• Live URL times out on first try: free Render services can sleep. Wait 60 seconds and retry.