{ "cells": [ { "cell_type": "markdown", "metadata": { }, "source": [ "*Module 1 Self-Driven Lab*\r\n", "\r\n", "# Dev Environment \u0026 Foundations\r\n", "\r\n", "**Objective:** confirm your dev environment and master the identification of critical API signals like `stop_reason` and `usage`.\r\n", "\r\n", "## Challenge Outline\r\n", "\r\n", "Build a complete notebook that demonstrates the following outcomes:\r\n", "\r\n", "- **Stateless request:** use the Messages API to send a `\"Hello Claude\"` prompt. Print the entire Message object.\r\n", "- **Signal inspection:** identify the `stop_reason`. Verify it is `\"end_turn\"`. Explain why parsing response text for phrases like `\"I am finished\"` is a loop termination anti-pattern.\r\n", "- **Token auditing:** inspect the `usage` block. Identify `input_tokens` and `output_tokens`. Calculate the cost of the request, applying the 1.1x multiplier for Opus 4.6+ when `inference_geo: \"us\"` is used.\r\n", "- **Signal simulation:** manually modify a request to include a mock tool. Verify that the API returns `stop_reason: \"tool_use\"`. Explain how this signal drives the next iteration of the loop.\r\n", "\r\n", "Your solution should include enough code, output, or written observations to prove each outcome worked. Keep the notebook focused on final behavior and evidence rather than a guided walkthrough.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "## Student Workspace\n", "\n", "Use the sections below to build your solution. Each section maps to one required outcome from the challenge outline.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Part 1: Stateless request\n", "\n", "use the Messages API to send a `\"Hello Claude\"` prompt. Print the entire Message object.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Part 1: Stateless request\n", "# Add your implementation, outputs, or notes here.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Part 2: Signal inspection\n", "\n", "identify the `stop_reason`. Verify it is `\"end_turn\"`. Explain why parsing response text for phrases like `\"I am finished\"` is a loop termination anti-pattern.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Part 2: Signal inspection\n", "# Add your implementation, outputs, or notes here.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Part 3: Token auditing\n", "\n", "inspect the `usage` block. Identify `input_tokens` and `output_tokens`. Calculate the cost of the request, applying the 1.1x multiplier for Opus 4.6+ when `inference_geo: \"us\"` is used.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Part 3: Token auditing\n", "# Add your implementation, outputs, or notes here.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Part 4: Signal simulation\n", "\n", "manually modify a request to include a mock tool. Verify that the API returns `stop_reason: \"tool_use\"`. Explain how this signal drives the next iteration of the loop.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Part 4: Signal simulation\n", "# Add your implementation, outputs, or notes here.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Verification Notes\n", "\n", "Summarize the evidence that each part worked. Capture API signals, validation outcomes, errors, recovery behavior, cost observations, or comparisons required by this lab.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Verification notes\n", "# Record the evidence that proves each lab outcome worked.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "---\n", "\n", "## Answer Key\n", "\n", "The cells below contain the completed reference implementation/content for this module. Use this section only after attempting the self-driven lab." ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "*Prerequisites*\n", "\n", "# Dev Environment \u0026 Foundations\n", "\n", "Before writing any code, you need three things working: **VS Code** as your editor, **Jupyter notebooks** for interactive development, and the **Anthropic Python SDK** connected to a valid API key. This module gets all three running and ends with a verified \"Hello Claude\" test.\n", "\n", "\n", "## 1. What You\u0027ll Need\n", "\n", "- **Python 3.9 or later**, check with `python --version` or `python3 --version`\n", "- **VS Code**, download from `code.visualstudio.com`\n", "- **An Anthropic API key**, obtained from `console.anthropic.com`\n", "- ~10 minutes and a terminal\n", "\n", "## 2. Install VS Code Extensions\n", "\n", "Open VS Code and install these two extensions from the Extensions panel (`Ctrl+Shift+X` / `Cmd+Shift+X`):\n", "\n", "- **Python**, publisher: *ms-python*. Enables Python language support, linting, and virtual environment detection.\n", "- **Jupyter**, publisher: *ms-toolsai*. Lets you run `.ipynb` notebooks directly inside VS Code without launching a browser.\n", "\n", "## 3. Create Your Project Folder\n", "\n", "Pick a home for your lab files. All 10 modules will build on the same notebook, so one folder is all you need.\n", "\n", "```bash\n", "mkdir claude-architect-lab\n", "cd claude-architect-lab\n", "```\n", "\n", "## 4. Set Up a Virtual Environment\n", "\n", "A virtual environment keeps the SDK and its dependencies isolated from the rest of your system, important when you\u0027re working with multiple Python projects.\n", "\n", "```bash\n", "# Create the environment\n", "python -m venv .venv\n", "\n", "# Activate it\n", "# macOS / Linux:\n", "source .venv/bin/activate\n", "\n", "# Windows (PowerShell):\n", ".venv\\Scripts\\Activate.ps1\n", "\n", "# Windows (Command Prompt):\n", ".venv\\Scripts\\activate.bat\n", "```\n", "\n", "Your terminal prompt should now show `(.venv)` to confirm it\u0027s active.\n", "\n", "## 5. Install Dependencies\n", "\n", "```bash\n", "pip install anthropic python-dotenv ipykernel\n", "```\n", "\n", "- **anthropic**, the official Python SDK for the Claude API\n", "- **python-dotenv**, loads your `.env` file so the API key is never hardcoded\n", "- **ipykernel**, registers your virtual environment as a Jupyter kernel so VS Code can find it\n", "\n", "## 6. Get Your API Key\n", "\n", "- Go to `console.anthropic.com` and sign in (or create a free account).\n", "- Navigate to **API Keys** in the left sidebar.\n", "- Click **Create Key**, give it a name like *\"architect-lab\"*, and copy the key, it starts with `sk-ant-`.\n", "\n", "You only see the full key once, so copy it immediately.\n", "\n", "## 7. Store Your Key Safely\n", "\n", "Create two files in your project folder:\n", "\n", "*.env*\n", "```\n", "ANTHROPIC_API_KEY=sk-ant-api03-YOUR-KEY-HERE\n", "```\n", "\n", "*.gitignore*\n", "```\n", ".env\n", ".venv/\n", "__pycache__/\n", "*.pyc\n", ".ipynb_checkpoints/\n", "```\n", "\n", "\u003e **Tip.** **Never commit your API key.** The `.gitignore` above ensures `.env` stays local. If you accidentally push a key, rotate it immediately in the Anthropic console, old keys can be used by anyone who finds them in your git history.\n", "\n", "## 8. Create Your Lab Notebook\n", "\n", "- Open your project folder in VS Code: `File → Open Folder`\n", "- Create a new file named `lab.ipynb` (`File → New File`, then save with the `.ipynb` extension).\n", "- VS Code will open it as a notebook. In the top-right corner, click **Select Kernel**.\n", "- Choose **Python Environments** → select the `.venv` you just created. If it doesn\u0027t appear, run `Python: Select Interpreter` from the command palette first.\n", "\n", "## 9. Hello Claude, Your First Cell\n", "\n", "Add a new code cell and paste the following. Run it with `Shift+Enter`." ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "import anthropic\n", "from dotenv import load_dotenv\n", "\n", "load_dotenv() # reads ANTHROPIC_API_KEY from your .env file\n", "\n", "client = anthropic.Anthropic()\n", "\n", "message = client.messages.create(\n", " model=\"claude-sonnet-4-6\",\n", " max_tokens=256,\n", " messages=[\n", " {\"role\": \"user\", \"content\": \"In one sentence, what is the Claude API?\"}\n", " ]\n", ")\n", "\n", "print(message.content[0].text)" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "If everything is configured correctly, you should see a one-sentence response from Claude. That\u0027s your environment confirmed.\n", "\n", "## 10. Understanding the Response Object\n", "\n", "Before moving to Module 2, it\u0027s worth knowing what the API returned. Add a second cell:" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "print(\"Stop reason:\", message.stop_reason)\n", "print(\"Input tokens:\", message.usage.input_tokens)\n", "print(\"Output tokens:\", message.usage.output_tokens)\n", "print(\"Model:\", message.model)" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "- **stop_reason**, `\"end_turn\"` means Claude finished naturally. The exam tests this heavily.\n", "- **usage**, input and output token counts used to calculate cost.\n", "- **model**, confirms which model version actually ran your request.\n", "\n", "### API Signal to Remember: `tool_use` vs. `end_turn`\n", "\n", "Agentic control flow starts with this one field:\n", "\n", "- `stop_reason == \"tool_use\"` means the loop continues. Your application must execute the requested tool, append a matching `tool_result`, and call Claude again with the full updated history.\n", "- `stop_reason == \"end_turn\"` means the loop terminates. Claude has completed its turn without requesting another tool.\n", "\n", "Do not check whether Claude *said* it is done. Use the structured `stop_reason` value.\n", "\n", "\u003e **Tip.** **Keep your notebook cells small and purposeful.** Each lab module adds new cells to this same `lab.ipynb`. A well-structured notebook with clear headings and focused cells is also good practice for the structured output modules later in the lab.\n", "\n", "## Troubleshooting\n", "\n", "| Problem | Most likely cause | Fix |\n", "| --- | --- | --- |\n", "| `AuthenticationError` | .env not found or key is wrong | Check the file is in the project root, not a subfolder. Confirm no extra spaces around the `=`. |\n", "| Kernel not listed | .venv not registered with Jupyter | Run `python -m ipykernel install --user --name .venv` inside your activated environment. |\n", "| `ModuleNotFoundError: anthropic` | Wrong Python environment active | Confirm `(.venv)` is in your terminal prompt, then re-run `pip install anthropic`. |\n", "| VS Code shows \"No kernel\" | Jupyter extension not installed | Install the *Jupyter* extension from the Extensions panel and reload VS Code. |" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.11.0" } }, "nbformat": 4, "nbformat_minor": 5 }