{ "cells": [ { "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 }