This guide walks you through the Week 1 assignment step by step using Claude Code or Cursor as your coding partner. You do not need to write code yourself. Your job is to give the AI the right instructions, check the results, and ship.

By the end, you will have a live URL on the internet that anyone can send a question to and get a structured AI response back. That is a real, deployed AI service built by you.

What you are building (in plain English)

• Someone sends your service a question (example: "What is RAG in one sentence?").
• It asks an AI model for the answer.
• It sends back a clean, predictable response that always includes: answer, tokens_used, and cost in dollars.
• If the AI gives back something broken or malformed, a guardrail catches it instead of passing garbage to the user.
• Done means a public HTTPS URL someone else can hit — not just localhost.

Before you start: accounts you need

Step 1: Get the starter code onto your machine

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 it locally and test it

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: Prove the guardrail works

The repo includes a built-in switch called `force_bad` to make the model produce deliberately malformed output. Your job is to prove the guardrail catches it.

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.

Screenshot the guardrail catching the bad output. This is one of your proof points.

Step 5: 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 6: 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 7: 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 8: Document 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.

Step 9: Share it

• In Maven or WhatsApp: post your live URL, the curl command, your model choice in one sentence, and one specific thing you want feedback on.
• On LinkedIn: attach 2 to 4 screenshots (curl request, JSON response with answer + tokens + cost, 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.