Chapter 1

Meet the Agent You Are About to Build

📖 Chapter 1 – Shipping Your First AI Agent (Part 1 of 4)

Before You Start

• A computer with internet access
• Basic Python knowledge (variables, functions, loops)
• ~2 hours of focused time
• You do NOT need: a GPU, a server, or prior AI experience

Get Your OpenAI API Key

What is an API? An API (Application Programming Interface) is how one program talks to another. Think of it like a waiter in a restaurant — you (your code) tell the waiter (API) what you want, the waiter goes to the kitchen (the server), and brings back your food (the response). You never talk to the kitchen directly.

1. Go to https://platform.openai.com/api-keys
2. Log in (free account)
3. Click "Create new secret key"
4. Name it (e.g., "adhikk")
5. Click "Create"
6. Copy the key (starts with sk-) — you will not see it again
7. Paste into your .env file

New accounts get $5 free credit — enough for this entire book.

Create & Activate Virtual Environment

What is a virtual environment (venv)? It is a separate, isolated Python world for your project. Without it, packages from different projects can conflict. With a venv, each project gets its own clean set of packages. Think of it like a separate browser profile for each website.

uv venv

Activate (Windows PowerShell):

.venv\Scripts\Activate

Activate (Mac/Linux):

source .venv/bin/activate

How you'll know it worked: Your prompt shows (.venv) at the start.

Install Python (if not already installed)

1. Go to https://www.python.org/downloads/
2. Click "Download Python 3.12.x"
3. Run the installer

4. CHECK the box: Add python.exe to PATH

   What is PATH? PATH is a list of folders your computer checks when you type a command. If you type python, your computer looks in each PATH folder for a file called python.exe. If it finds it, it runs it. If not, you get "command not found." Installing Python with "Add to PATH" checked adds Python's folder to this list.

5. Click "Install Now"

6. Close and reopen your terminal

Verify:

python --version

Expected output:

Python 3.12.x

Why This Matters – In today’s job market a static résumé is no longer enough. A 24 × 7 AI‑powered digital avatar can field recruiter messages, schedule interviews, and even nurture leads while you focus on building great software. This chapter shows you how to lay the foundation for that avatar.

🎯 What You’ll Build

By the end of this chapter you will have a runnable skeleton for a personal AI assistant that:

1. Runs as a FastAPI web service (so you can embed it anywhere).
2. Talks to OpenAI’s GPT‑4o (or any compatible LLM).
3. Exposes a simple JSON API that accepts a user message and returns the assistant’s reply.
4. Registers eight “tool” placeholders that we will flesh out in later chapters (e.g., calendar, email, CRM, web‑search).

You won’t see the full‑blown functionality yet, but the project layout will be ready for the next three chapters.

📚 Content

📁 Project Files

Below is the exact file tree you should end up with:

ai-digital-assistant/
├─.env
├─ requirements.txt
├─ config.py
├─ assistant.py
├─ main.py
└─ tools/
 ├─ __init__.py
 ├─ calendar.py
 ├─ email.py
 ├─ crm.py
 ├─ websearch.py
 └─. (four more placeholders)

💡 Tip: Keep the repository under version control from day 1 (git init && git add. && git commit -m "Initial scaffold"). It makes later refactors painless.

1️⃣ requirements.txt

# Save as: requirements.txt
fastapi==0.110.0
uvicorn[standard]==0.27.0
python-dotenv==1.0.1
openai==1.30.0
pydantic==2.7.0

✅ Verify: Run pip install -r requirements.txt inside a clean virtual environment. No errors should appear.

2️⃣ .env

# Save as:.env
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

⚠️ Warning: Never commit your .env file to a public repo. Add it to .gitignore.

✅ Verify: After installing python-dotenv, you can test loading the variable:

python -c "from dotenv import load_dotenv, find_dotenv; load_dotenv(find_dotenv()); import os; print('Key loaded' if os.getenv('OPENAI_API_KEY') else 'Missing')"

Expected output:

Key loaded

3️⃣ config.py

# Save as: config.py
import os
from dotenv import load_dotenv

load_dotenv() # Pull values from.env into os.environ

OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
if not OPENAI_API_KEY:
 raise EnvironmentError("OPENAI_API_KEY not set in environment")

✅ Verify: Import the module in a REPL:

>>> import config
>>> config.OPENAI_API_KEY[:5]'sk-xx'

4️⃣ tools/__init__.py

# Save as: tools/__init__.py
"""
Placeholder implementations for the eight tools we will flesh out later.
Each tool receives a dictionary `payload` and returns a string result.
"""

def calendar_tool(payload: dict) -> str:
 """Stub for scheduling meetings."""
 return "🗓️ Calendar tool invoked – not yet implemented."

def email_tool(payload: dict) -> str:
 """Stub for sending emails."""
 return "✉️ Email tool invoked – not yet implemented."

def crm_tool(payload: dict) -> str:
 """Stub for personal CRM actions."""
 return "📇 CRM tool invoked – not yet implemented."

def websearch_tool(payload: dict) -> str:
 """Stub for live web searches."""
 return "🔎 Web‑search tool invoked – not yet implemented."

# Additional four placeholders
def placeholder_tool_5(payload: dict) -> str: return "🔧 Placeholder 5"
def placeholder_tool_6(payload: dict) -> str: return "🔧 Placeholder 6"
def placeholder_tool_7(payload: dict) -> str: return "🔧 Placeholder 7"
def placeholder_tool_8(payload: dict) -> str: return "🔧 Placeholder 8"

# Registry that the assistant can look up by name
TOOL_REGISTRY = {
 "calendar": calendar_tool,
 "email": email_tool,
 "crm": crm_tool,
 "websearch": websearch_tool,
 "tool5": placeholder_tool_5,
 "tool6": placeholder_tool_6,
 "tool7": placeholder_tool_7,
 "tool8": placeholder_tool_8,
}

✅ Verify: In a Python shell:

>>> from tools import TOOL_REGISTRY
>>> TOOL_REGISTRY["calendar"]({})
'🗓️ Calendar tool invoked – not yet implemented.'

5️⃣ assistant.py

# Save as: assistant.py
import json
from typing import Any, Dict, List
import openai
from config import OPENAI_API_KEY
from tools import TOOL_REGISTRY

openai.api_key = OPENAI_API_KEY

class AIAgent:
 """
 Thin wrapper around OpenAI’s chat completion endpoint.
 It knows how to:
 • Send the user’s message to the LLM.
 • Parse tool calls embedded in the LLM’s response.
 • Dispatch to the appropriate stub function.
 """
 def __init__(self, model: str = "gpt-4o-mini"):
 self.model = model

 def _format_message(self, user_msg: str) -> List[Dict[str, str]]:
 """Create the message payload for the chat API."""
 system_prompt = (
 "You are a digital assistant representing a software engineer. "
 "You can call the following tools when needed: "
 + ", ".join(TOOL_REGISTRY.keys())
 + ". Respond in JSON when you want to invoke a tool."
 )
 return [
 {"role": "system", "content": system_prompt},
 {"role": "user", "content": user_msg},
 ]

 def _parse_tool_response(self, response: str) -> Dict[str, Any]:
 """
 The LLM is instructed to reply with a JSON object:
 {
 "tool": "<tool_name>",
 "payload": {. }
 }
 If the response is not JSON, we treat it as a plain answer.
 """
 try:
 data = json.loads(response)
 if "tool" in data and "payload" in data:
 return data
 except json.JSONDecodeError:
 pass
 return {"answer": response.strip()}

 def _run_tool(self, tool_name: str, payload: dict) -> str:
 """Dispatch to the stub implementation."""
 tool_fn = TOOL_REGISTRY.get(tool_name)
 if not tool_fn:
 return f"❗ Unknown tool: {tool_name}"
 return tool_fn(payload)

 def chat(self, user_msg: str) -> str:
 """Main entry point – returns the final string to send back to the user."""
 messages = self._format_message(user_msg)

 # Call the LLM
 completion = openai.ChatCompletion.create(
 model=self.model,
 messages=messages,
 temperature=0.2,
 )
 raw_reply = completion.choices[0].message.content

 # Determine if the LLM wants to call a tool
 parsed = self._parse_tool_response(raw_reply)

 if "answer" in parsed:
 # Simple answer – no tool needed
 return parsed["answer"]
 else:
 # Tool call path
 tool_name = parsed["tool"]
 payload = parsed["payload"]
 tool_result = self._run_tool(tool_name, payload)
 # Return a combined message for now
 return f"Tool `{tool_name}` executed. Result: {tool_result}"

✅ Verify: Run a quick sanity check (no network call yet because we’ll use a mock later):

>>> from assistant import AIAgent
>>> agent = AIAgent()
>>> # Mock the LLM by monkey‑patching openai.ChatCompletion.create if you have no API key.
>>> # For now just ensure the object instantiates without error.
>>> isinstance(agent, AIAgent)
True

6️⃣ main.py

# Save as: main.py
import uvicorn
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from assistant import AIAgent

app = FastAPI(title="Personal AI Digital Assistant")
agent = AIAgent() # Singleton – cheap to keep in memory

class ChatRequest(BaseModel):
 message: str

class ChatResponse(BaseModel):
 reply: str

@app.post("/chat", response_model=ChatResponse)
def chat_endpoint(req: ChatRequest):
 """
 Accepts a user message, forwards it to the AIAgent,
 and returns the assistant’s reply.
 """
 if not req.message.strip():
 raise HTTPException(status_code=400, detail="Message cannot be empty")
 reply = agent.chat(req.message)
 return ChatResponse(reply=reply)

if __name__ == "__main__":
 # Run with: python main.py
 uvicorn.run(app, host="0.0.0.0", port=8000)

✅ Verify: Start the server and hit the endpoint:

python main.py

In another terminal:

curl -X POST http://127.0.0.1:8000/chat \
 -H "Content-Type: application/json" \
 -d '{"message":"Tell me about my experience"}'

Expected output (the exact wording may vary because the LLM generates it):

{
 "reply": "I am a software engineer with 5 years of experience building scalable web applications."
}

If the LLM decides to call a tool, you’ll see something like:

{
 "reply": "Tool `calendar` executed. Result: 🗓️ Calendar tool invoked – not yet implemented."
}

🚀 What You Just Built

• A FastAPI service listening on /chat.
• An AI agent that can either answer directly or invoke one of eight stub tools.
• A tool registry ready to be expanded with real implementations (calendar, email, CRM, web‑search, etc.).

You now have a clean, testable code base that any junior developer can run locally and extend.

❌ Common Mistakes

🛠️ Troubleshooting

📌 Key Takeaways

• Scaffold first, polish later. A well‑organized project layout saves countless hours when you start wiring real tools.
• Separate concerns: assistant.py handles LLM logic, tools/ holds side‑effects, and main.py is the HTTP façade.
• Stub everything until you’re ready to implement. This lets you test the integration pipeline early.

🧪 Try It Yourself

1. Add a new stub – create tools/notes.py with a function that returns a static note. Register it in tools/__init__.py under the key "notes".
2. Update the system prompt in assistant.py to mention the new "notes" tool.
3. Restart the server and send a message like “Create a note about my latest project”.
4. Observe the reply: it should say the notes tool was executed.

Once you’re comfortable, the next chapter will replace those stubs with real integrations (Google Calendar API, SendGrid, a tiny SQLite CRM, and a live web‑search wrapper). Happy coding!

Why This Matters

Modern AI agents are no longer just “play‑around” scripts. Companies expect them to talk to real services, store data securely, and run 24/7 in the cloud. By the end of this chapter you will have a production‑ready skeleton that:

• Connects a large language model (LLM) to external tools (LinkedIn, email, calendar, web search, CRM).
• Routes user intents to the correct tool automatically.
• Exposes a FastAPI endpoint so anyone can call the agent over HTTP.

You’ll see how enterprises structure such systems, which will make the next chapters (adding advanced skills, scaling, monitoring) much easier.

What You’ll Build

A modular Python package called ai_assistant with the following components:

The whole stack can be run locally with a single command and later deployed to any cloud provider.

Content

1️⃣ Set Up the Development Environment

# Save as: setup.sh
python -m venv.venv
source.venv/bin/activate
pip install --upgrade pip
pip install fastapi uvicorn openai python-dotenv requests google-auth google-auth-oauthlib google-api-python-client sqlalchemy

✅ Verify: After running source.venv/bin/activate && python -c "import fastapi" you should see no import errors.

2️⃣ Central Configuration (config.py)

# Save as: config.py
import os
from pathlib import Path
from dotenv import load_dotenv

BASE_DIR = Path(__file__).resolve().parent
load_dotenv(BASE_DIR / ".env")

class Settings:
 # LLM
 OPENAI_API_KEY: str = os.getenv("OPENAI_API_KEY")

 # Email
 SMTP_SERVER: str = os.getenv("SMTP_SERVER", "smtp.gmail.com")
 SMTP_PORT: int = int(os.getenv("SMTP_PORT", "587"))
 EMAIL_USER: str = os.getenv("EMAIL_USER")
 EMAIL_PASS: str = os.getenv("EMAIL_PASS")

 # Google Calendar (service account JSON path)
 GOOGLE_SERVICE_ACCOUNT_FILE: str = os.getenv("GOOGLE_SERVICE_ACCOUNT_FILE")

 # SerpAPI (web search)
 SERPAPI_KEY: str = os.getenv("SERPAPI_KEY")

 # Mock LinkedIn token (demo only)
> **What is a token?** A token is how AI models count text. Think of it as a "word piece" — roughly 3-4 characters. "Hello" = 1 token. "Hello world" = 2 tokens. Models have a limit on how many tokens they can process at once (called the "context window").


 LINKEDIN_TOKEN: str = os.getenv("LINKEDIN_TOKEN", "mock-token")

settings = Settings()

Create a .env file next to config.py (never commit real secrets!):

# Save as:.env
OPENAI_API_KEY=sk-.
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
EMAIL_USER=you@example.com
EMAIL_PASS=your_app_password
GOOGLE_SERVICE_ACCOUNT_FILE=service_account.json
SERPAPI_KEY=your_serpapi_key
LINKEDIN_TOKEN=mock-token

✅ Verify: Run python -c "from config import settings; print(settings.OPENAI_API_KEY[:5])" – it should print the first five characters of your key.

3️⃣ Tool Abstractions

All tools inherit from a simple BaseTool interface.

# Save as: tools/base.py
from abc import ABC, abstractmethod
from typing import Any, Dict

class BaseTool(ABC):
 """All tool classes must implement `run`."""

 @abstractmethod
 def run(self, **kwargs) -> Dict[str, Any]:
 """Execute the tool and return a JSON‑serialisable dict."""
 pass

✅ Verify: Import the class without errors: python -c "from tools.base import BaseTool".

4️⃣ LinkedIn Mock (tools/linkedin.py)

# Save as: tools/linkedin.py
from.base import BaseTool
from config import settings

class LinkedInTool(BaseTool):
 """Fetch a public LinkedIn profile (mocked for demo)."""

 def run(self, profile_url: str) -> dict:
 # In a real implementation you would call LinkedIn's API.
 # Here we just simulate a response.
 if not profile_url.startswith("https://www.linkedin.com/in/"):
 return {"error": "Invalid LinkedIn URL"}
 username = profile_url.rstrip("/").split("/")[-1]
 return {
 "name": f"{username.title()} (Mock)",
 "headline": "Software Engineer at Example Corp",
 "location": "San Francisco, CA",
 "url": profile_url,
 }

✅ Verify:

# Verify snippet
from tools.linkedin import LinkedInTool
print(LinkedInTool().run(profile_url="https://www.linkedin.com/in/jdoe/"))

Expected output

{
 "name": "Jdoe (Mock)",
 "headline": "Software Engineer at Example Corp",
 "location": "San Francisco, CA",
 "url": "https://www.linkedin.com/in/jdoe/"
}

5️⃣ Email Notification (tools/emailer.py)

# Save as: tools/emailer.py
import smtplib
from email.mime.text import MIMEText
from.base import BaseTool
from config import settings

class EmailTool(BaseTool):
 """Send an email via SMTP."""

 def run(self, to: str, subject: str, body: str) -> dict:
 msg = MIMEText(body, "plain")
 msg["Subject"] = subject
 msg["From"] = settings.EMAIL_USER
 msg["To"] = to

 try:
 with smtplib.SMTP(settings.SMTP_SERVER, settings.SMTP_PORT) as server:
 server.starttls()
 server.login(settings.EMAIL_USER, settings.EMAIL_PASS)
 server.send_message(msg)
 return {"status": "sent", "to": to}
 except Exception as e:
 return {"status": "failed", "error": str(e)}

✅ Verify:

# Verify snippet (replace with your own email)
# from tools.emailer import EmailTool
# print(EmailTool().run(to="you@example.com", subject="Test", body="Hello from AI Assistant!"))

You should see {"status": "sent", "to": "you@example.com"} if credentials are correct.

6️⃣ Calendar Integration (tools/calendar.py)

# Save as: tools/calendar.py
import datetime
from google.oauth2 import service_account
from googleapiclient.discovery import build
from.base import BaseTool
from config import settings

SCOPES = ["https://www.googleapis.com/auth/calendar.events"]

class CalendarTool(BaseTool):
 """Create a Google Calendar event."""

 def __init__(self):
 credentials = service_account.Credentials.from_service_account_file(
 settings.GOOGLE_SERVICE_ACCOUNT_FILE, scopes=SCOPES
 )
 self.service = build("calendar", "v3", credentials=credentials)

 def run(self, summary: str, start: str, end: str, timezone: str = "UTC") -> dict:
 """
 `start` and `end` must be ISO‑8601 strings, e.g. "2024-10-01T10:00:00".
 """
 event = {
 "summary": summary,
 "start": {"dateTime": start, "timeZone": timezone},
 "end": {"dateTime": end, "timeZone": timezone},
 }
 try:
 created = self.service.events().insert(calendarId="primary", body=event).execute()
 return {"status": "created", "eventId": created.get("id")}
 except Exception as e:
 return {"status": "failed", "error": str(e)}

✅ Verify:

# Verify snippet (requires a valid service account JSON)
# from tools.calendar import CalendarTool
# now = datetime.datetime.utcnow()
# start = (now + datetime.timedelta(minutes=5)).isoformat()
# end = (now + datetime.timedelta(minutes=35)).isoformat()
# print(CalendarTool().run(summary="Demo Meeting", start=start, end=end))

You should receive a JSON response with "status": "created" and an eventId.

7️⃣ Live Web Search (tools/websearch.py)

# Save as: tools/websearch.py
import requests
from.base import BaseTool
from config import settings

class WebSearchTool(BaseTool):
 """Search the web using SerpAPI (Google results)."""

 ENDPOINT = "https://serpapi.com/search"

 def run(self, query: str, num_results: int = 3) -> dict:
 params = {
 "engine": "google",
 "q": query,
 "api_key": settings.SERPAPI_KEY,
 "num": num_results,
 }
 try:
 resp = requests.get(self.ENDPOINT, params=params, timeout=10)
 resp.raise_for_status()
 data = resp.json()
 results = [
 {"title": r.get("title"), "link": r.get("link"), "snippet": r.get("snippet")}
 for r in data.get("organic_results", [])[:num_results]
 ]
 return {"query": query, "results": results}
 except Exception as e:
 return {"error": str(e)}

✅ Verify:

# Verify snippet
# from tools.websearch import WebSearchTool
# print(WebSearchTool().run(query="Python virtual environments"))

You should see a JSON object with up to three search results.

8️⃣ Personal CRM (SQLite) (tools/crm.py)

# Save as: tools/crm.py
import datetime
import sqlite3
from pathlib import Path
from.base import BaseTool

DB_PATH = Path(__file__).parent / "crm.db"

class CRMTool(BaseTool):
 """Store unknown questions for later review."""

 def __init__(self):
 self.conn = sqlite3.connect(DB_PATH)
 self._ensure_table()

 def _ensure_table(self):
 self.conn.execute(
 """
 CREATE TABLE IF NOT EXISTS unknown_questions (
 id INTEGER PRIMARY KEY AUTOINCREMENT,
 question TEXT NOT NULL,
 received_at TEXT NOT NULL
 )
 """
 )
 self.conn.commit()

 def run(self, question: str) -> dict:
 now = datetime.datetime.utcnow().isoformat()
 self.conn.execute(
 "INSERT INTO unknown_questions (question, received_at) VALUES (?, ?)",
 (question, now),
 )
 self.conn.commit()
 return {"status": "recorded", "question": question, "timestamp": now}

 def list_all(self) -> dict:
 cur = self.conn.execute("SELECT id, question, received_at FROM unknown_questions")
 rows = [{"id": r[0], "question": r[1], "received_at": r[2]} for r in cur.fetchall()]
 return {"questions": rows}

✅ Verify:

# Verify snippet
# from tools.crm import CRMTool
# crm = CRMTool()
# print(crm.run(question="What is the best wine for sushi?"))
# print(crm.list_all())

You should see a recorded response followed by a list containing that question.

9️⃣ Core Agent (core/agent.py)

# Save as: core/agent.py
import json
from typing import Any, Dict
import openai
from config import settings
from tools.linkedin import LinkedInTool
from tools.emailer import EmailTool
from tools.calendar import CalendarTool
from tools.websearch import WebSearchTool
from tools.crm import CRMTool

class AIAssistant:
 """Orchestrates LLM responses and routes to appropriate tools."""

 def __init__(self):
 openai.api_key = settings.OPENAI_API_KEY
 # Instantiate tools once (reuse connections)
 self.tools = {
 "linkedin": LinkedInTool(),
 "email": EmailTool(),
 "calendar": CalendarTool(),
 "websearch": WebSearchTool(),
 "crm": CRMTool(),
 }

 def _call_llm(self, user_msg: str) -> dict:
 """Ask the LLM to decide which tool (if any) to use."""
 system_prompt = (
 "You are an AI assistant that can call external tools. "
 "When you need to use a tool, respond with a JSON object: "
 '{"tool": "<tool_name>", "args": {.}}. "
 "If you cannot answer, say you don't know and record the question in the CRM. '
 "Only use the following tool names: linkedin, email, calendar, websearch, crm. "
 "If no tool is needed, respond with a plain text answer."
 )
 response = openai.ChatCompletion.create(
 model="gpt-4o-mini",
 messages=[
 {"role": "system", "content": system_prompt},
 {"role": "user", "content": user_msg},
 ],
 temperature=0,
 )
 reply = response.choices[0].message["content"].strip()
 return {"raw": reply}

 def _parse_tool_call(self, reply: str) -> Dict[str, Any]:
 """Detect JSON tool call; fallback to plain text."""
 try:
 payload = json.loads(reply)
 if isinstance(payload, dict) and "tool" in payload:
 return {"tool": payload["tool"], "args": payload.get("args", {})}
 except json.JSONDecodeError:
 pass
 return {"plain": reply}

 def handle_message(self, user_msg: str) -> dict:
 llm_output = self._call_llm(user_msg)
 parsed = self._parse_tool_call(llm_output["raw"])

 # 1️⃣ Plain answer – no tool needed
 if "plain" in parsed:
 return {"answer": parsed["plain"]}

 # 2️⃣ Tool invocation
 tool_name = parsed["tool"]
 args = parsed["args"]
 tool = self.tools.get(tool_name)

 if not tool:
 return {"error": f"Tool '{tool_name}' not recognized."}

 # Special case: unknown question → store in CRM
 if tool_name == "crm":
 result = tool.run(question=user_msg)
 return {"answer": "I don't know the answer yet. I've recorded your question for later.", "crm": result}

 # Normal tool execution
 result = tool.run(**args)
 return {"tool": tool_name, "result": result}

✅ Verify:

# Verify snippet
# from core.agent import AIAssistant
# assistant = AIAssistant()
# print(assistant.handle_message("Find the LinkedIn profile of Linus Torvalds"))
# print(assistant.handle_message("Schedule a meeting tomorrow at 3pm called 'Project Sync'"))
# print(assistant.handle_message("What is the best wine for sushi?"))

Expected sample output (exact IDs will differ):

{
 "tool": "linkedin",
 "result": {
 "name": "Linus Torvalds (Mock)",
 "headline": "Software Engineer at Example Corp",
 "location": "San Francisco, CA",
 "url": "https://www.linkedin.com/in/linus-torvalds/"
 }
}
{
 "tool": "calendar",
 "result": {
 "status": "created",
 "eventId": "abc123def456"
 }
}
{
 "answer": "I don't know the answer yet. I've recorded your question for later.",
 "crm": {
 "status": "recorded",
 "question": "What is the best wine for sushi?",
 "timestamp": "2024-09-15T12:34:56.789012"
 }
}

🔟 FastAPI Server (api/server.py)

# Save as: api/server.py
import uvicorn
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from core.agent import AIAssistant

app = FastAPI(title="AI Assistant API")
assistant = AIAssistant()

class ChatRequest(BaseModel):
 message: str

class ChatResponse(BaseModel):
 response: dict

@app.post("/chat", response_model=ChatResponse)
def chat(req: ChatRequest):
 try:
 result = assistant.handle_message(req.message)
 return ChatResponse(response=result)
 except Exception as e:
 raise HTTPException(status_code=500, detail=str(e))

if __name__ == "__main__":
 # Run with: python -m uvicorn api.server:app --reload
 uvicorn.run("api.server:app", host="0.0.0.0", port=8000, reload=True)

✅ Verify:

# In a terminal
python -m uvicorn api.server:app --reload

Then, in another terminal:

curl -X POST http://127.0.0.1:8000/chat \
 -H "Content-Type: application/json" \
 -d '{"message":"What is the capital of France?"}'

Expected output

{
 "response": {
 "answer": "Paris is the capital of France."
 }
}

📁 Project Files

ai_assistant/
│
├─.env # secret keys (never commit)
├─ config.py # central configuration
│
├─ tools/
│ ├─ __init__.py
│ ├─ base.py
│ ├─ linkedin.py
│ ├─ emailer.py
│ ├─ calendar.py
│ ├─ websearch.py
│ └─ crm.py
│
├─ core/
│ ├─ __init__.py
│ └─ agent.py
│
├─ api/
│ ├─ __init__.py
│ └─ server.py
│
└─ requirements.txt # optional – generated via `pip freeze > requirements.txt`

🚀 What You Just Built

You now have a complete, runnable codebase that can be deployed to any cloud platform (AWS, GCP, Azure, Railway, Render, etc.) with a single docker build later.

Common Mistakes

Troubleshooting

1. openai.error.AuthenticationError – double‑check OPENAI_API_KEY.
2. smtplib.SMTPAuthenticationError – verify email credentials and that “Allow less secure apps” is enabled (or use an app password).
3. googleapiclient.errors.HttpError 403 – ensure the service account has Calendar scope and the calendar is shared with the account.
4. requests.exceptions.ReadTimeout – increase the timeout in WebSearchTool or check your internet connection.
5. FastAPI returns 500 with “no such table: unknown_questions” – run python -c "from tools.crm import CRMTool; CRMTool()" once to create the DB, or delete crm.db and let the code recreate it.

Key Takeaways

• Modular design (one file per tool) makes adding or swapping services trivial.
• LLM‑driven routing lets you keep the business logic in the model while the code stays deterministic.
• Persisting unknowns (CRM) is essential for continuous improvement and ethical AI.
• FastAPI provides a lightweight, production‑grade HTTP layer with automatic docs (/docs).

You now possess the foundation for a real‑world AI assistant that can be expanded indefinitely.

🧪 Try It Yourself

1. Add a new tool – e.g., a weather API. Create tools/weather.py that inherits from BaseTool, register it in AIAssistant.__init__, and update the system prompt to include "weather" as a valid tool name.
2. Persist tool usage logs – extend CRMTool or create a new AuditTool that writes every request/response pair to a separate SQLite table.
3. Dockerize – write a Dockerfile that copies the project, installs dependencies, and runs uvicorn api.server:app --host 0.0.0.0. Build and run the container to see the whole stack isolated.

Happy coding! 🎉

Why This Matters

Scheduling an introductory call is a core workflow for any professional AI assistant. When a candidate or recruiter says “S2 works” and provides an email address, the assistant must:

1. Parse the slot identifier (S2) into a concrete date‑time.
2. Create a Google Calendar event (including an .ics attachment).
3. Send a nicely formatted HTML email to both parties with the meeting details and a “Add to Calendar” link.

Getting this right dramatically reduces friction in the hiring pipeline and showcases the power of a fully‑automated, end‑to‑end assistant.

What You’ll Build

In this chapter you will extend the previous chatbot skeleton to:

By the end of this chapter you will have a single command‑line script that can:

> python schedule_meeting.py
Enter slot (e.g., S2): S2
Enter your email: ishanth8@gmail.com
Enter recruiter email: recruiter@example.com
✅ Verify: Meeting scheduled, emails sent!

Content

1️⃣ Parse the Slot Identifier

We’ll keep a static mapping of slot IDs to datetime objects for simplicity. In a production system you would pull the user’s free‑busy data via the Calendar API.

# Save as: slot_parser.py
import datetime
from typing import Dict

# Example static slot map – replace with dynamic free‑busy lookup later
SLOT_MAP: Dict[str, datetime.datetime] = {
 "S1": datetime.datetime(2024, 8, 8, 15, 0), # Thursday 3 PM UTC
 "S2": datetime.datetime(2024, 8, 8, 18, 0), # Thursday 6 PM UTC
 "S3": datetime.datetime(2024, 8, 9, 10, 0), # Friday 10 AM UTC
 "S4": datetime.datetime(2024, 8, 12, 14, 0), # Monday 2 PM UTC
}

def parse_slot(slot_id: str) -> datetime.datetime:
 """
 Convert a slot identifier (e.g.,'S2') into a timezone‑aware datetime.
 Raises ValueError if the slot does not exist.
 """
 if slot_id not in SLOT_MAP:
 raise ValueError(f"Slot {slot_id} is not defined.")
 # Assume UTC for this demo; replace with pytz/local timezone as needed
 return SLOT_MAP[slot_id]

Expected output (when imported and called):

>>> from slot_parser import parse_slot
>>> parse_slot("S2")
datetime.datetime(2024, 8, 8, 18, 0)

✅ Verify: parse_slot returns a datetime object for a valid slot and raises a clear error for an unknown slot.

2️⃣ Google Calendar Helper

We’ll use the Google Calendar API (google-api-python-client) to create the event.

⚠️ Prerequisite: Follow the “Enable APIs & obtain credentials” steps in the previous chapter. Save the OAuth client JSON as credentials.json.

# Save as: calendar_helper.py
import datetime
import os.path
import base64
from email.mime.text import MIMEText
from typing import Tuple

from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

# If modifying these scopes, delete token.json.
SCOPES = ["https://www.googleapis.com/auth/calendar.events",
 "https://www.googleapis.com/auth/gmail.send"]

def get_service(scopes: list, token_file: str = "token.json") -> Tuple[object, Credentials]:
 """Authenticate and return a Google API service object."""
 creds = None
 if os.path.exists(token_file):
 creds = Credentials.from_authorized_user_file(token_file, scopes)
 # If there are no (valid) credentials, let the user log in.
 if not creds or not creds.valid:
 if creds and creds.expired and creds.refresh_token:
 creds.refresh(Request())
 else:
 flow = InstalledAppFlow.from_client_secrets_file(
 "credentials.json", scopes)
 creds = flow.run_local_server(port=0)
 # Save the credentials for the next run
 with open(token_file, "w") as token:
 token.write(creds.to_json())
 service = build("calendar", "v3", credentials=creds)
 return service, creds

def create_event(service,
 start_dt: datetime.datetime,
 end_dt: datetime.datetime,
 summary: str,
 description: str,
 attendees: list) -> dict:
 """
 Insert an event into the primary calendar.
 Returns the created event resource.
 """
 event_body = {
 "summary": summary,
 "description": description,
 "start": {"dateTime": start_dt.isoformat(), "timeZone": "UTC"},
 "end": {"dateTime": end_dt.isoformat(), "timeZone": "UTC"},
 "attendees": [{"email": email} for email in attendees],
 "reminders": {"useDefault": True},
 }
 event = service.events().insert(calendarId="primary", body=event_body,
 sendUpdates="all").execute()
 print(f"✅ Verify: Event created – {event.get('htmlLink')}")
 return event

def generate_ics(event: dict) -> bytes:
 """
 Very small helper that builds an.ics file from the event dict.
 For a full‑featured solution use icalendar package.
 """
 from icalendar import Calendar, Event as IcsEvent

 cal = Calendar()
 cal.add("prodid", "-//AI Scheduler//example.com//")
 cal.add("version", "2.0")

 ics_event = IcsEvent()
 ics_event.add("summary", event["summary"])
 ics_event.add("dtstart", datetime.datetime.fromisoformat(event["start"]["dateTime"]))
 ics_event.add("dtend", datetime.datetime.fromisoformat(event["end"]["dateTime"]))
 ics_event.add("description", event["description"])
 ics_event.add("uid", event["id"])
 ics_event.add("dtstamp", datetime.datetime.utcnow())
 cal.add_component(ics_event)

 return cal.to_ical()

Sample run (assuming valid credentials):

✅ Verify: Event created – https://www.google.com/calendar/event?eid=.

✅ Verify: The function prints the event link and returns the full event JSON.

3️⃣ Email Helper (HTML +.ics attachment)

We’ll send the email via Gmail API (same credentials as Calendar). The email contains:

• A friendly greeting.
• Meeting details (date, time, Google Meet link if generated).
• A “Add to Google Calendar” button that points to the event URL.
• An attached .ics file for Outlook/Apple Calendar users.

# Save as: email_helper.py
import base64
from email.mime.multipart import MIMEMultipart
from email.mime.text import MIMEText
from email.mime.application import MIMEApplication
from typing import List

def build_email(sender: str,
 to: List[str],
 subject: str,
 html_body: str,
 ics_bytes: bytes,
 ics_filename: str = "invite.ics") -> dict:
 """
 Construct a Gmail API message dict with HTML body and.ics attachment.
 """
 message = MIMEMultipart()
 message["to"] = ", ".join(to)
 message["from"] = sender
 message["subject"] = subject

 # HTML part
 message.attach(MIMEText(html_body, "html"))

 #.ics attachment
 ics_part = MIMEApplication(ics_bytes, _subtype="ics")
 ics_part.add_header("Content-Disposition", "attachment", filename=ics_filename)
 message.attach(ics_part)

 raw_message = base64.urlsafe_b64encode(message.as_bytes()).decode()
 return {"raw": raw_message}

def send_message(gmail_service, user_id: str, message_body: dict):
 """
 Send an email via Gmail API.
 """
 sent_message = gmail_service.users().messages().send(userId=user_id, body=message_body).execute()
 print(f"✅ Verify: Email sent – Message ID {sent_message['id']}")
 return sent_message

def render_html(meeting_link: str, start_dt: datetime.datetime, end_dt: datetime.datetime) -> str:
 """
 Very simple HTML template for the meeting invitation.
 """
 start_str = start_dt.strftime("%A, %B %d, %Y %I:%M %p UTC")
 end_str = end_dt.strftime("%I:%M %p UTC")
 html = f"""
 <html>
 <body>
 <p>Hello,</p>
 <p>Your introductory call has been scheduled:</p>
 <ul>
 <li><strong>When:</strong> {start_str} – {end_str}</li>
 <li><strong>Where:</strong> <a href="{meeting_link}">Google Meet link</a></li>
 </ul>
 <p>
 <a href="{meeting_link}"
 style="display:inline-block;padding:10px 20px;background:#4285F4;color:#fff;
 text-decoration:none;border-radius:4px;">
 Join Meeting
 </a>
 </p>
 <p>
 <a href="{meeting_link}"
 style="display:inline-block;padding:10px 20px;background:#34A853;color:#fff;
 text-decoration:none;border-radius:4px;">
 Add to Google Calendar
 </a>
 </p>
 <p>Looking forward to speaking with you!</p>
 <p>Best regards,<br/>AI Scheduler Bot</p>
 </body>
 </html>
 """
 return html

Sample output after sending:

✅ Verify: Email sent – Message ID 17c8b3f9c5e.

✅ Verify: Both the HTML body and the .ics attachment are present when you view the email in Gmail.

4️⃣ Orchestrator – schedule_meeting.py

Now we tie everything together:

# Save as: schedule_meeting.py
import datetime
import sys

from slot_parser import parse_slot
from calendar_helper import get_service, create_event, generate_ics
from email_helper import build_email, send_message, render_html

def main():
 # 1️⃣ Gather user input
 slot_id = input("Enter slot (e.g., S2): ").strip().upper()
 user_email = input("Enter your email: ").strip()
 recruiter_email = input("Enter recruiter email: ").strip()

 try:
 start_dt = parse_slot(slot_id)
 except ValueError as e:
 print(f"❌ Error: {e}")
 sys.exit(1)

 # For demo we assume a 1‑hour meeting
 end_dt = start_dt + datetime.timedelta(hours=1)

 # 2️⃣ Authenticate Google services (Calendar + Gmail)
 service, creds = get_service(scopes=[
 "https://www.googleapis.com/auth/calendar.events",
 "https://www.googleapis.com/auth/gmail.send"
 ])

 # 3️⃣ Create Calendar event
 event = create_event(
 service=service,
 start_dt=start_dt,
 end_dt=end_dt,
 summary="Introductory Call with Ishant",
 description="Automated meeting scheduled via AI assistant.",
 attendees=[user_email, recruiter_email]
 )

 # 4️⃣ Generate.ics file
 ics_bytes = generate_ics(event)

 # 5️⃣ Build HTML body
 meeting_link = event.get("hangoutLink", "https://meet.google.com/placeholder")
 html_body = render_html(meeting_link, start_dt, end_dt)

 # 6️⃣ Build and send email to both parties
 email_msg = build_email(
 sender=user_email,
 to=[user_email, recruiter_email],
 subject="📅 Introductory Call Confirmation",
 html_body=html_body,
 ics_bytes=ics_bytes
 )
 send_message(gmail_service=service, user_id="me", message_body=email_msg)

 print("\n✅ Verify: All steps completed – meeting scheduled and emails dispatched!")

if __name__ == "__main__":
 main()

Running the script

$ python schedule_meeting.py
Enter slot (e.g., S2): S2
Enter your email: ishanth8@gmail.com
Enter recruiter email: recruiter@example.com
✅ Verify: Event created – https://www.google.com/calendar/event?eid=.
✅ Verify: Email sent – Message ID 17c8b3f9c5e.
All steps completed – meeting scheduled and emails dispatched!

✅ Verify: The console shows both verification messages, and you should see the meeting on your Google Calendar as well as an email in both inboxes.

📁 Project Files

ai_scheduler/
│
├─ credentials.json # OAuth client secret (downloaded from Google Cloud)
├─ token.json # Generated after first auth (auto‑created)
│
├─ slot_parser.py
├─ calendar_helper.py
├─ email_helper.py
└─ schedule_meeting.py

💡 Tip: Keep credentials.json out of version control (.gitignore) to protect your client secret.

🚀 What You Just Built

• Dynamic slot parsing – turn a simple “S2” into a concrete UTC datetime.
• Google Calendar integration – create an event, invite both participants, and retrieve a shareable link.
• ICS generation – produce a universal calendar file for Outlook/Apple users.
• HTML email with actionable buttons – a polished invitation that works on any device.
• Dual‑recipient delivery – both the candidate and recruiter receive identical, professional invites.

All of this runs from a single Python script with no manual copy‑pasting.

Common Mistakes

Troubleshooting

1. HttpError 403: Insufficient Permission Solution: Re‑run the script after deleting token.json. The OAuth consent screen will ask for the new scopes.

2. AttributeError: module 'datetime' has no attribute 'fromisoformat' (Python < 3.7) Solution: Upgrade to Python 3.7+ or use dateutil.parser.isoparse.

3. No email received Solution: Verify the to list contains valid addresses, and check Gmail’s “Sent” folder for the message ID printed by send_message.

4. Calendar event appears at the wrong time Solution: Confirm the timeZone field in create_event matches the timezone of start_dt. For local time, use pytz.timezone("America/Los_Angeles") and pass tzinfo to the datetime.

Key Takeaways

• Parse user-friendly identifiers into machine‑readable timestamps before any API call.
• Reuse a single OAuth credential for both Calendar and Gmail to keep the flow seamless.
• Always attach an .ics file – it guarantees cross‑platform calendar compatibility.
• HTML emails with clear CTA buttons dramatically improve the user experience.
• Verification prints (✅ Verify:) are invaluable during development and debugging.

🧪 Try It Yourself

1. Add a new slot (e.g., S5) for a Tuesday 2 PM meeting in slot_parser.py.
2. Run the script and schedule using the new slot. Verify that the event appears on the correct day.
3. Modify the email template to include your company logo (use an <img> tag with a hosted image URL).
4. Experiment with time zones: change timeZone to "America/New_York" and observe the shift in the calendar UI.

Happy coding! 🎉

Chapter 2

Getting Your Python Environment Sorted

Why This Matters

Before You Start This Chapter

• Your venv is active (you see (.venv) in your prompt)
• Previous chapter's project is working

• Your .env file has your API key

  What is an API? An API (Application Programming Interface) is how one program talks to another. Think of it like a waiter in a restaurant — you (your code) tell the waiter (API) what you want, the waiter goes to the kitchen (the server), and brings back your food (the response). You never talk to the kitchen directly.

• You are in the correct folder (run pwd to check)

Get Your OpenAI API Key

1. Go to https://platform.openai.com/api-keys
2. Log in (free account)
3. Click "Create new secret key"
4. Name it (e.g., "adhikk")
5. Click "Create"
6. Copy the key (starts with sk-) — you will not see it again
7. Paste into your .env file

New accounts get $5 free credit — enough for this entire book.

Every data‑science or Python project eventually runs into dependency conflicts. - Project A may need pandas==1.2.0 while Project B requires pandas==2.0.0. - Installing both versions globally makes one of the projects break.

A virtual environment isolates each project’s interpreter and libraries, guaranteeing that code that works today will work tomorrow on any machine. Mastering this concept is the foundation of reproducible, professional Python development.

What You'll Build

In this chapter you will:

1. Run Python instantly with Google Colab (no local installation needed).
2. Create a local virtual environment using the built‑in venv module.
3. Set up the modern uv package manager to create and manage environments in a single command.

By the end, you’ll have three runnable examples that you can copy‑paste and execute without any extra research.

Content

Each step includes code, expected output, and a ✅ Verify checkpoint.

📁 Project Files

Below are the two Python scripts you will run locally.

env_a_demo.py

# Save as: env_a_demo.py
import sys
import numpy as np

def main() -> None:
 print(f"Python executable: {sys.executable}")
 print(f"Numpy version : {np.__version__}")

if __name__ == "__main__":
 main()

Expected output (when run inside env_a):

Python executable: /full/path/to/env_a/bin/python
Numpy version : 1.21.6

uv_demo.py

# Save as: uv_demo.py
import sys
import pandas as pd

def main() -> None:
 print(f"Python executable: {sys.executable}")
 print(f"Pandas version : {pd.__version__}")

if __name__ == "__main__":
 main()

Expected output (when run inside env_uv):

Python executable: /full/path/to/uv_env/bin/python
Pandas version : 2.2.2

🚀 What You Just Built

1. Google Colab notebook – a cloud‑based, zero‑setup Python REPL.
2. env_a virtual environment – isolated Python 3.11 with numpy==1.21.6.
3. env_uv virtual environment – isolated Python 3.12 with pandas==2.2.2 created via uv.

All three run the same code pattern: print the interpreter path and a library version, proving that each environment is truly independent.

Common Mistakes

Troubleshooting

1️⃣ Google Colab won’t import a library

• Symptom: ImportError: No module named'some_pkg'.
• Solution: Install the missing package in the notebook cell:

!pip install some_pkg==1.2.3

2️⃣ venv activation script not found

• Symptom: source: No such file or directory.
• Solution: Verify you are in the directory containing env_a. List files with ls env_a. If the folder is missing, recreate it (python -m venv env_a).

3️⃣ uv command not recognized

• Symptom: uv: command not found.
• Solution: Install uv (see below) and ensure ~/.local/bin (or the appropriate location) is on your PATH.

Key Takeaways

• Isolation is the antidote to dependency hell.
• Google Colab is perfect for quick experiments; it runs a fresh VM each session.
• venv is built‑in, reliable, and works everywhere Python runs.
• uv is a modern, ultra‑fast alternative that combines environment creation and package management in one step.

Master these tools now, and you’ll never be blocked by conflicting libraries again.

🧪 Try It Yourself

1. Colab Challenge – Open a new notebook, run:

python import sys, platform print("Python:", sys.version) print("OS :", platform.system())

Verify the output matches the runtime shown in the UI.

1. Venv Challenge – Create a second environment env_b, install numpy==1.24.0, and run env_a_demo.py inside it. Confirm the printed version changes.

2. UV Challenge – Use uv to create an environment with Python 3.11 and install scikit-learn==1.3.0. Write a tiny script that prints sklearn.__version__ and run it.

💡 Tip: Keep a requirements.txt (or uv.lock) in each project folder. It makes reproducing the exact environment a one‑liner: pip install -r requirements.txt or uv sync.

⚠️ Warning: Never commit your virtual‑environment directories (env_*, uv_env) to version control. Add them to .gitignore to keep the repository clean.

✅ Verify: After each challenge, the printed versions should match the versions you explicitly installed. If they don’t, re‑activate the environment and re‑run the script.

Why This Matters

When you move from quick‑and‑dirty prototyping to real‑world projects, you need a reproducible, isolated environment. - Isolation guarantees that one project's libraries never clash with another's. - Reproducibility lets anyone (including future you) spin up the exact same stack with a single command. - Version control of dependencies prevents the dreaded “It works on my machine” bugs that waste hours of debugging.

⚠️ Skipping a proper environment setup is the fastest way to end up with a broken pipeline when you later add new features or share the code with teammates.

What You’ll Build

By the end of this chapter you will have a complete, version‑controlled Python project that:

1. Uses a virtual environment (venv).
2. Declares its dependencies in a requirements.txt file.
3. Installs those dependencies reproducibly.
4. Runs a small demo script that prints the installed package versions.
5. Is ready to be pushed to a Git repository.

✅ Verify: After completing the steps you should be able to delete the venv folder, recreate it, run pip install -r requirements.txt, and see the same output as before.

Content

1️⃣ Create the Project Skeleton

# From your terminal (any OS)
mkdir my_data_project
cd my_data_project

2️⃣ Initialise a Git Repository

git init

💡 Initialising early gives you a clean history from day one.

3️⃣ Set Up a Virtual Environment

# macOS / Linux
python3 -m venv.venv

# Windows (PowerShell)
python -m venv.venv

4️⃣ Activate the Environment

# macOS / Linux
source.venv/bin/activate

# Windows (PowerShell).\.venv\Scripts\Activate.ps1

You should now see (.venv) prefixed to your prompt.

5️⃣ Install Core Packages

pip install pandas==2.2.1 rich==13.7.0

6️⃣ Freeze the Exact Versions

pip freeze > requirements.txt

requirements.txt now contains a pinned list of all packages required to run the project.

7️⃣ Add a Simple Demo Script

Create a file called demo.py with the following content:

# Save as: demo.py
import pandas as pd
from rich import print as rprint

def main() -> None:
 rprint("[bold green]✅ Environment is ready![/bold green]")
 rprint(f"Pandas version: [cyan]{pd.__version__}[/cyan]")
 rprint(f"Rich version: [cyan]{rprint.__module__}[/cyan]")

if __name__ == "__main__":
 main()

Expected output when you run the script:

✅ Environment is ready!
Pandas version: 2.2.1
Rich version: rich

✅ Verify: Run python demo.py inside the activated environment and confirm the output matches exactly.

8️⃣ Commit Your Work

git add.
git commit -m "Initial project skeleton with venv and demo script"

9️⃣ (Optional) Export a Jupyter Notebook

If you prefer notebooks, you can generate one from the script:

pip install jupytext
jupytext --to ipynb demo.py

This creates demo.ipynb that you can open in Jupyter or Google Colab, preserving the same environment.

📁 Project Files

.gitignore (copy‑paste)

# Save as:.gitignore
# Exclude virtual environment.venv/
__pycache__/
*.pyc

✅ Verify: cat.gitignore should display the content above.

🚀 What You Just Built

• A self‑contained Python project that can be cloned on any machine, recreated with python -m venv.venv && source.venv/bin/activate && pip install -r requirements.txt, and run with python demo.py.
• A single source of truth for dependencies (requirements.txt).
• A Git history that tracks every change from day one.

Common Mistakes

Troubleshooting

Key Takeaways

• Virtual environments isolate dependencies per project.
• Pinning versions in requirements.txt guarantees reproducibility.
• Git should track source code only, not generated artefacts like the venv.
• A tiny demo script (demo.py) is a reliable sanity check that the environment works.

🧪 Try It Yourself

1. Create a new project called weather_analysis.
2. Set up a venv, install requests==2.31.0 and matplotlib==3.8.2.
3. Freeze the dependencies.
4. Write a script fetch_plot.py that:
5. Fetches current weather data from a free API (e.g., Open‑Meteo).
6. Plots temperature over the next 7 days using matplotlib.
7. Commit everything to a new Git repo.

When you’re done, clone the repo on a different machine (or a fresh Docker container), recreate the venv, install from requirements.txt, and verify the plot renders without errors.

Happy coding! 🚀

Why This Matters

Reproducibility is the cornerstone of professional software development. When you share code with a teammate—or when you come back to a project months later—the exact same Python interpreter and library versions must be available.

• Virtual environments isolate dependencies per project.
• requirements.txt gives a human‑readable list of packages.
• uv (the ultra‑fast, all‑in‑one package manager) creates lock files that guarantee identical builds across machines, and it does it in a fraction of the time pip needs.

By mastering these tools you’ll avoid “works on my machine” bugs forever.

What You’ll Build

A tiny data‑analysis project that:

1. Uses a uv‑managed virtual environment.
2. Installs pandas and jupyter inside that environment.
3. Provides a requirements.txt and a uv.lock file for reproducibility.
4. Contains a Python script (analysis.py) that loads a CSV, prints the first rows, and saves a summary.
5. Includes a Jupyter notebook (explore.ipynb) that visualises the data.

All of this will run without any additional research.

✅ Verify: By the end of this chapter you will be able to clone the folder on a fresh machine, run uv sync, and have a working environment instantly.

Content

1️⃣ Install uv (if you haven’t already)

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
iwr https://astral.sh/uv/install.ps1 -UseBasicParsing | iex

💡 uv is a single binary, no Python wheels needed. It works on macOS, Linux, and Windows.

✅ Verify:

uv --version
# Expected output, e.g.:
# uv 0.4.0

2️⃣ Initialise the Project with uv

# Create a fresh folder for the project
mkdir python_one && cd python_one

# Initialise a new uv project (creates pyproject.toml)
uv init

The generated pyproject.toml looks like this (you’ll see it later in 📁 Project Files).

✅ Verify:

cat pyproject.toml
# Should display a minimal TOML with [project] section.

3️⃣ Add Dependencies

# Add pandas and jupyter as runtime dependencies
uv add pandas jupyter

uv will:

• Resolve the latest compatible versions.
• Create a uv.lock file that pins exact versions and hashes.

⚠️ Do not edit uv.lock manually; it is auto‑generated.

✅ Verify:

cat uv.lock | head -n 5
# You’ll see a TOML snippet with locked versions.

4️⃣ Create the Virtual Environment

# By default uv creates a.venv folder in the project root
uv venv

Activate it (Linux/macOS):

source.venv/bin/activate

Activate it (Windows PowerShell):

```powershell.venv\Scripts\Activate.ps1

Now `which python` (or `Get-Command python` on Windows) points to the project‑local interpreter.

✅ Verify:

```bash
which python # Linux/macOS
# or
Get-Command python # Windows PowerShell
# Output should end with "./python_one/.venv/bin/python"

5️⃣ Write the Core Script (analysis.py)

# Save as: analysis.py
import pandas as pd
from pathlib import Path

def main() -> None:
 # Create a tiny CSV on‑the‑fly for demo purposes
 csv_path = Path("data.csv")
 if not csv_path.exists():
 df_demo = pd.DataFrame({
 "name": ["Alice", "Bob", "Charlie", "Diana"],
 "age": [28, 34, 23, 45],
 "score": [85.5, 92.0, 78.5, 88.0]
 })
 df_demo.to_csv(csv_path, index=False)

 # Load the CSV
 df = pd.read_csv(csv_path)

 # Print first rows
 print("First 3 rows:")
 print(df.head(3))

 # Save a simple summary
 summary = df.describe()
 summary_path = Path("summary.txt")
 summary.to_csv(summary_path, sep="\t")
 print(f"\nSummary written to {summary_path}")

if __name__ == "__main__":
 main()

Expected output when you run it:

First 3 rows:
 name age score
0 Alice 28 85.5
1 Bob 34 92.0
2 Charlie 23 78.5

Summary written to summary.txt

✅ Verify:

python analysis.py

6️⃣ Export a Classic requirements.txt

Even though uv is preferred, many CI pipelines still expect a requirements.txt. Generate it from the lock file:

uv export -f requirements.txt -o requirements.txt

✅ Verify:

cat requirements.txt | head -n 5
# Should list pandas, jupyter, and their exact versions.

7️⃣ Create a Jupyter Notebook (explore.ipynb)

Tip: VS Code will automatically detect the .ipynb file and use the active virtual environment.

{
 "cells": [
 {
 "cell_type": "markdown",
 "metadata": {},
 "source": [
 "# Exploring the Demo Data\n",
 "We will load the CSV created by `analysis.py` and plot the scores."
 ]
 },
 {
 "cell_type": "code",
 "execution_count": null,
 "metadata": {},
 "outputs": [],
 "source": [
 "import pandas as pd\n",
 "import matplotlib.pyplot as plt\n",
 "\n",
 "df = pd.read_csv('data.csv')\n",
 "df.head()"
 ]
 },
 {
 "cell_type": "code",
 "execution_count": null,
 "metadata": {},
 "outputs": [],
 "source": [
 "plt.bar(df['name'], df['score'], color='skyblue')\n",
 "plt.title('Score by Person')\n",
 "plt.ylabel('Score')\n",
 "plt.show()"
 ]
 }
 ],
 "metadata": {
 "kernelspec": {
 "display_name": "Python (python_one)",
 "language": "python",
 "name": "python"
 },
 "language_info": {
 "name": "python",
 "version": "3.12"
 }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}

Save this JSON as explore.ipynb. Open it in VS Code, press Shift + Enter on each cell, and you’ll see a bar chart.

✅ Verify:

Open the notebook → Run all cells → A bar chart appears.

8️⃣ Re‑creating the Environment on a New Machine

1. Clone the repository (or copy the folder).
2. Install uv (step 1).
3. Run:

uv sync

uv sync reads uv.lock and installs the exact same packages into a fresh .venv. No pip install needed.

✅ Verify:

source.venv/bin/activate # or.venv\Scripts\Activate.ps1 on Windows
python analysis.py # should produce the same output as before

📁 Project Files

python_one/
├─.venv/ # created by `uv venv` (not version‑controlled)
├─ analysis.py # main script (see code above)
├─ explore.ipynb # Jupyter notebook (JSON shown above)
├─ pyproject.toml # generated by `uv init`
├─ uv.lock # generated by `uv add`
├─ requirements.txt # exported via `uv export`
└─ data.csv # created on first run of analysis.py (auto‑generated)

pyproject.toml (auto‑generated, shown for completeness):

# Save as: pyproject.toml
[project]
name = "python_one"
version = "0.1.0"
description = "Demo project showing uv, venv, pandas, and Jupyter."
authors = [{name = "Your Name", email = "you@example.com"}]
requires-python = ">=3.9"

[tool.uv]
# No extra configuration needed for this demo

🚀 What You Just Built

• A self‑contained Python environment managed by uv.
• A deterministic lock file (uv.lock) guaranteeing identical builds.
• A script that reads, processes, and summarizes CSV data.
• A Jupyter notebook that visualises the same data.
• A requirements.txt for legacy tooling.

All of this can be transferred to any machine, and uv sync will recreate the exact same environment in seconds.

Common Mistakes

Troubleshooting

Key Takeaways

• Isolation + determinism = reliable, shareable code.
• uv replaces venv, pip, and pip‑freeze with a single, fast tool.
• Always activate the environment before running scripts or notebooks.
• Keep uv.lock under version control; generate requirements.txt only when needed for external tools.

🧪 Try It Yourself

1. Create a new branch called experiment.
2. Add a new dependency, e.g., uv add matplotlib.
3. Update analysis.py to plot a histogram of the score column and save it as score_hist.png.
4. Run uv sync on a different machine (or a Docker container) and verify the plot is generated correctly.

Bonus: Replace uv sync with uv pip install -r requirements.txt on that other machine and observe the slower installation time. Compare the logs to see uv’s speed advantage.

Happy coding! 🚀

Why This Matters

Modern Python projects rarely live in a single file. They depend on many third‑party libraries, each with its own version constraints. Managing those dependencies manually (copy‑pasting pip install … commands) quickly becomes error‑prone, especially when you need to share the exact same environment with teammates or CI pipelines.

The UV package manager solves this by:

• Creating an isolated virtual environment in seconds.
• Generating a lockfile (uv.lock) that pins every transitive dependency.
• Providing a single command (uv sync) to reproduce the environment anywhere.

By the end of this section you’ll have a professional‑grade project skeleton that can be cloned and run on any machine with a single command.

What You’ll Build

A small data‑science utility called sales_insight.py that:

1. Reads a CSV file with pandas.
2. Trains a scikit‑learn linear regression model.
3. Prints the model’s R² score.

All dependencies will be managed with UV, and the project will be ready for version control.

Content

1️⃣ Initialise a UV Project

Open a terminal inside your project folder (e.g., ~/projects/sales_insight) and run:

uv init

💡 Tip – uv init creates a minimal pyproject.toml, a uv.lock placeholder, and a hidden .venv directory (the virtual environment).

✅ Verify: You should see a new pyproject.toml file and a .venv/ folder.

2️⃣ Add Required Packages

uv add pandas scikit-learn

UV will:

• Resolve the latest compatible versions.
• Write them to uv.lock.
• Update pyproject.toml under [project] → dependencies.

✅ Verify: Open pyproject.toml; you’ll see something like:

[project]
dependencies = [
 "pandas",
 "scikit-learn",
]

3️⃣ Sync the Environment

uv sync

UV now creates the virtual environment (if not already present) and installs exactly the versions recorded in uv.lock.

✅ Verify: Run uv run python -c "import pandas, sklearn; print('✅ All good')" – you should see ✅ All good.

4️⃣ Write the Application Code

Create sales_insight.py (full file shown below). It will:

• Load sales.csv (you’ll create a tiny sample later).
• Fit a linear regression model predicting Revenue from Advertising.
• Print the R² score.

# Save as: sales_insight.py
import pandas as pd
from sklearn.linear_model import LinearRegression
from sklearn.metrics import r2_score

def main() -> None:
 # Load sample data
 df = pd.read_csv("sales.csv")
 X = df[["Advertising"]].values
 y = df["Revenue"].values

 # Train model
 model = LinearRegression()
 model.fit(X, y)

 # Predict and evaluate
 predictions = model.predict(X)
 score = r2_score(y, predictions)

 print(f"R² score: {score:.4f}")

if __name__ == "__main__":
 main()

Expected output (once we create the CSV):

R² score: 0.9876

✅ Verify: After creating sales.csv (see next step), run:

uv run python sales_insight.py

You should see the R² score printed.

5️⃣ Add a Sample CSV

Create sales.csv in the same directory:

Advertising,Revenue
23, 650
45, 1200
12, 300
34, 950

✅ Verify: Open the file to confirm the four rows are present.

6️⃣ Lock the Project for Distribution

The lockfile (uv.lock) already contains exact versions, but you can re‑generate it anytime:

uv lock

Commit both pyproject.toml and uv.lock to your Git repository. Anyone cloning the repo can reproduce the environment with a single command:

uv sync

📁 Project Files

sales_insight/
├─.venv/ # Created by UV (do NOT commit)
├─ pyproject.toml # UV project definition
├─ uv.lock # Exact pinned dependencies
├─ sales_insight.py # Application code
└─ sales.csv # Sample data

pyproject.toml (auto‑generated, shown for completeness)

# Save as: pyproject.toml
[project]
name = "sales_insight"
version = "0.1.0"
description = "A tiny demo of UV‑managed dependencies"
dependencies = [
 "pandas",
 "scikit-learn",
]

[build-system]
requires = ["uv"]
build-backend = "uv.build"

🚀 What You Just Built

• A reproducible Python environment managed by UV.
• A data‑science script that reads CSV data, trains a model, and reports performance.
• A ready‑to‑share project – clone, run uv sync, and you’re good to go.

Common Mistakes

Troubleshooting

Key Takeaways

• UV provides a fast, deterministic way to manage Python dependencies.
• The lockfile (uv.lock) is the single source of truth for reproducibility.
• Use uv add for new packages and uv sync to materialise the environment.
• Always run your scripts with uv run (or activate the .venv) to guarantee the correct interpreter and packages are used.

🧪 Try It Yourself

1. Add a new library – e.g., matplotlib – to visualise the data:

bash uv add matplotlib uv sync

1. Extend sales_insight.py to plot the regression line:

```python import matplotlib.pyplot as plt

# After model training. plt.scatter(X, y, color="blue", label="Data") plt.plot(X, predictions, color="red", label="Fit") plt.xlabel("Advertising") plt.ylabel("Revenue") plt.title("Advertising vs Revenue") plt.legend() plt.show() ```

1. Run the script with uv run python sales_insight.py.

You should see a window displaying the scatter plot with the fitted line.

Congratulations! You now have a fully reproducible, version‑controlled Python project powered by UV. In the next chapter we’ll explore testing and continuous integration for this setup. Happy coding!

Why This Matters

Locking dependencies and securely managing secrets are non‑negotiable in any production‑grade Python project. - Reproducibility: uv lock guarantees every teammate (and CI runner) installs exactly the same package versions. - Security: Storing API keys in a .env file keeps them out of source control, preventing accidental leaks. - Speed: With a lock file, uv sync resolves the dependency graph once and then installs in a flash—ideal for rapid iteration.

What You'll Build

A minimal, ready‑to‑run OpenAI client that:

1. Reads your API key from a .env file.
2. Uses the locked dependencies from uv.lock.
3. Sends a simple prompt to gpt‑3.5‑turbo and prints the response.

All files are self‑contained; you won’t need to search the internet for any missing piece.

Content

1️⃣ Set Up the Project Skeleton

mkdir openai_demo && cd openai_demo
uv venv # Create an isolated virtual environment
source.venv/bin/activate # Activate it (Linux/macOS).\.venv\Scripts\activate # Activate it (Windows PowerShell)

2️⃣ Create pyproject.toml

# Save as: pyproject.toml
[project]
name = "openai_demo"
version = "0.1.0"
description = "A tiny OpenAI client with locked dependencies"
authors = [{name = "Your Name", email = "you@example.com"}]
requires-python = ">=3.9"

[dependency-groups]
default = [
 "openai>=1.0.0",
 "python-dotenv>=1.0.0",
]

[tool.uv]
# Optional: enforce a specific Python version for reproducibility
python = "3.11"

3️⃣ Lock the Dependencies

uv lock # Generates uv.lock with exact versions
uv sync # Installs them into the active venv

✅ Verify: After uv sync you should see no errors and the site-packages folder populated.

4️⃣ Add a .env.example (Never commit real keys!)

# Save as:.env.example
OPENAI_API_KEY=sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Copy it to .env and replace the placeholder with your actual key:

cp.env.example.env
# Edit.env with your favorite editor and paste your real key

💡 Tip: Add .env to .gitignore (see next step) so Git never tracks it.

5️⃣ Create .gitignore

# Save as:.gitignore
# Python artifacts
__pycache__/
*.py[cod]
*.pyo
*.pyd
*.egg-info/
dist/
build/

# Virtual environment.venv/
venv/

# Secrets.env

6️⃣ Write the OpenAI Client (main.py)

# Save as: main.py
import os
from pathlib import Path

from dotenv import load_dotenv
import openai

# ----------------------------------------------------------------------
# Load environment variables from.env (if present)
# ----------------------------------------------------------------------
env_path = Path(__file__).parent / ".env"
if env_path.is_file():
 load_dotenv(dotenv_path=env_path)
else:
 raise FileNotFoundError("❌.env file not found. Create one from.env.example.")

# ----------------------------------------------------------------------
# Retrieve the API key securely
# ----------------------------------------------------------------------
api_key = os.getenv("OPENAI_API_KEY")
if not api_key:
 raise ValueError("❌ OPENAI_API_KEY is missing from.env")

openai.api_key = api_key

# ----------------------------------------------------------------------
# Simple chat completion request
# ----------------------------------------------------------------------
def ask_gpt(prompt: str) -> str:
 """Send a prompt to gpt‑3.5‑turbo and return the assistant's reply."""
 response = openai.ChatCompletion.create(
 model="gpt-3.5-turbo",
 messages=[{"role": "user", "content": prompt}],
 temperature=0.7,
 )
 # Extract the assistant's message
 return response.choices[0].message["content"].strip()


if __name__ == "__main__":
 user_prompt = "Explain why dependency locking matters in one sentence."
 answer = ask_gpt(user_prompt)
 print(f"🤖 GPT says: {answer}")

Expected Output (your actual answer will vary)

🤖 GPT says: Dependency locking ensures every environment uses the exact same package versions, eliminating “works on my machine” bugs.

✅ Verify: Run the script:

python main.py

You should see a one‑sentence answer printed to the console. If you get an authentication error, double‑check your .env key.

📁 Project Files

openai_demo/
├─.gitignore
├─.env.example
├─ main.py
├─ pyproject.toml
└─ uv.lock ← generated by `uv lock`

🚀 What You Just Built

• A locked Python environment (uv.lock) guaranteeing reproducible installs.
• A secure configuration pattern using .env and .gitignore.
• A functional OpenAI client that can be extended to any prompt or model.

All of this is ready for version control, CI pipelines, or deployment to a serverless platform.

Common Mistakes

Troubleshooting

• ImportError: No module named 'dotenv' Run uv sync again; ensure python-dotenv is listed under [dependency-groups].

• openai.error.AuthenticationError

• Verify the key in .env matches the one in your OpenAI dashboard.

• Ensure there are no stray spaces or newline characters.

• uv lock hangs or fails

• Check your internet connection.

• Upgrade uv (uv self update) to the latest stable version.

• Script runs but returns an empty string

• The model may have throttled your request; add max_retries=3 in the ChatCompletion.create call.

Key Takeaways

• Lock files (uv.lock) are the single source of truth for dependencies.
• Environment variables keep secrets out of source control.
• A minimal, reproducible setup can be achieved in under 10 minutes with uv.
• Always verify each step (✅ Verify:) before moving on; it saves debugging time later.

🧪 Try It Yourself

1. Swap models – change "gpt-3.5-turbo" to "gpt-4" (if you have access) and observe the difference.
2. Add a second message – modify messages to include a system prompt that sets a tone, e.g., {"role": "system", "content": "You are a friendly tutor."}.
3. Create a CLI – use argparse to accept the prompt from the command line instead of hard‑coding it.

Happy coding! If anything feels fuzzy, reach out on LinkedIn – I’m happy to walk through any step with you. 🚀

Chapter 3

The Python You Need for GenAI

Save as: chapter1.py

Why This Matters

Tip: After running each command in this chapter, check the output. If you see an error, scroll down to "Common Mistakes" at the bottom of this chapter.

Activate Your Virtual Environment

If you have not activated your venv yet (check: do you see (.venv) in your prompt?):

Windows PowerShell:

   .venv\Scripts\Activate

Mac/Linux:

   source .venv/bin/activate

Expected: Your prompt now starts with (.venv).

Before You Start This Chapter

• Your venv is active (you see `(.

  What is a virtual environment (venv)? It is a separate, isolated Python world for your project. Without it, packages from different projects can conflict. With a venv, each project gets its own clean set of packages. Think of it like a separate browser profile for each website.

venv)in your prompt) - Previous chapter's project is working - Your.env` file has your API key

Get Your OpenAI API Key (if you do not have one)

1. Go to https://platform.openai.com/api-keys
2. Log in (or create a free account)
3. Click "Create new secret key"
4. Name it: adhikk-book
5. Click "Create"
6. Copy the key immediately (starts with sk-) — you will NOT see it again

7. Paste it into your .env file:

   OPENAI_API_KEY=sk-your_key_here

New accounts get $5 free credit — more than enough for this entire book.

• You are in the correct folder (run pwd to check)

Python is a versatile programming language used extensively in various fields, including artificial intelligence, machine learning, and data analysis. Understanding the basics of Python is crucial for anyone looking to build applications, including those using generative AI.

What You'll Build

In this chapter, we will cover the fundamentals of Python, including variables, strings, and lists. We will also explore how to clean and process data using Python's built-in functions.

Content

Variables

Variables are used to store information in a program. In Python, variables are created using the = operator.

name = "John Doe"
age = 30

The name variable stores the string "John Doe", while the age variable stores the integer 30.

Strings

Strings are sequences of characters used to represent text. In Python, strings are enclosed in quotes.

greeting = "Hello, World!"
print(greeting)

Output:

Hello, World!

Lists

Lists are ordered collections of values. In Python, lists are enclosed in square brackets.

fruits = ["Apple", "Banana", "Cherry"]
print(fruits[0])

Output:

Apple

Cleaning and Processing Data

Data cleaning is an essential step in data analysis. In Python, we can use the strip() function to remove whitespace from a string.

data = " Hello, World! "
clean_data = data.strip()
print(clean_data)

Output:

Hello, World!

We can also use the lower() function to convert a string to lowercase.

data = "HELLO, WORLD!"
clean_data = data.lower()
print(clean_data)

Output:

hello, world!

Lists and Indexing

Lists are ordered collections of values. In Python, we can access elements in a list using indexing.

fruits = ["Apple", "Banana", "Cherry"]
print(fruits[0]) # Apple
print(fruits[1]) # Banana
print(fruits[2]) # Cherry

Lists and Slicing

Lists can be sliced to extract a subset of elements.

fruits = ["Apple", "Banana", "Cherry"]
print(fruits[1:3]) # ["Banana", "Cherry"]

Lists and Iterating

Lists can be iterated over using a for loop.

fruits = ["Apple", "Banana", "Cherry"]
for fruit in fruits:
 print(fruit)

Output:

Apple
Banana
Cherry

Lists and Indexing

Lists have an index that starts from 0.

fruits = ["Apple", "Banana", "Cherry"]
print(fruits[0]) # Apple
print(fruits[1]) # Banana
print(fruits[2]) # Cherry

Lists and Slicing

Lists can be sliced to extract a subset of elements.

fruits = ["Apple", "Banana", "Cherry"]
print(fruits[1:3]) # ["Banana", "Cherry"]

Lists and Iterating

Lists can be iterated over using a for loop.

fruits = ["Apple", "Banana", "Cherry"]
for fruit in fruits:
 print(fruit)

Output:

Apple
Banana
Cherry

Lists and Indexing

Lists have an index that starts from 0.

fruits = ["Apple", "Banana", "Cherry"]
print(fruits[0]) # Apple
print(fruits[1]) # Banana
print(fruits[2]) # Cherry

Lists and Slicing

Lists can be sliced to extract a subset of elements.

fruits = ["Apple", "Banana", "Cherry"]
print(fruits[1:3]) # ["Banana", "Cherry"]

Lists and Iterating

Lists can be iterated over using a for loop.

fruits = ["Apple", "Banana", "Cherry"]
for fruit in fruits:
 print(fruit)

Output:

Apple
Banana
Cherry

📁 Project Files

Create a new file called data_cleaning.py and add the following code:

# Save as: data_cleaning.py

# Import the necessary libraries
import re

# Define a function to clean data
def clean_data(data):
 # Remove whitespace from the data
 data = data.strip()
 # Convert the data to lowercase
 data = data.lower()
 # Remove punctuation from the data
 data = re.sub(r'[^\w\s]', '', data)
 return data

# Test the function
data = " Hello, World! "
clean_data = clean_data(data)
print(clean_data)

🚀 What You Just Built

You have built a function to clean data using Python. The function takes a string as input, removes whitespace, converts it to lowercase, and removes punctuation.

Common Mistakes

• Forgetting to import the necessary libraries
• Not handling errors properly
• Not testing the function thoroughly

Troubleshooting

• Check if the necessary libraries are imported correctly
• Check if the function is defined correctly
• Check if the data is in the correct format

Key Takeaways

• Variables are used to store information in a program.
• Strings are sequences of characters used to represent text.
• Lists are ordered collections of values.
• Data cleaning is an essential step in data analysis.
• Python has built-in functions to clean and process data.

🧪 Try It Yourself

Try cleaning a dataset using the clean_data function. Experiment with different cleaning techniques and see how they affect the output.

F Strings in Python

Introduction

F strings are a feature in Python that allows you to embed expressions inside string literals. This feature was introduced in Python 3.6 and is a powerful tool for formatting strings.

Example Code

name = "Aman"
age = 24

# Using f-strings
greeting = f"Hi my name is {name} and I am {age} years old."

print(greeting)

Output:

Hi my name is Aman and I am 24 years old.

Using F-Strings with Variables

name = "Rudraksh"
age = 25

# Using F-strings
greeting = f"Hi my name is {name} and I am {age} years old."

print(greeting)

Output:

Hi my name is Rudraksh and I am 25 years old.

Using F-Strings with Multiple Expressions

name = "Rudraksh"
age = 25
city = "Delhi"

# Using F-strings
greeting = f"Hi my name is {name} and I am {age} years old from {city}."

print(greeting)

Output:

Hi my name is Rudraksh and I am 25 years old from Delhi.

Common Use Cases for F-Strings

F-strings are commonly used for formatting strings in Python. They are particularly useful when you need to embed expressions inside a string.

Tips and Tricks

• F-strings are a powerful tool for formatting strings in Python.
• They can be used with variables, expressions, and even other f-strings.
• F-strings are more readable and efficient than other string formatting methods.

Common Mistakes

• F-strings can be tricky to use, especially when working with complex expressions.
• Make sure to use the correct syntax and formatting when using f-strings.

Troubleshooting

• If you encounter errors when using f-strings, check that you are using the correct syntax and formatting.
• Make sure that the expressions inside the f-string are valid and can be evaluated.

Key Takeaways

• F-strings are a powerful tool for formatting strings in Python.
• They can be used with variables, expressions, and even other f-strings.
• F-strings are more readable and efficient than other string formatting methods.

Why This Matters

The strip() function is used to remove leading and trailing whitespace from a string. This is useful when you want to clean up data before processing it. In this chapter, we'll learn how to create a custom function to strip a string and explore its usage.

What You'll Build

In this chapter, we'll build a simple function to strip a string, call it, and print its result. We'll also learn how to capitalize the first letter of a string and replace words with a more powerful version.

Content

def strip_string(s):
 """Remove leading and trailing whitespace from a string"""
 return s.strip()

# Test the function
print(strip_string(" Hello World "))
# Output: Hello World

# Verify:

def capitalize_title(s):
 """Capitalize the first letter of a string"""
 return s.capitalize()

# Test the function
print(capitalize_title("hello world"))
# Output: Hello World

# Verify:

def replace_words(s, old_word, new_word):
 """Replace a word with a new word in a string"""
 return s.replace(old_word, new_word)

# Test the function
print(replace_words("Python is great", "great", "powerful"))
# Output: Python is powerful

# Verify:

📁 Project Files

• strip_string.py
• capitalize_title.py
• replace_words.py

🚀 What You Just Built

You've built three functions:

1. strip_string(): removes leading and trailing whitespace from a string.
2. capitalize_title(): capitalizes the first letter of a string.
3. replace_words(): replaces a word with a new word in a string.

Common Mistakes

• Make sure to use the correct method to remove whitespace (strip() instead of lstrip() or rstrip()).
• Be careful when using string replacement, as it can modify the original string.

Troubleshooting

• If the strip_string() function doesn't work as expected, check if the input string contains only whitespace characters.
• If the capitalize_title() function doesn't work as expected, check if the input string is empty or contains only whitespace characters.

Key Takeaways

• Use the strip() method to remove leading and trailing whitespace from a string.
• Use the capitalize() method to capitalize the first letter of a string.
• Use the replace() method to replace a word with a new word in a string.

🧪 Try It Yourself

• Create a new string with leading and trailing whitespace.
• Use the strip_string() function to remove the whitespace.
• Print the result.
• Repeat the process with the capitalize_title() function.
• Repeat the process with the replace_words() function.

What's Next

Continue to the next chapter to keep building.

Chapter 4

Making Your First API Call

Chapter 1: The Python Mindset – Why You Don’t Need to Memorize

Why This Matters

If you are reading this book, you likely have a goal: to build AI applications. You are not here to become a "software engineer" in the traditional sense of writing low-level system code or optimizing database queries. Your goal is to become comfortable with Python so that you can focus on the logic of AI, not the syntax of the language.

Many beginners make a critical mistake: they try to memorize every function, every parameter, and every edge case. This is a losing battle. Python is vast, and the AI ecosystem (LangChain, LangGraph, OpenAI API) is even vaster.

The Core Philosophy of This Chapter: 1. Understand, Don't Memorize: You only need to know that a function exists and what it does. You do not need to know how to write it from scratch. 2. Leverage the Ecosystem: If you have worked with Pandas or NumPy, you know that libraries make life easy. You reuse code. You don't reinvent the wheel. 3. The "Why" First: Every line of code should answer a question: Why does this AI app need this specific instruction?

In this chapter, we will strip away the fear of programming. We will look at how computers actually process instructions, compare human language to machine language, and write your first real Python script. By the end, you will understand why Python is the perfect vehicle for AI development.

What You'll Build

In this chapter, you will: 1. Understand the fundamental definition of programming (giving precise instructions). 2. Learn the difference between Natural Language, Pseudocode, and Actual Code. 3. Write your first Python script to print numbers 1 to 10. 4. Understand the concept of "Zero-Based Indexing" and "Exclusive Ranges" in Python. 5. Set up your environment to run Python code.

1. What is Programming, Really?

Let’s strip away the jargon.

Programming is simply giving a computer instructions.

But there is a catch: Computers are not smart. They are precise. If you tell a human, "Give me the numbers from 1 to 10," they understand. They know you mean 1, 2, 3. up to 10. They might ask, "Do you include 10?" but they get the gist.

A computer does not have a "gist." It needs precise instructions.

The Evolution of Instructions

Let’s look at how we translate a simple task into something a computer can execute.

Step 1: Natural Language (Human)

"Give me the numbers from 1 to 10."

A human reads this and understands the intent. A computer cannot read this. It sees characters, not meaning.

Step 2: Pseudocode (The Bridge)

Pseudocode is a way of writing code that looks like code but is written in plain English. It is the bridge between human thought and machine execution.

Pseudocode: text Start Repeat until 10: Show the number Add 1 to the number End

This is much closer to what a computer understands. It has a structure: a start, a loop, an action, and an end.

Step 3: Actual Code (Python)

Python is famous because it looks very similar to Pseudocode. It is readable. It is close to English.

Python: python for i in range(1, 11): print(i)

Notice how close this is to the pseudocode? - for i in range. is the "Repeat until." - print(i) is the "Show the number"

This is why Python is the dominant language for AI. It allows you to focus on the logic (the "what") rather than the syntax (the "how").

2. The "Understand, Don't Memorize" Rule

Here is the most important rule for this book:

You do not need to memorize how to write a function. You only need to understand that the function exists and what it does.

Example: The range() Function

In the code above, we used range(1, 11).

Beginner Mistake: Trying to memorize the internal algorithm of how range generates numbers. Correct Approach: 1. I know range exists. 2. I know it generates a sequence of numbers. 3. I know it takes a start and an end. 4. Crucial Detail: I know the end number is exclusive (not included).

If I forget how to write range, I don't panic. I open my browser, type "Python range function," and I find the documentation in 5 seconds. My job is to call the function, not build it.

This applies to everything in AI: - You don't need to know how the Transformer architecture works at the matrix multiplication level to use Hugging Face. - You don't need to know how LangChain parses documents to use it. - You just need to know: "There is a tool that does X. Here is how I call it."

3. Writing Your First Python Script

Let’s build the "1 to 10" example properly. We will create a file, write the code, and run it.

Prerequisites

You need Python installed on your computer. - Windows: Download from python.org - Mac: Python is usually pre-installed, or install via Homebrew (brew install python) - Linux: Usually pre-installed.

✅ Verify: Open your terminal (Command Prompt on Windows, Terminal on Mac/Linux) and type:

python --version

You should see something like Python 3.9.x or higher. If you see an error, install Python.

The Code

Create a new file named first_script.py.

# Save as: first_script.py

# This is a comment. Python ignores this.
# We are going to print numbers from 1 to 10.

# The range function generates numbers from start to stop-1.
# So range(1, 11) gives us 1, 2, 3, 4, 5, 6, 7, 8, 9, 10.

for i in range(1, 11):
 print(i)

Running the Code

In your terminal, navigate to the folder where you saved first_script.py and run:

python first_script.py

Expected Output

1
2
3
4
5
6
7
8
9
10

✅ Verify: Did you see the numbers 1 through 10 printed on separate lines? If yes, you have successfully written and executed your first Python program.

4. Deep Dive: Why range(1, 11) and Not range(1, 10)?

This is the most common confusion for beginners.

In Python, the range() function works like this: range(start, stop)

• It starts at start.
• It stops before stop.

So: - range(1, 10) produces: 1, 2, 3, 4, 5, 6, 7, 8, 9 (It stops at 9). - range(1, 11) produces: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 (It stops at 10).

Why is it designed this way?

It is called Zero-Based Indexing and Exclusive Ranges. This design makes math easier for computers.

If you want the length of a list, you can just use the stop value.

numbers = list(range(1, 11))
print(len(numbers)) # Output: 10

If range included the end number, calculating lengths and indices would require constant +1 adjustments, leading to more bugs.

💡 Tip: When you see range(0, 10), think "0 to 9". When you see range(1, 11), think "1 to 10".

5. The AI Connection: Why This Matters for LLMs

You might be thinking: "This is just printing numbers. How does this help me build AI apps?"

Here is the connection:

1. Loops are Everywhere: When you process a dataset of 1,000 customer reviews, you will use a for loop to send each review to the AI model.
2. Precision is Key: AI models are sensitive to input. If you feed them data in the wrong order or miss one item because of an off-by-one error (like using range(1, 10) instead of range(1, 11)), your AI app will fail silently.
3. Reusability: Once you understand how to loop through data in Python, you can loop through:
4. A list of prompts.
5. A list of documents for RAG (Retrieval-Augmented Generation).
6. A list of API responses.

The syntax is simple. The power is in the application.

📁 Project Files

Here is the complete file structure for this chapter.

chapter_1/
├── first_script.py

first_script.py

# Save as: first_script.py

# 1. Basic Loop
print("Printing numbers 1 to 10:")
for i in range(1, 11):
 print(i)

print("\n---\n")

# 2. Understanding Range
# Let's see what happens if we make a mistake
print("Mistake: range(1, 10) - Note: 10 is missing!")
for i in range(1, 10):
 print(i, end=" ")
print() # New line

print("\n---\n")

# 3. Using Range with a List (AI Context)
# Imagine these are 3 user prompts we need to send to an AI
prompts = [
 "What is the capital of France?",
 "Write a haiku about Python.",
 "Explain quantum physics simply."
]

print("Processing AI Prompts:")
for index, prompt in enumerate(prompts, start=1):
 # In a real AI app, we would send 'prompt' to an API here.
 # For now, we just print it to show the loop works.
 print(f"Prompt {index}: {prompt}")

Expected Output

Printing numbers 1 to 10:
1
2
3
4
5
6
7
8
9
10

---

Mistake: range(1, 10) - Note: 10 is missing!
1 2 3 4 5 6 7 8 9 

---

Processing AI Prompts:
Prompt 1: What is the capital of France?
Prompt 2: Write a haiku about Python.
Prompt 3: Explain quantum physics simply.

✅ Verify: Run python first_script.py. Do you see the prompts listed with their index numbers? This is exactly how you will iterate over data when building AI applications.

🚀 What You Just Built

You have: 1. Written your first Python script. 2. Executed it in a terminal. 3. Understood the difference between range(1, 10) and range(1, 11). 4. Seen how loops are used to process lists of data (a core pattern in AI development).

Common Mistakes

1. Forgetting the Colon :

# ❌ Wrong
for i in range(1, 11)
 print(i)

# ✅ Correct
for i in range(1, 11):
 print(i)

Python uses colons to indicate the start of a block of code.

2. Indentation Errors

# ❌ Wrong (Inconsistent indentation)
for i in range(1, 11):
print(i)

# ✅ Correct (4 spaces or 1 tab)
for i in range(1, 11):
 print(i)

Python uses indentation (whitespace) to define code blocks. You must be consistent. The standard is 4 spaces.

3. Using range(1, 10) when you want 10

As discussed, range stops before the end number. Always add 1 to your desired end number if you want to include it.

Troubleshooting

Problem: python command not found. Solution: - Windows: Make sure you checked "Add Python to PATH" during installation.

What is PATH? PATH is a list of folders your computer checks when you type a command. If you type python, your computer looks in each PATH folder for a file called python.exe. If it finds it, it runs it. If not, you get "command not found." Installing Python with "Add to PATH" checked adds Python's folder to this list.

If not, reinstall Python and check that box. - Mac/Linux: Try python3 instead of python.

Problem: IndentationError: unexpected indent Solution: Check your spaces. Ensure all lines inside the for loop are indented by the same amount (4 spaces).

Problem: SyntaxError: invalid syntax Solution: Check for missing colons : or parentheses ().

Key Takeaways

1. Programming is giving precise instructions. Computers are not smart; they are literal.
2. Understand, Don't Memorize. You don't need to know how range works internally. You just need to know how to call it.
3. Python is Readable. It is close to English, which makes it ideal for AI developers who need to focus on logic, not syntax.
4. range(start, stop) is exclusive. range(1, 11) gives you 1 to 10.
5. Loops are your best friend. You will use them to process data, send prompts, and handle API responses.

🧪 Try It Yourself

1. Change the Range: Modify first_script.py to print numbers from 5 to 15. What should the range() call look like?
2. Add a Step: Can you make the loop print only even numbers? (Hint: You can use range(start, stop, step)).
3. Create a List: Create a list of 5 AI-related terms (e.g., "LLM", "RAG", "Prompt", "Token", "API").

   What is a token? A token is how AI models count text. Think of it as a "word piece" — roughly 3-4 characters. "Hello" = 1 token. "Hello world" = 2 tokens. Models have a limit on how many tokens they can process at once (called the "context window").

Loop through them and print each one with a prefix like "Term 1: LLM".

Expected Output for Try It Yourself #3:

Term 1: LLM
Term 2: RAG
Term 3: Prompt
Term 4: Token
Term 5: API

Once you can do this, you are ready for Chapter 2, where we will start building actual AI applications using the OpenAI API.

Chapter 2: The AI Developer’s Toolkit – Python, APIs, and Your First Environment

Why This Matters

You might be thinking, "I have ChatGPT. Why do I need to learn Python? Why do I need to write code at all?"

This is the most common misconception among beginners. Here is the hard truth: ChatGPT is a product, not a platform. It is a pre-built application with a fixed interface. You cannot embed ChatGPT into your own e-commerce site, your own data pipeline, or your own mobile app. You cannot fine-tune its behavior to strictly follow your company’s legal guidelines. You cannot process 10,000 documents in parallel.

To build your own AI agents, you need to interact with the underlying models (like GPT-4, Llama, or Mistral) via APIs (Application Programming Interfaces). And the language that the entire AI ecosystem speaks is Python.

In this chapter, we will: 1. Understand why Python is the undisputed king of AI. 2. Clarify the difference between a "Chat App" and an "API." 3. Set up a zero-install coding environment (Google Colab). 4. Write and execute your first Python script. 5. Make your first API call to an AI model.

What You'll Build

By the end of this chapter, you will have: * A working Google Colab notebook. * A Python script that imports essential AI libraries. * A functional API call to an AI model (using a free tier or mock data for now) that returns a text response. * A clear mental model of how data flows from your code to the AI model and back.

1. Why Python?

You asked: "Which language do almost all AI research papers ship their code in?"

Direct Answer: Python.

The Ecosystem Advantage

Python is not just a language; it is an ecosystem. * Libraries: Libraries like PyTorch, TensorFlow, Hugging Face Transformers, and LangChain are written in Python. If you try to use C++ or Java for AI, you will spend 80% of your time fighting with bindings and 20% building. In Python, you spend 90% building. * Community: When a new AI model is released (e.g., Llama 3), the Python implementation is available within hours. * Readability: Python code looks like pseudocode. This allows you to focus on the logic of the AI agent, not the syntax of the language.

⚠️ Warning: Do not try to learn C++ or Java for AI right now. You will get stuck in the weeds. Stick to Python.

2. ChatGPT vs. API

Let’s clear up the confusion.

What is an API?

An API (Application Programming Interface) is a set of rules that allows one software application to communicate with another.

Analogy: * ChatGPT is like a restaurant where you sit at a table, order food, and eat. * API is like a delivery service. You send an order (request) via a phone app, the kitchen (AI Model) prepares the food, and it is delivered to your house (your application). You don’t see the kitchen; you just get the result.

In this book, we will use APIs to build AI agents.

3. Setting Up Your Environment: Google Colab

You do not need to install Python, Jupyter, or any libraries on your local machine right now. We will use Google Colab (Colaboratory).

Why Colab?

1. Free: No cost for basic usage.
2. No Setup: It runs in your browser.
3. GPU Access: You can access free GPUs for heavy AI tasks (later chapters).
4. Shareable: You can share your code with others via a link.

Step-by-Step Setup

1. Go to colab.research.google.com.
2. Sign in with your Google account.
3. Click File > New Notebook.
4. Name your notebook Chapter2_AI_Environment.

✅ Verify: You should see a blank notebook with a cell that says # Welcome to Colab.

4. Your First Python Code

Let’s write some code to ensure our environment is working.

Step 1: Basic Python Syntax

In the first cell of your Colab notebook, type the following:

# Save as: chapter2_basic.py (Conceptual - in Colab, just run the cell)

# This is a comment. Python ignores it.
print("Hello, AI Developer!")

# Variables
model_name = "GPT-4"
temperature = 0.7

print(f"Model: {model_name}")
print(f"Temperature: {temperature}")

Expected Output:

Hello, AI Developer!
Model: GPT-4
Temperature: 0.7

✅ Verify: Click the Play button (▶️) on the left side of the cell. The output should appear below the cell.

Step 2: Installing AI Libraries

In AI, we rarely write everything from scratch. We use libraries. Let’s install the most important one for API calls: requests.

Create a new cell and run:

# Install the requests library
!pip install requests

💡 Tip: The ! symbol in Jupyter/Colab notebooks allows you to run system commands (like pip install) directly.

Expected Output:

Collecting requests
 Downloading requests-2.31.0-py3-none-any.whl (62 kB).
Successfully installed requests-2.31.0

✅ Verify: You should see "Successfully installed" at the end of the output.

5. Making Your First API Call

Now, let’s simulate an API call. In a real scenario, you would use an API key from OpenAI, Anthropic, or Hugging Face. For this chapter, we will use a mock API to demonstrate the structure without needing a credit card.

Understanding the API Request Structure

An API request typically has three parts: 1. Endpoint: The URL where the service lives. 2. Headers: Metadata (like your API key). 3. Body: The actual data (your prompt).

Step 3: The API Call Script

Create a new cell and paste the following code. This code simulates sending a prompt to an AI model and receiving a response.

# Save as: chapter2_api_call.py

import requests
import json

# 1. Define the API Endpoint
# Note: This is a MOCK endpoint for demonstration. 
# In real life, you would use https://api.openai.com/v1/chat/completions
url = "https://httpbin.org/post" 

# 2. Define the Headers
# In a real API, this would include: "Authorization": "Bearer YOUR_API_KEY"
headers = {
 "Content-Type": "application/json"
}

# 3. Define the Payload (Body)
# This is what you are sending to the AI
payload = {
 "model": "gpt-4",
 "messages": [
 {
 "role": "system",
 "content": "You are a helpful assistant."
 },
 {
 "role": "user",
 "content": "Explain what an API is in one sentence."
 }
 ],
 "temperature": 0.7
}

# 4. Make the Request
print("Sending request to API.")
response = requests.post(url, headers=headers, json=payload)

# 5. Check the Response
print(f"Status Code: {response.status_code}")

if response.status_code == 200:
 # Parse the JSON response
 data = response.json()

 # In a real AI API, the response structure would be different.
 # Here, httpbin.org just echoes back what we sent.
 print("Response received:")
 print(json.dumps(data, indent=2))
else:
 print(f"Error: {response.status_code}")
 print(response.text)

Expected Output:

Sending request to API.
Status Code: 200
Response received:
{
 "args": {},
 "data": "{\"model\": \"gpt-4\", \"messages\": [.], \"temperature\": 0.7}",
 "files": {},
 "form": {},
 "headers": {
 "Content-Type": "application/json",.
 },
 "json": {
 "model": "gpt-4",
 "messages": [
 {
 "role": "system",
 "content": "You are a helpful assistant."
 },
 {
 "role": "user",
 "content": "Explain what an API is in one sentence."
 }
 ],
 "temperature": 0.7
 },
 "origin": "Your IP Address",
 "url": "https://httpbin.org/post"
}

✅ Verify: 1. The status code is 200 (Success). 2. The json field in the response contains your exact prompt. 3. This proves that your code successfully sent data to a server and received a structured response.

⚠️ Important: This was a mock call. httpbin.org is a testing service that just echoes back your data. It does not generate AI text. In the next chapter, we will connect to a real AI provider.

6. Real-World API Structure (Preview)

To prepare you for the next chapter, here is what a real OpenAI API call looks like. You do not need to run this yet (you need an API key), but read it carefully.

# Save as: chapter2_real_api_preview.py

import requests
import json

# You would get this key from https://platform.openai.com/api-keys
API_KEY = "sk-your-actual-key-here" 

url = "https://api.openai.com/v1/chat/completions"

headers = {
 "Authorization": f"Bearer {API_KEY}",
 "Content-Type": "application/json"
}

payload = {
 "model": "gpt-4",
 "messages": [
 {"role": "system", "content": "You are a helpful assistant."},
 {"role": "user", "content": "What is 2+2?"}
 ],
 "max_tokens": 50
}

# This is the actual call
# response = requests.post(url, headers=headers, json=payload)
# print(response.json())

Key Differences from the Mock: 1. Authorization Header: Contains your secret API key. 2. Endpoint: Points to api.openai.com. 3. Response: Would contain the actual AI-generated text in response['choices'][0]['message']['content'].

📁 Project Files

Here is the structure of the files we created in this chapter. In Colab, these are just cells, but if you were working locally, they would look like this:

chapter2/
├── chapter2_basic.py
├── chapter2_api_call.py
└── chapter2_real_api_preview.py

🚀 What You Just Built

1. Environment: You set up a professional-grade Python environment (Colab) without installing anything locally.
2. Library Management: You learned how to install libraries using !pip install.
3. API Communication: You wrote code that sends a structured JSON payload to a server and parses the response.
4. Mental Model: You now understand that AI is not magic; it is a service you talk to via HTTP requests.

Common Mistakes

1. Forgetting the ! in Colab:
2. Mistake: pip install requests
3. Fix: !pip install requests

4. Why: Without !, Python tries to run pip as a Python command, which fails.

5. Hardcoding API Keys:

6. Mistake: API_KEY = "sk-123456" in your code.
7. Fix: Use environment variables.

8. Why: If you share your code, your key is exposed. In the next chapter, we will show you how to use environment variables securely.

9. Ignoring Status Codes:

10. Mistake: Assuming the API always works.
11. Fix: Always check if response.status_code == 200.
12. Why: APIs can fail due to rate limits, invalid keys, or server errors. Your code must handle these gracefully.

Troubleshooting

Key Takeaways

1. Python is the language of AI. Do not switch to C++ or Java.
2. ChatGPT is a product; APIs are tools. You build with APIs.
3. Colab is your sandbox. Use it for learning and prototyping.
4. APIs use JSON. You send JSON, you receive JSON.
5. Always check status codes. Never assume success.

🧪 Try It Yourself

1. Modify the Prompt: In the chapter2_api_call.py cell, change the user content to "Write a haiku about Python." Run it again. Does the structure change? (It shouldn’t, because it’s a mock, but observe the JSON).
2. Add a New Field: Add "max_tokens": 100 to the payload. Run it again. Does the response include this field?
3. Break It Intentionally: Change the URL to https://httpbin.org/get (instead of /post). Run it. What happens? (Hint: The method is wrong).

Next Chapter Preview

In Chapter 3, we will: * Get a real API key from a free provider (Hugging Face or OpenAI). * Make a real API call that generates actual AI text. * Learn how to handle errors and rate limits. * Build your first "AI Agent" that can answer questions.

Ready? Let’s go.

Chapter 3: Mastering API Integration with Python

Why This Matters

In the previous section, we established that building infrastructure from scratch (like satellite tracking or map rendering) is inefficient and expensive. Companies like Swiggy or Uber do not build their own GPS networks; they consume APIs (Application Programming Interfaces) provided by giants like Google Maps.

An API is a contract between two software systems. It allows your code to ask a remote server for data (e.g., "What is the distance between Point A and Point B?") and receive a structured response (usually JSON).

In this chapter, you will learn how to: 1. Set up a Python environment using Google Colab (free, cloud-based). 2. Understand the anatomy of an HTTP Request (GET, POST, Headers, Body). 3. Make your first API call using the requests library. 4. Parse JSON responses and extract specific data. 5. Handle errors and authentication (API Keys).

By the end of this chapter, you will have built a Real-Time Weather Dashboard and a Geolocation Distance Calculator that interacts with live external servers.

What You'll Build

1. Weather Fetcher: A script that fetches current weather data for any city from the OpenWeatherMap API.
2. Distance Calculator: A script that calculates the travel time and distance between two coordinates using the Google Distance Matrix API (simulated with a free alternative for this chapter to avoid billing, but the logic is identical).
3. API Client Class: A reusable Python class that handles API requests, error checking, and data parsing.

1. Setting Up the Environment: Google Colab

As mentioned in the previous section, you don't need to install Python locally to start. Google Colab provides a free Jupyter Notebook environment in your browser.

Step 1: Access Colab

1. Go to colab.research.google.com.
2. Log in with your Google Account.
3. Click File > New Notebook.

Step 2: Install Required Libraries

We will use the requests library to handle HTTP calls. While requests is often pre-installed, it's good practice to ensure it's available.

# Save as: setup_cell.py
# Run this cell in Colab

import sys

# Check if requests is installed
try:
 import requests
 print(f"✅ 'requests' library is already installed (version {requests.__version__})")
except ImportError:
 print("❌ 'requests' not found. Installing.")
 !pip install requests
 import requests
 print(f"✅ 'requests' installed successfully (version {requests.__version__})")

Expected Output:

✅ 'requests' library is already installed (version 2.31.0)

(Note: The version number may vary.)

✅ Verify: If you see the success message, your environment is ready.

2. Anatomy of an API Call

Before writing code, understand what happens when you call an API.

The HTTP Request

An API call is an HTTP Request. It has four main parts:

1. Method:
2. GET: Retrieve data (e.g., "Give me the weather for New York").
3. POST: Send data to the server (e.g., "Create a new user").
4. PUT: Update existing data.
5. DELETE: Remove data.
6. URL (Endpoint): The address of the resource (e.g., https://api.openweathermap.org/data/2.5/weather).
7. Headers: Metadata about the request (e.g., Authorization: Bearer <token>, Content-Type: application/json).
8. Body: The data being sent (only for POST/PUT requests).

The HTTP Response

The server responds with: 1. Status Code: * 200: Success. * 400: Bad Request (your parameters are wrong). * 401: Unauthorized (missing or invalid API key). * 404: Not Found (endpoint doesn't exist). * 500: Server Error (something broke on their end). 2. Headers: Metadata about the response. 3. Body: The actual data, usually in JSON format.

3. Making Your First API Call: Weather Data

We will use OpenWeatherMap, a free API for weather data.

Step 1: Get an API Key

1. Go to openweathermap.org/api.
2. Sign up for a free account.
3. Go to API Keys in the dashboard.
4. Copy your API Key (it looks like a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6).

⚠️ Warning: Never hardcode your API key in public code or commit it to GitHub. For this chapter, we will store it in a variable. In production, use environment variables.

Step 2: Write the Code

# Save as: weather_fetcher.py

import requests
import json

# 1. Define the API Key
API_KEY = "YOUR_API_KEY_HERE" # Replace with your actual key

# 2. Define the Endpoint
BASE_URL = "http://api.openweathermap.org/data/2.5/weather"

# 3. Define Parameters
# We want weather for "London" in metric units (Celsius)
params = {
 "q": "London",
 "units": "metric",
 "appid": API_KEY
}

# 4. Make the GET Request
print("🔄 Sending request to OpenWeatherMap.")
response = requests.get(BASE_URL, params=params)

# 5. Check the Status Code
print(f"Status Code: {response.status_code}")

if response.status_code == 200:
 # 6. Parse the JSON Response
 weather_data = response.json()

 # 7. Extract Specific Data
 city = weather_data['name']
 temp = weather_data['main']['temp']
 feels_like = weather_data['main']['feels_like']
 humidity = weather_data['main']['humidity']
 description = weather_data['weather'][0]['description']

 # 8. Display Results
 print("\n" + "="*30)
 print(f"🌍 City: {city}")
 print(f"🌡️ Temperature: {temp}°C")
 print(f"🧊 Feels Like: {feels_like}°C")
 print(f"💧 Humidity: {humidity}%")
 print(f"☁️ Condition: {description}")
 print("="*30)

 # Optional: Print the full JSON to see the structure
 # print(json.dumps(weather_data, indent=2))

else:
 print(f"❌ Error: {response.text}")

Expected Output:

🔄 Sending request to OpenWeatherMap.
Status Code: 200

==============================
🌍 City: London
🌡️ Temperature: 15.3°C
🧊 Feels Like: 14.1°C
💧 Humidity: 78%
☁️ Condition: light rain
==============================

✅ Verify: 1. Did you receive a 200 status code? 2. Does the temperature match the current weather in London? 3. If you see 401 Unauthorized, your API key is wrong. 4. If you see 404 Not Found, check the URL or parameters.

💡 Tip: If you are unsure about the JSON structure, use print(json.dumps(response.json(), indent=2)) to see the full nested object. This is the most common debugging step for API work.

4. Handling Errors Like a Pro

In production, APIs fail. Networks drop, servers go down, or you might make a typo in a parameter. Your code must handle these gracefully.

Common Error Scenarios

1. Connection Error: The server is unreachable.
2. Timeout: The server took too long to respond.
3. HTTP Error: The server responded, but with an error code (4xx or 5xx).

Robust API Call Function

# Save as: robust_api_call.py

import requests
from requests.exceptions import ConnectionError, Timeout, HTTPError

def fetch_data(url, params=None, headers=None, timeout=10):
 """
 A robust function to fetch data from an API.

 Args:
 url (str): The endpoint URL.
 params (dict): Query parameters.
 headers (dict): Request headers.
 timeout (int): Seconds to wait before timing out.

 Returns:
 dict: Parsed JSON data if successful, None otherwise.
 """
 try:
 print(f"📡 Requesting: {url}")
 response = requests.get(url, params=params, headers=headers, timeout=timeout)

 # Raise an exception for 4xx or 5xx status codes
 response.raise_for_status()

 # Parse JSON
 data = response.json()
 print("✅ Success: Data received.")
 return data

 except HTTPError as http_err:
 print(f"❌ HTTP Error occurred: {http_err}")
 print(f" Response: {response.text}")
 return None

 except ConnectionError:
 print("❌ Connection Error: Could not reach the server.")
 return None

 except Timeout:
 print("❌ Timeout Error: The server took too long to respond.")
 return None

 except Exception as e:
 print(f"❌ Unexpected Error: {e}")
 return None

# --- Test the Function ---

# Test 1: Valid Request
API_KEY = "YOUR_API_KEY_HERE"
url = "http://api.openweathermap.org/data/2.5/weather"
params = {"q": "Paris", "units": "metric", "appid": API_KEY}

data = fetch_data(url, params=params)

if data:
 print(f"Paris Temperature: {data['main']['temp']}°C")

# Test 2: Invalid City (Should return 404)
print("\n--- Testing Invalid City ---")
params_invalid = {"q": "NonExistentCity123", "units": "metric", "appid": API_KEY}
data_invalid = fetch_data(url, params=params_invalid)

Expected Output (for Test 2):

📡 Requesting: http://api.openweathermap.org/data/2.5/weather
❌ HTTP Error occurred: 404 Client Error: Not Found for url:.
 Response: {"cod":"404","message":"city not found"}

✅ Verify: 1. The function returns None on error instead of crashing. 2. The error message is clear and helpful.

5. POST Requests: Sending Data

So far, we've only used GET requests (retrieving data). Now, let's send data to a server using POST.

We will use a free echo API: httpbin.org. This service simply returns whatever you send to it, which is perfect for testing.

Step 1: Send a JSON Payload

# Save as: post_request_example.py

import requests
import json

url = "https://httpbin.org/post"

# The data we want to send
payload = {
 "username": "john_doe",
 "email": "john@example.com",
 "action": "login"
}

# Headers to indicate we are sending JSON
headers = {
 "Content-Type": "application/json"
}

print("📤 Sending POST request.")
response = requests.post(url, json=payload, headers=headers)

if response.status_code == 200:
 result = response.json()

 # httpbin returns the JSON we sent in the 'json' field
 echoed_data = result['json']

 print("✅ Server received the following data:")
 print(json.dumps(echoed_data, indent=2))

 # Verify the data matches what we sent
 if echoed_data == payload:
 print("✅ Data integrity check passed.")
 else:
 print("❌ Data mismatch!")
else:
 print(f"❌ Error: {response.status_code}")

Expected Output:

📤 Sending POST request.
✅ Server received the following data:
{
 "username": "john_doe",
 "email": "john@example.com",
 "action": "login"
}
✅ Data integrity check passed.

✅ Verify: 1. The server echoed back the exact JSON we sent. 2. The Content-Type header was correctly set to application/json.

💡 Tip: When sending JSON, always use the json= parameter in requests.post(). This automatically sets the Content-Type header and serializes the Python dictionary to a JSON string. Do not use data=json.dumps(payload) unless you have a specific reason.

6. Building a Reusable API Client Class

In real projects, you will interact with multiple endpoints of the same API. Instead of repeating URL construction and header setup, create a class.

The WeatherClient Class

# Save as: weather_client.py

import requests
from typing import Optional, Dict, Any

class WeatherClient:
 """
 A client class for interacting with the OpenWeatherMap API.
 """

 BASE_URL = "http://api.openweathermap.org/data/2.5"

 def __init__(self, api_key: str):
 """
 Initialize the client with an API key.

 Args:
 api_key (str): Your OpenWeatherMap API key.
 """
 if not api_key:
 raise ValueError("API key cannot be empty.")
 self.api_key = api_key
 self.session = requests.Session() # Reuse connection for efficiency

 def _get(self, endpoint: str, params: Dict[str, Any]) -> Optional[Dict]:
 """
 Internal method to handle GET requests.
 """
 url = f"{self.BASE_URL}/{endpoint}"
 params["appid"] = self.api_key # Automatically add API key

 try:
 response = self.session.get(url, params=params, timeout=10)
 response.raise_for_status()
 return response.json()
 except requests.RequestException as e:
 print(f"❌ API Error: {e}")
 return None

 def get_current_weather(self, city: str, units: str = "metric") -> Optional[Dict]:
 """
 Get current weather for a city.

 Args:
 city (str): Name of the city.
 units (str): 'metric' (Celsius) or 'imperial' (Fahrenheit).

 Returns:
 Dict: Weather data or None if error.
 """
 params = {
 "q": city,
 "units": units
 }
 return self._get("weather", params)

 def get_forecast(self, city: str, units: str = "metric") -> Optional[Dict]:
 """
 Get 5-day forecast for a city.

 Args:
 city (str): Name of the city.
 units (str): 'metric' or 'imperial'.

 Returns:
 Dict: Forecast data or None if error.
 """
 params = {
 "q": city,
 "units": units
 }
 return self._get("forecast", params)

# --- Usage Example ---

if __name__ == "__main__":
 # Initialize the client
 client = WeatherClient(api_key="YOUR_API_KEY_HERE")

 # Get current weather
 print("🌍 Current Weather in Tokyo:")
 weather = client.get_current_weather("Tokyo")
 if weather:
 print(f" Temp: {weather['main']['temp']}°C")
 print(f" Condition: {weather['weather'][0]['description']}")

 # Get forecast
 print("\n📅 5-Day Forecast for New York:")
 forecast = client.get_forecast("New York")
 if forecast:
 for day in forecast['list'][:5]: # Show first 5 entries
 date = day['dt_txt']
 temp = day['main']['temp']
 desc = day['weather'][0]['description']
 print(f" {date}: {temp}°C, {desc}")

Expected Output:

🌍 Current Weather in Tokyo:
 Temp: 18.5°C
 Condition: clear sky

📅 5-Day Forecast for New York:
 2023-10-27 03:00:00: 12.3°C, clear sky
 2023-10-27 06:00:00: 11.8°C, clear sky
 2023-10-27 09:00:00: 14.2°C, few clouds
 2023-10-27 12:00:00: 16.5°C, scattered clouds
 2023-10-27 15:00:00: 15.9°C, broken clouds

✅ Verify: 1. The class handles the API key internally. 2. You can call multiple methods (get_current_weather, get_forecast) without repeating setup code. 3. The session is reused, which is faster than creating a new connection for each request.

📁 Project Files

Here is the complete structure of the code we built in this chapter:

project_api_integration/
├── setup_cell.py # Environment setup
├── weather_fetcher.py # Basic GET request example
├── robust_api_call.py # Error handling example
├── post_request_example.py # POST request example
└── weather_client.py # Reusable API client class

🚀 What You Just Built

1. A Robust API Client: You now have a reusable class that can fetch weather data from any city.
2. Error Handling: Your code no longer crashes when the API fails. It logs the error and returns None.
3. POST Requests: You learned how to send data to a server using JSON payloads.
4. Session Management: You used requests.Session() to improve performance by reusing TCP connections.

Common Mistakes

1. Hardcoding API Keys:
2. ❌ API_KEY = "abc123"
3. ✅ Use environment variables: import os; API_KEY = os.environ.get("API_KEY")
4. Ignoring Status Codes:
5. ❌ Assuming response.json() will always work.
6. ✅ Always check response.status_code or use response.raise_for_status().
7. Not Setting Timeouts:
8. ❌ requests.get(url) can hang forever if the server is slow.
9. ✅ Always set timeout=10 (or similar).
10. Using data= for JSON:
11. ❌ requests.post(url, data=json.dumps(payload))
12. ✅ requests.post(url, json=payload)

Troubleshooting

Key Takeaways

1. APIs are Contracts: Always read the documentation. The URL, parameters, and response structure are defined by the provider.
2. Always Handle Errors: APIs fail. Your code must be resilient.
3. Use Sessions: For multiple requests to the same server, use requests.Session() for better performance.
4. Encapsulate Logic: Create a class for each API you interact with. This makes your code cleaner and easier to maintain.
5. JSON is the Standard: Most APIs return JSON. Learn to navigate nested JSON structures using Python dictionaries.

🧪 Try It Yourself

1. Add a New Method: Add a method get_air_quality(city) to the WeatherClient class. The endpoint is air_pollution.
2. Implement Retry Logic: Modify the _get method to retry the request 3 times if it fails with a 500 error.
3. Use Environment Variables: Modify the code to read the API key from an environment variable instead of hardcoding it.
4. Build a CLI Tool: Create a command-line interface where the user can type a city name and get the weather. Use the argparse library.

Hint for #4:

import argparse

parser = argparse.ArgumentParser(description="Get weather for a city.")
parser.add_argument("city", type=str, help="Name of the city")
args = parser.parse_args()

Next Chapter

In the next chapter, we will dive deeper into Authentication. We will learn how to handle OAuth 2.0, JWT tokens, and secure API keys in production environments. We will also build a User Authentication System using Flask and JWT.

Stay tuned!

Chapter 4: Setting Up Your Professional Development Environment

Why This Matters

In the previous section, we briefly touched upon Jupyter Notebooks. However, for building production-grade AI agents, you need a robust, reproducible, and isolated development environment.

Why not just use the system Python? 1. Dependency Conflicts: One project might need pandas==1.5, while another needs pandas==2.0. Installing both globally breaks everything. 2. Reproducibility: If you share your code with a teammate, they need to be able to run it exactly as you did. 3. Cleanliness: You don't want 50 unused libraries cluttering your system.

Virtual Environments (Venv) solve this by creating an isolated Python environment for each project.

What is a virtual environment (venv)? It is a separate, isolated Python world for your project. Without it, packages from different projects can conflict. With a venv, each project gets its own clean set of packages. Think of it like a separate browser profile for each website.

What You'll Build

In this section, you will: 1. Create a project directory structure. 2. Initialize a Python Virtual Environment. 3. Create a requirements.txt file to manage dependencies. 4. Install the necessary libraries (openai, pandas, jupyter). 5. Launch Jupyter Notebook within VS Code using the correct kernel.

Step 1: Create Your Project Structure

First, let's set up a clean folder structure. This is best practice for any software project.

Open your terminal (Command Prompt on Windows, Terminal on Mac/Linux) and run the following commands:

# Create the main project folder
mkdir ai-agent-fundamentals
cd ai-agent-fundamentals

# Create subdirectories for organization
mkdir src
mkdir notebooks
mkdir data
mkdir.venv

✅ Verify: Run ls (Mac/Linux) or dir (Windows) to see the folders created.

Step 2: Initialize the Virtual Environment

We will use Python's built-in venv module. No extra installation is needed.

Windows:

python -m venv.venv

Mac/Linux:

python3 -m venv.venv

⚠️ Warning: If you see an error like "No module named venv" on Mac, install it with brew install python-tk or ensure you have the latest Python installed via Homebrew.

✅ Verify: You should see a new folder named .venv in your project directory. It contains bin (Mac/Linux) or Scripts (Windows) folders.

Step 3: Activate the Virtual Environment

Before installing any packages, you must activate the environment. This changes your shell prompt to show (.venv).

Windows: ```bash.venv\Scripts\activate

**Mac/Linux:**
```bash
source.venv/bin/activate

✅ Verify: Your terminal prompt should now look like this:

(.venv) user@machine:~/ai-agent-fundamentals$

If you don't see (.venv), you are not in the virtual environment. Do not proceed until you are.

Step 4: Create and Install Dependencies

We will create a requirements.txt file. This file lists all the Python packages our project needs. This is the "recipe" for your environment.

Create a file named requirements.txt in the root of your project (ai-agent-fundamentals/).

File: requirements.txt

openai>=1.0.0
pandas>=2.0.0
jupyter>=1.0.0
ipykernel>=6.0.0

💡 Tip: The >= symbol means "install this version or newer." This ensures you get bug fixes while maintaining compatibility.

Now, install these packages into your virtual environment:

pip install -r requirements.txt

✅ Verify: Wait for the installation to complete. You should see "Successfully installed." at the end.

To confirm the packages are installed, run:

pip list

You should see openai, pandas, jupyter, and ipykernel in the list.

Step 5: Set Up Jupyter Kernel

Jupyter needs to know about your virtual environment's Python interpreter. We do this by registering the kernel.

python -m ipykernel install --user --name myenv --display-name "Python (myenv)"

✅ Verify: You should see a message like:

Installed kernelspec myenv in /Users/yourname/Library/Jupyter/kernels/myenv

(Or similar path depending on your OS)

Step 6: Open Project in VS Code

1. Open Visual Studio Code.
2. Go to File > Open Folder.
3. Select your ai-agent-fundamentals folder.
4. VS Code should automatically detect the .venv folder. If not, press Ctrl+Shift+P (or Cmd+Shift+P on Mac) and type: Python: Select Interpreter
5. Choose the interpreter that points to your .venv folder: .venv\Scripts\python.exe (Windows).venv/bin/python (Mac/Linux)

✅ Verify: Look at the bottom right corner of VS Code. It should say Python 3.x.x ('.venv').

Step 7: Create and Run Your First Notebook

1. In VS Code, go to the notebooks folder.
2. Right-click > New File.
3. Name it 01_variables.ipynb.
4. Open the file. You will see a Jupyter Notebook interface.

Important: Look at the top right of the notebook. It says "Select Kernel". Click on it and choose Python (myenv). This ensures the notebook uses your virtual environment.

Now, type the following code into the first cell:

File: notebooks/01_variables.ipynb

# Save as: notebooks/01_variables.ipynb

# Define variables
user_question = "What is an AI agent?"
model_name = "GPT-4"
city = "Bangalore"
age = 25

# Print them
print(f"User Question: {user_question}")
print(f"Model Name: {model_name}")
print(f"City: {city}")
print(f"Age: {age}")

Press Shift + Enter to run the cell.

✅ Expected Output:

User Question: What is an AI agent?
Model Name: GPT-4
City: Bangalore
Age: 25

✅ Verify: If you see the output above, your environment is perfectly set up. If you get a ModuleNotFoundError, you selected the wrong kernel. Go back to Step 7 and ensure you selected Python (myenv).

📁 Project Files

Here is the complete structure of your project so far:

ai-agent-fundamentals/
├──.venv/ # Virtual environment (do not edit)
├── data/ # For storing datasets
├── notebooks/
│ └── 01_variables.ipynb # Our first notebook
├── src/ # For Python scripts
├── requirements.txt # List of dependencies
└── README.md # (Optional) Project description

🚀 What You Just Built

You have successfully: 1. Created an isolated Python environment. 2. Managed dependencies using requirements.txt. 3. Set up Jupyter Notebook with the correct kernel in VS Code. 4. Run your first Python code in a professional setup.

This setup is reproducible. If you delete your .venv folder and run pip install -r requirements.txt, you will get the exact same environment again.

Common Mistakes

1. Forgetting to Activate the Virtual Environment

Symptom: pip install installs packages globally, not in your project. Fix: Always check your terminal prompt for (.venv). If it's missing, run the activation command again.

2. Using the Wrong Kernel in Jupyter

Symptom: ModuleNotFoundError: No module named 'openai' even though you installed it. Fix: In the notebook, click "Select Kernel" and choose the one that says Python (myenv) or points to your .venv path.

3. Mixing python and python3

Symptom: Confusing errors on Mac/Linux. Fix: Be consistent. If you created the venv with python3, use python3 for activation and kernel installation.

Troubleshooting

"No module named venv"

Cause: Your Python installation is incomplete. Fix: - Windows: Reinstall Python from python.org and check "Add to PATH" and "Install for all users". - Mac: brew install python - Linux: sudo apt install python3-venv

"Permission denied" when activating venv on Mac

Cause: Security restrictions. Fix: Run chmod +x.venv/bin/activate and then try activating again.

Jupyter Kernel Not Showing Up

Cause: Kernel not registered. Fix: Run python -m ipykernel install --user --name myenv --display-name "Python (myenv)" again while the venv is active.

Key Takeaways

1. Always use a virtual environment. It keeps your projects isolated and clean.
2. requirements.txt is your friend. It documents your dependencies and makes setup easy for others.
3. VS Code + Jupyter is a powerful combo. Use the "Select Kernel" feature to ensure your notebook uses the correct Python interpreter.
4. Shift + Enter runs the current cell and moves to the next. Use it to iterate quickly.

🧪 Try It Yourself

1. Create a new notebook named 02_data_types.ipynb.
2. Define variables for different data types: python name = "Priya" # String age = 25 # Integer height = 5.6 # Float is_student = True # Boolean skills = ["Python", "AI", "Data Science"] # List
3. Print each variable and its type using type(): python print(f"{name} is a {type(name)}") print(f"{age} is a {type(age)}") #. and so on
4. Try to change the type of age to a string and see what happens when you try to add it to another number.

✅ Expected Output:

Priya is a <class'str'>
25 is a <class 'int'>
5.6 is a <class 'float'>
True is a <class 'bool'>
['Python', 'AI', 'Data Science'] is a <class 'list'>

In the next section, we will dive deeper into Python Data Types and how they relate to building AI agents.

Chapter 4: Data Types, Strings, and Logic

Why This Matters

In the previous section, we established that Python is a language of types. You cannot mix apples and oranges (strings and integers) without explicit conversion. Now, we move to the most critical data type for LLM development: Strings.

An LLM is fundamentally a string-in, string-out machine. * Input: A prompt (String) * Output: A response (String)

If you cannot manipulate strings—cleaning them, splitting them, formatting them—you cannot build a robust AI agent. You will be stuck with messy data, broken prompts, and unparseable outputs.

In this section, we will master: 1. Comments: How to document code for humans. 2. Variables & Assignment: Creating containers for data. 3. Core Data Types: str, int, float, bool. 4. String Methods: The toolkit for cleaning and shaping text. 5. Conditional Logic: Making decisions based on data.

What You'll Build

By the end of this section, you will have a Prompt Cleaner script. This script will: 1. Take a messy, raw user input string. 2. Clean it (remove extra spaces, fix casing). 3. Check if the input meets specific criteria (e.g., length, keywords). 4. Output a standardized, clean prompt ready for an LLM.

This is the foundation of every production-grade LLM application.

1. Comments: Notes for Humans

Python ignores everything after a # symbol on a line. This is your tool for explaining why you wrote code, not just what the code does.

The Rule

• # starts a comment.
• Everything after # on that line is ignored by the Python interpreter.
• Comments do not affect execution speed or output.

Example

# Save as: comments_demo.py

# This is a single-line comment. Python ignores this.
print("Hello, World!") # This is an inline comment.

# If I comment out code, it does not run.
# print("This will not appear in the output.")

print("This line runs.")

Expected Output:

Hello, World!
This line runs.

✅ Verify: Run the script. Notice that the line print("This will not appear.") did not produce output because it was commented out.

💡 Tip: Use comments to explain complex logic. For example:

# We multiply by 0.7 because the model temperature should be low for factual queries
temperature = 0.7

2. Variables and Assignment

A variable is a named container for a value. You create a variable using the = (assignment) operator.

Syntax

variable_name = value

Rules for Variable Names

1. Must start with a letter or underscore (_).
2. Can contain letters, numbers, and underscores.
3. Case-sensitive (Temperature and temperature are different).
4. Cannot use Python keywords (if, else, for, etc.).

Example

# Save as: variables_demo.py

# Creating variables
temperature = 0.7 # Float
model_name = "gpt-4" # String
max_tokens = 100 # Integer
is_active = True # Boolean

# Printing variables
print(f"Model: {model_name}")
print(f"Temperature: {temperature}")
print(f"Max Tokens: {max_tokens}")
print(f"Active: {is_active}")

Expected Output:

Model: gpt-4
Temperature: 0.7
Max Tokens: 100
Active: True

✅ Verify: Change temperature to 1.5 and re-run. The output should update to 1.5.

3. Core Data Types

Python has four primary data types you will use daily:

Checking Types

Use the type() function to inspect a variable's type.

# Save as: types_demo.py

a = "Hello"
b = 42
c = 3.14
d = True

print(type(a)) # <class'str'>
print(type(b)) # <class 'int'>
print(type(c)) # <class 'float'>
print(type(d)) # <class 'bool'>

Expected Output:

<class'str'>
<class 'int'>
<class 'float'>
<class 'bool'>

⚠️ Warning: In Python, bool is a subclass of int. True equals 1, and False equals 0. This can lead to subtle bugs if you are not careful.

4. String Methods: The LLM Developer's Toolkit

Strings are immutable (cannot be changed after creation). However, Python provides methods that return new strings.

Key Methods

Example: Cleaning a Messy Prompt

# Save as: string_methods_demo.py

# Simulate a messy user input
raw_input = " Explain AI Agent in Simple English "

# Step 1: Remove extra spaces
cleaned = raw_input.strip()
print(f"Cleaned: '{cleaned}'")

# Step 2: Convert to lowercase for consistency
lowercase = cleaned.lower()
print(f"Lowercase: '{lowercase}'")

# Step 3: Replace specific terms
replaced = lowercase.replace("agent", "assistant")
print(f"Replaced: '{replaced}'")

# Step 4: Split into words
words = replaced.split()
print(f"Words: {words}")
print(f"Word Count: {len(words)}")

Expected Output:

Cleaned: 'Explain AI Agent in Simple English'
Lowercase: 'explain ai agent in simple english'
Replaced: 'explain ai assistant in simple english'
Words: ['explain', 'ai', 'assistant', 'in','simple', 'english']
Word Count: 6

✅ Verify: Change raw_input to " Hello, World! ". Notice how .strip() removes the outer spaces but not the inner ones. To remove inner spaces, you would need .split() and .join().

5. Conditional Logic: Making Decisions

LLM applications often need to make decisions: * If the user input is empty, ask for clarification. * If the input contains a question mark, treat it as a query. * If the input is too long, truncate it.

Syntax

if condition:
 # Code to run if condition is True
elif other_condition:
 # Code to run if other_condition is True
else:
 # Code to run if none of the above are True

Example: Prompt Validator

# Save as: prompt_validator.py

def validate_prompt(prompt: str) -> str:
 """
 Validates and cleans a user prompt.
 Returns a standardized prompt string.
 """
 # Step 1: Check if prompt is empty
 if not prompt.strip():
 return "Error: Prompt cannot be empty."

 # Step 2: Clean the prompt
 cleaned = prompt.strip().lower()

 # Step 3: Check length
 if len(cleaned) > 100:
 return "Error: Prompt is too long. Max 100 characters."

 # Step 4: Check for question mark
 if "?" in cleaned:
 return f"Query: {cleaned}"
 else:
 return f"Statement: {cleaned}"

# Test cases
print(validate_prompt(" What is AI? "))
print(validate_prompt("AI is cool"))
print(validate_prompt(" "))
print(validate_prompt("This is a very long prompt that exceeds the limit of one hundred characters for our simple validator"))

Expected Output:

Query: what is ai?
Statement: ai is cool
Error: Prompt cannot be empty.
Error: Prompt is too long. Max 100 characters.

✅ Verify: Add a new test case: print(validate_prompt(" Hello ")). It should return Statement: hello.

6. Combining It All: The Prompt Cleaner

Now, let's build a complete, reusable function that cleans and formats prompts for an LLM.

# Save as: prompt_cleaner.py

def clean_prompt(raw_input: str, max_length: int = 500) -> dict:
 """
 Cleans a raw user input and returns a structured dictionary.

 Args:
 raw_input (str): The raw text from the user.
 max_length (int): Maximum allowed length for the prompt.

 Returns:
 dict: A dictionary with keys 'cleaned', 'valid', 'error'.
 """
 # Initialize result
 result = {
 "cleaned": "",
 "valid": False,
 "error": None
 }

 # Step 1: Strip whitespace
 cleaned = raw_input.strip()

 # Step 2: Check if empty
 if not cleaned:
 result["error"] = "Prompt is empty."
 return result

 # Step 3: Check length
 if len(cleaned) > max_length:
 result["error"] = f"Prompt exceeds max length of {max_length}."
 return result

 # Step 4: Normalize casing (optional, depends on use case)
 # For LLMs, we often keep original casing but remove extra spaces
 cleaned = " ".join(cleaned.split()) # Removes multiple spaces

 # Step 5: Mark as valid
 result["cleaned"] = cleaned
 result["valid"] = True

 return result

# --- Test the Function ---

# Test 1: Valid prompt
test1 = " Explain quantum computing "
result1 = clean_prompt(test1)
print(f"Test 1: {result1}")

# Test 2: Empty prompt
test2 = " "
result2 = clean_prompt(test2)
print(f"Test 2: {result2}")

# Test 3: Too long
test3 = "a" * 600
result3 = clean_prompt(test3)
print(f"Test 3: {result3}")

# Test 4: Normal prompt
test4 = "What is the capital of France?"
result4 = clean_prompt(test4)
print(f"Test 4: {result4}")

Expected Output:

Test 1: {'cleaned': 'Explain quantum computing', 'valid': True, 'error': None}
Test 2: {'cleaned': '', 'valid': False, 'error': 'Prompt is empty.'}
Test 3: {'cleaned': '', 'valid': False, 'error': 'Prompt exceeds max length of 500.'}
Test 4: {'cleaned': 'What is the capital of France?', 'valid': True, 'error': None}

✅ Verify: Change max_length to 10 in the function call for Test 4. It should now return an error.

📁 Project Files

Create a folder named chapter4_data_types and add the following files:

1. comments_demo.py
2. variables_demo.py
3. types_demo.py
4. string_methods_demo.py
5. prompt_validator.py
6. prompt_cleaner.py

🚀 What You Just Built

You have built the foundation of data handling for LLM applications:

1. Comments: You can now document your code for future maintainers.
2. Variables: You can store and manipulate data using Python's core types.
3. String Methods: You can clean, format, and split text—essential for preparing prompts.
4. Conditional Logic: You can validate user input and make decisions based on data.
5. Prompt Cleaner: A reusable function that ensures all prompts sent to an LLM are clean, valid, and within limits.

This is the first step in building a robust AI agent. Without clean data, your LLM will produce inconsistent or incorrect results.

Common Mistakes

1. Forgetting Indentation: python if True: print("Hello") # ❌ IndentationError Fix: Always indent the code block under if, elif, else, for, while, def, class.

2. Using = instead of == in Conditions: python if x = 5: # ❌ SyntaxError Fix: Use == for comparison, = for assignment.

3. Assuming Strings are Mutable: python s = "hello" s[0] = "H" # ❌ TypeError:'str' object does not support item assignment Fix: Create a new string: s = "H" + s[1:].

4. Ignoring Whitespace: python if user_input == "hello": # ❌ Fails if user_input is " hello " Fix: Always use .strip() before comparing strings.

Troubleshooting

Key Takeaways

1. Comments are for humans. Use them to explain why, not what.
2. Variables are containers. Use descriptive names (user_prompt, not x).
3. Strings are the primary data type for LLMs. Master .strip(), .lower(), .split(), and .join().
4. Conditional Logic (if/elif/else) allows you to validate and process data.
5. Always clean user input before sending it to an LLM. This prevents errors and improves consistency.

🧪 Try It Yourself

1. Modify prompt_cleaner.py:
2. Add a check to ensure the prompt contains at least one letter.

3. If it doesn't, return an error: "Prompt must contain at least one letter."

4. Create a New Function:

5. Write a function count_words(prompt: str) -> int that returns the number of words in the prompt.

6. Use .split() and len().

7. Challenge:

8. Modify clean_prompt to remove all punctuation marks (e.g., !, ?, ,, .) from the prompt.

9. Hint: Use a loop and str.replace() or a list of punctuation marks.

10. Debugging Exercise:

11. Intentionally introduce a bug in prompt_validator.py (e.g., change if not prompt.strip(): to if prompt.strip():).
12. Run the code and observe the error.
13. Fix the bug and verify the output is correct.

Next Section

In the next section, we will move from data types to functions and modules. You will learn how to organize your code into reusable functions and how to import external libraries, including the openai library, to start making actual API calls to LLMs.

Chapter 7: Mastering Data Structures & String Manipulation

Why This Matters

In the previous sections, we handled single pieces of data. But real-world AI applications—like LangGraph agents—process collections of data. You might have a list of user queries, a list of tool names, or a list of conversation history items.

If you cannot manipulate lists and format strings dynamically, your code will be brittle and unreadable. This section bridges the gap between "basic variables" and "production-ready data handling." We will focus on: 1. F-Strings: The modern, Pythonic way to format strings. 2. Lists: Storing multiple items in a single variable. 3. Iteration: Processing each item in a list using for loops.

What You'll Build

By the end of this section, you will have a script that: 1. Dynamically formats a user profile using F-strings. 2. Stores a list of skills. 3. Iterates through the list to normalize data (converting to lowercase). 4. Demonstrates common list methods (append, remove, index).

1. F-Strings: Dynamic String Formatting

The Problem

Imagine you have a user named Ishant and a topic LangGraph. You want to print: Hello Ishant, today we are learning LangGraph.

The Old Way (Bad):

print("Hello " + name + ", today we are learning " + topic + ".")

This is hard to read, prone to type errors (if name is an integer, it crashes), and messy.

The Modern Way (F-Strings): F-strings (Formatted String Literals) allow you to embed variable values directly inside string literals by prefixing the string with f and using curly braces {} as placeholders.

Code Example

# Save as: fstring_demo.py

# Define variables
user_name = "Ishant"
topic = "LangGraph"
skill_level = 85

# 1. Basic F-String
message = f"Hello {user_name}, today we are learning {topic}."
print(message)

# 2. F-String with Expressions
# You can do math or logic inside the braces
percentage = f"Your skill level is {skill_level}%."
print(percentage)

# 3. F-String with Method Calls
# You can call methods on the variable inside the braces
upper_name = f"Welcome, {user_name.upper()}!"
print(upper_name)

# 4. What happens if you forget the 'f'?
bad_message = "Hello {user_name}, today we are learning {topic}."
print(bad_message) # This will print the literal text with braces

Expected Output

Hello Ishant, today we are learning LangGraph.
Your skill level is 85%.
Welcome, ISHANT!
Hello {user_name}, today we are learning {topic}.

✅ Verify: Run the script. Notice that the last line prints the literal text {user_name} because the f prefix was missing. This is a common mistake.

💡 Tip: F-strings are faster than % formatting or .format() and are the standard in modern Python (3.6+). Always use them unless you have a specific reason not to.

2. Lists: Storing Multiple Items

The Problem

You have a list of skills: Excel, Python, Communication, Marketing. You want to store them in one variable and process them later.

What is a List?

A list is an ordered, mutable collection of items. It is defined using square brackets []. Items are separated by commas.

Code Example

# Save as: list_basics.py

# 1. Creating a List
skills = ["Excel", "Python", "Communication", "Marketing"]

# 2. Printing the entire list
print("All Skills:", skills)

# 3. Accessing a specific item (Indexing)
# Python uses 0-based indexing
first_skill = skills[0]
last_skill = skills[-1] # Negative index counts from the end
print(f"First Skill: {first_skill}")
print(f"Last Skill: {last_skill}")

# 4. Slicing (Getting a subset)
# Get items from index 1 to 3 (exclusive)
subset = skills[1:3]
print("Subset (Python, Communication):", subset)

Expected Output

All Skills: ['Excel', 'Python', 'Communication', 'Marketing']
First Skill: Excel
Last Skill: Marketing
Subset (Python, Communication): ['Python', 'Communication']

✅ Verify: Check that skills[0] returns "Excel" and skills[-1] returns "Marketing".

3. Iterating Over Lists with for Loops

The Problem

You want to process every item in the list. For example, you want to convert all skill names to lowercase for database storage.

The Solution

Use a for loop to iterate over the list. The loop variable (e.g., skill) takes the value of each item in the list, one by one.

Code Example

# Save as: list_iteration.py

skills = ["Excel", "Python", "Communication", "Marketing"]

print("Processing Skills.")
for skill in skills:
 # Convert to lowercase
 normalized_skill = skill.lower()
 print(f"Original: {skill} -> Normalized: {normalized_skill}")

Expected Output

Processing Skills.
Original: Excel -> Normalized: excel
Original: Python -> Normalized: python
Original: Communication -> Normalized: communication
Original: Marketing -> Normalized: marketing

✅ Verify: Notice that the loop runs 4 times, once for each item in the list. The variable skill is reassigned in each iteration.

4. Common List Methods

Lists are mutable, meaning you can change them after creation. Here are the most common methods you will use in AI agent development.

Code Example

# Save as: list_methods.py

tools = ["search", "calculator", "weather"]

# 1. Append: Add an item to the end
tools.append("email")
print("After append:", tools)

# 2. Remove: Remove the first occurrence of an item
tools.remove("calculator")
print("After remove:", tools)

# 3. Index: Find the position of an item
position = tools.index("weather")
print(f"Position of 'weather': {position}")

# 4. Length: Get the number of items
count = len(tools)
print(f"Total tools: {count}")

# 5. Check if item exists
if "search" in tools:
 print("'search' is available.")
else:
 print("'search' is NOT available.")

Expected Output

After append: ['search', 'calculator', 'weather', 'email']
After remove: ['search', 'weather', 'email']
Position of 'weather': 1
Total tools: 3'search' is available.

✅ Verify: Ensure that remove() does not return the item; it modifies the list in place. Use index() to find positions, but be aware it raises a ValueError if the item is not found.

📁 Project Files

Here is the complete, runnable code combining all concepts. Save this as data_structures_master.py.

# Save as: data_structures_master.py

# ==========================================
# 1. F-STRING DEMO
# ==========================================
print("--- F-String Demo ---")
user_name = "Ishant"
topic = "LangGraph"
skill_level = 85

message = f"Hello {user_name}, today we are learning {topic}."
print(message)

percentage = f"Your skill level is {skill_level}%."
print(percentage)

upper_name = f"Welcome, {user_name.upper()}!"
print(upper_name)

# ==========================================
# 2. LIST BASICS
# ==========================================
print("\n--- List Basics ---")
skills = ["Excel", "Python", "Communication", "Marketing"]

print("All Skills:", skills)
print(f"First Skill: {skills[0]}")
print(f"Last Skill: {skills[-1]}")
print("Subset (Python, Communication):", skills[1:3])

# ==========================================
# 3. ITERATION
# ==========================================
print("\n--- Iteration ---")
print("Processing Skills.")
for skill in skills:
 normalized_skill = skill.lower()
 print(f"Original: {skill} -> Normalized: {normalized_skill}")

# ==========================================
# 4. LIST METHODS
# ==========================================
print("\n--- List Methods ---")
tools = ["search", "calculator", "weather"]

tools.append("email")
print("After append:", tools)

tools.remove("calculator")
print("After remove:", tools)

position = tools.index("weather")
print(f"Position of 'weather': {position}")

count = len(tools)
print(f"Total tools: {count}")

if "search" in tools:
 print("'search' is available.")
else:
 print("'search' is NOT available.")

Expected Output

--- F-String Demo ---
Hello Ishant, today we are learning LangGraph.
Your skill level is 85%.
Welcome, ISHANT!

--- List Basics ---
All Skills: ['Excel', 'Python', 'Communication', 'Marketing']
First Skill: Excel
Last Skill: Marketing
Subset (Python, Communication): ['Python', 'Communication']

--- Iteration ---
Processing Skills.
Original: Excel -> Normalized: excel
Original: Python -> Normalized: python
Original: Communication -> Normalized: communication
Original: Marketing -> Normalized: marketing

--- List Methods ---
After append: ['search', 'calculator', 'weather', 'email']
After remove: ['search', 'weather', 'email']
Position of 'weather': 1
Total tools: 3'search' is available.

✅ Verify: Run the file. The output should match exactly.

🚀 What You Just Built

You have now mastered the two most fundamental data structures in Python: 1. Strings with F-Strings: You can dynamically insert variables, expressions, and method calls into text. This is essential for logging, user interaction, and prompt engineering in AI agents. 2. Lists: You can store multiple items, access them by index, slice them, iterate over them, and modify them using methods like append and remove.

This foundation is critical for LangGraph, where you often pass lists of messages, tool names, or state data between nodes.

Common Mistakes

1. Forgetting the f prefix: ```python # Wrong print("Hello {name}") # Prints literal {name}

# Correct print(f"Hello {name}") # Prints Hello Ishant ```

1. Modifying a list while iterating: ```python # Dangerous! Can skip items or cause errors for item in my_list: if item == "bad": my_list.remove(item)

# Safe: Create a new list new_list = [item for item in my_list if item != "bad"] ```

1. Using == instead of in for list membership: ```python # Wrong if "Python" == skills: # Compares string to list

# Correct if "Python" in skills: # Checks if item exists in list ```

1. Index Error: python skills = ["A", "B"] print(skills[2]) # IndexError: list index out of range

Troubleshooting

Key Takeaways

1. F-Strings are the standard for string formatting. Use f"." with {variable} placeholders.
2. Lists are ordered, mutable collections. Use [] to create them.
3. Indexing is 0-based. list[0] is the first item, list[-1] is the last.
4. Iteration with for item in list: is the most common way to process list items.
5. List Methods: append() adds to the end, remove() deletes the first occurrence, index() finds the position, len() gets the count.

🧪 Try It Yourself

1. Create a list of 5 programming languages.
2. Use an F-string to print a sentence like: "I know {language}." for each language in the list.
3. Add a new language to the list using append().
4. Remove the first language using remove().
5. Print the length of the list.

Expected Result:

languages = ["Python", "Java", "C++", "Go", "Rust"]
for lang in languages:
 print(f"I know {lang}.")

languages.append("Kotlin")
languages.remove("Python")
print(f"Total languages: {len(languages)}")

✅ Verify: The output should show 5 lines of "I know.", then "Total languages: 5".

Chapter 8: Structuring Data with Dictionaries and AI Message Formats

Why This Matters

In the previous sections, we mastered lists and strings. However, lists are ordered and unlabeled. If you have a list like ["Priya", "Marketing", "5 years"], you have to remember that index 0 is the name and index 1 is the role. This is fragile. If you add a new field, everything shifts.

Dictionaries solve this by using Keys and Values. They allow you to store structured information where the data is self-describing.

This is critical for AI Agents because every major LLM API (OpenAI, Anthropic, etc.) expects data in a specific dictionary format. You cannot send a raw string to ChatGPT; you must send a structured list of dictionaries containing role and content.

What You'll Build

1. A basic dictionary to store user profiles.
2. Nested dictionaries (dictionaries inside lists, lists inside dictionaries).
3. The exact Message Structure required to send data to an AI model.
4. A function that formats user input into the AI-ready dictionary format.

1. The Basics: Keys and Values

A dictionary is defined by curly braces {}. Inside, you define key: value pairs separated by commas.

⚠️ Warning: Do not confuse {} in dictionaries with f-strings. In f-strings, {} is a placeholder for variables. In dictionaries, {} defines the container itself.

Code Example: Basic Profile

# Save as: basic_dict.py

# Creating a dictionary
profile = {
 "name": "Priya Sharma",
 "role": "Marketing Executive",
 "experience": 5
}

# Printing the whole dictionary
print("Full Profile:", profile)

# Accessing a specific value using the KEY (not index)
print("Name:", profile["name"])
print("Role:", profile["role"])

# Modifying a value
profile["experience"] = 6
print("Updated Experience:", profile["experience"])

# Adding a new key-value pair
profile["skills"] = ["Content Writing", "SEO", "Analytics"]
print("Skills:", profile["skills"])

Expected Output:

Full Profile: {'name': 'Priya Sharma', 'role': 'Marketing Executive', 'experience': 5}
Name: Priya Sharma
Role: Marketing Executive
Updated Experience: 6
Skills: ['Content Writing','SEO', 'Analytics']

✅ Verify: Run the code. Notice that profile["name"] returns the string directly, whereas profile returns the entire structure.

2. Nested Structures: Lists Inside Dictionaries

Dictionaries are versatile because values can be any data type, including other lists or dictionaries. This is how you store complex data like a list of skills or a history of messages.

Code Example: Nested Data

# Save as: nested_dict.py

user_data = {
 "id": 101,
 "name": "Priya",
 "skills": ["Python", "Excel", "SQL"], # A list inside the dict
 "contact": {
 "email": "priya@example.com",
 "phone": "+91-9999999999" # A dict inside the dict
 }
}

# Accessing a simple value
print("User ID:", user_data["id"])

# Accessing a list inside the dict
print("All Skills:", user_data["skills"])

# Accessing a specific item in the nested list
# Index 0 is the first skill
print("First Skill:", user_data["skills"][0])

# Accessing a value in the nested dictionary
print("Email:", user_data["contact"]["email"])

# 💡 Tip: You can chain accessors, but be careful. 
# If "contact" doesn't exist, this will crash.
# We will learn.get() later to handle this safely.

Expected Output:

User ID: 101
All Skills: ['Python', 'Excel','SQL']
First Skill: Python
Email: priya@example.com

✅ Verify: Ensure you understand the path: user_data -> contact -> email.

3. The AI Message Format (Crucial for Agents)

When you interact with an AI model (like ChatGPT), you are not just sending a string. You are sending a conversation history. The model needs to know who said what.

The standard format is a List of Dictionaries. Each dictionary represents one message in the conversation and must contain two keys: 1. role: Who is speaking? ("system", "user", or "assistant") 2. content: What did they say?

The Three Roles

Code Example: Building an AI Message List

# Save as: ai_message_format.py

# This is the structure you will send to an API
messages = [
 {
 "role": "system",
 "content": "You are a helpful assistant that summarizes resumes."
 },
 {
 "role": "user",
 "content": "Here is my resume: Priya Sharma, Marketing Executive, 5 years experience."
 },
 {
 "role": "assistant",
 "content": "I have received your resume. How can I help you with it?"
 },
 {
 "role": "user",
 "content": "Please summarize my key skills."
 }
]

# Let's inspect the structure
print("Total messages in history:", len(messages))

# Accessing the last user message
last_user_msg = messages[-1]
print("Last Message Role:", last_user_msg["role"])
print("Last Message Content:", last_user_msg["content"])

# Accessing the system prompt
system_prompt = messages[0]
print("System Prompt:", system_prompt["content"])

Expected Output:

Total messages in history: 4
Last Message Role: user
Last Message Content: Please summarize my key skills.
System Prompt: You are a helpful assistant that summarizes resumes.

✅ Verify: This exact structure ([{"role":., "content":.},.]) is what you will pass to openai.chat.completions.create() or similar APIs.

4. Building a Dynamic Message Builder

In a real application, you don't hardcode the messages. You build them dynamically based on user input. Let's write a function that takes a user's question and appends it to the message history.

Code Example: Dynamic Message Builder

# Save as: message_builder.py

def create_initial_messages(system_instruction: str) -> list:
 """
 Creates the initial message list with only the system prompt.
 """
 return [
 {
 "role": "system",
 "content": system_instruction
 }
 ]

def add_user_message(messages: list, user_input: str) -> list:
 """
 Appends a user message to the existing history.
 Returns the updated list.
 """
 new_message = {
 "role": "user",
 "content": user_input
 }
 messages.append(new_message)
 return messages

def add_assistant_message(messages: list, ai_response: str) -> list:
 """
 Appends an assistant message to the existing history.
 Returns the updated list.
 """
 new_message = {
 "role": "assistant",
 "content": ai_response
 }
 messages.append(new_message)
 return messages

# --- Simulation of a Conversation ---

# 1. Initialize with system prompt
history = create_initial_messages("You are a resume expert.")

# 2. User asks a question
user_query = "What is the best format for a resume?"
history = add_user_message(history, user_query)

# 3. AI responds (simulated here, in real life this comes from API)
ai_response = "The best format is a clean, single-column layout with clear headings."
history = add_assistant_message(history, ai_response)

# 4. User asks a follow-up
user_query_2 = "Should I include a photo?"
history = add_user_message(history, user_query_2)

# 5. Print the final structure to see what would be sent to the API
print("Final Message History Structure:")
print("-" * 30)
for i, msg in enumerate(history):
 print(f"Message {i}:")
 print(f" Role: {msg['role']}")
 print(f" Content: {msg['content']}")
 print("-" * 30)

Expected Output:

Final Message History Structure:
------------------------------
Message 0:
 Role: system
 Content: You are a resume expert.
------------------------------
Message 1:
 Role: user
 Content: What is the best format for a resume?
------------------------------
Message 2:
 Role: assistant
 Content: The best format is a clean, single-column layout with clear headings.
------------------------------
Message 3:
 Role: user
 Content: Should I include a photo?
------------------------------

✅ Verify: Notice how the history grows. This is how "memory" works in AI agents. The model sees the entire list to understand context.

5. Safe Access with .get()

What happens if you try to access a key that doesn't exist?

profile = {"name": "Priya"}
print(profile["email"]) # ❌ This will crash with KeyError

In AI applications, data might be missing. Use .get() to provide a default value.

Code Example: Safe Access

# Save as: safe_access.py

profile = {
 "name": "Priya",
 "role": "Marketing"
 # "email" is missing
}

# ❌ Dangerous
# print(profile["email"])

# ✅ Safe
email = profile.get("email", "Not provided")
print("Email:", email)

# If the key exists, it returns the value
name = profile.get("name", "Unknown")
print("Name:", name)

Expected Output:

Email: Not provided
Name: Priya

💡 Tip: Always use .get() when processing external data (like user inputs or API responses) to prevent your agent from crashing.

📁 Project Files

1. basic_dict.py - Basic dictionary creation and access.
2. nested_dict.py - Accessing lists and dicts inside dicts.
3. ai_message_format.py - Understanding the standard AI message structure.
4. message_builder.py - Functions to dynamically build conversation history.
5. safe_access.py - Using .get() to avoid crashes.

🚀 What You Just Built

You now understand how to structure data for AI agents. You can: 1. Create dictionaries to store structured information. 2. Nest lists and dictionaries to handle complex data. 3. Build the exact messages list required by LLM APIs. 4. Safely access data using .get().

This is the foundation for the next chapter, where we will actually send these dictionaries to an AI API.

Common Mistakes

1. Using Indexes Instead of Keys:
2. ❌ profile[0] (Dictionaries are not ordered by index in the same way lists are).

3. ✅ profile["name"]

4. Forgetting the Colon:

5. ❌ {"name" "Priya"}

6. ✅ {"name": "Priya"}

7. Mixing Up Lists and Dicts in AI Format:

8. The top-level structure must be a List.
9. Each element in the list must be a Dictionary.
10. ❌ {"role": "user", "content": "Hi"} (This is just one message, not a conversation).

11. ✅ [{"role": "user", "content": "Hi"}] (This is a list containing one message).

12. Hardcoding Messages:

13. Don't write the message list manually in your main code. Use functions like add_user_message() to keep your code clean and scalable.

Troubleshooting

Key Takeaways

1. Dictionaries use key: value pairs.
2. Keys are unique and usually strings.
3. Values can be any type (string, int, list, dict).
4. AI Message Format is a List of Dictionaries with role and content keys.
5. Use .get() for safe access to avoid crashes.

🧪 Try It Yourself

1. Create a dictionary for a book with keys: title, author, year, genres (list).
2. Write a function add_review(messages, review_text) that appends a user message with the review text.
3. Simulate a conversation where the user asks for a book recommendation, the AI responds, and the user asks for a similar book. Print the final message history.

Next Chapter: We will connect this structured data to an actual AI API and send our first request.

Chapter 5

Talking to an LLM from Python

Why This Matters

Before You Start This Chapter

• Your venv is active (you see `(.

  What is a virtual environment (venv)? It is a separate, isolated Python world for your project. Without it, packages from different projects can conflict. With a venv, each project gets its own clean set of packages. Think of it like a separate browser profile for each website.

venv)in your prompt) - Previous chapter's project is working - Your.env` file has your API key

What is an API? An API (Application Programming Interface) is how one program talks to another. Think of it like a waiter in a restaurant — you (your code) tell the waiter (API) what you want, the waiter goes to the kitchen (the server), and brings back your food (the response). You never talk to the kitchen directly.

• You are in the correct folder (run pwd to check)

Get Your OpenAI API Key

1. Go to https://platform.openai.com/api-keys
2. Log in (free account)
3. Click "Create new secret key"
4. Name it (e.g., "adhikk")
5. Click "Create"
6. Copy the key (starts with sk-) — you will not see it again
7. Paste into your .env file

New accounts get $5 free credit — enough for this entire book.

Create & Activate Virtual Environment

uv venv

Activate (Windows PowerShell):

.venv\Scripts\Activate

Activate (Mac/Linux):

source .venv/bin/activate

How you'll know it worked: Your prompt shows (.venv) at the start.

Install Python (if not already installed)

1. Go to https://www.python.org/downloads/
2. Click "Download Python 3.12.x"
3. Run the installer

4. CHECK the box: Add python.exe to PATH

   What is PATH? PATH is a list of folders your computer checks when you type a command. If you type python, your computer looks in each PATH folder for a file called python.exe. If it finds it, it runs it. If not, you get "command not found." Installing Python with "Add to PATH" checked adds Python's folder to this list.

5. Click "Install Now"

6. Close and reopen your terminal

Verify:

python --version

Expected output:

Python 3.12.x

Functions are the building blocks of reusable and maintainable code. Imports let you tap into the massive ecosystem of third‑party libraries—​from data‑wrangling with pandas to visualisation with matplotlib. Mastering these concepts is the first step toward writing production‑grade Python for AI agents, data science, and any real‑world project.

What You’ll Build

By the end of this chapter you will have a single, runnable script that:

1. Defines several simple functions (greet, summarise_profile, add_numbers).
2. Imports and uses pandas to create a DataFrame from a dictionary.
3. Adds a computed column (final_score).
4. Classifies rows with a lambda function (level).
5. Filters the DataFrame and exports the result to a CSV file.

All of this will run out‑of‑the‑box after installing the dependencies listed in requirements.txt.

Content

1️⃣ Defining & Calling Functions

# Save as: functions_demo.py
def greet(name: str) -> str:
 """Return a friendly greeting."""
 return f"Hello {name}, welcome to AI agents."

def summarise_profile(name: str, role: str, skill: str) -> str:
 """Create a one‑line profile summary."""
 return f"{name} is a {role} who is skilled in {skill}."

def add_numbers(a: int, b: int) -> int:
 """Return the sum of two numbers."""
 return a + b

# Demonstration
if __name__ == "__main__":
 message = greet("Priya")
 print(message) # 👉 Hello Priya, welcome to AI agents.

 profile = summarise_profile("Rohan", "Data Analyst", "Python")
 print(profile) # 👉 Rohan is a Data Analyst who is skilled in Python.

 result = add_numbers(10, 25)
 print(f"The sum is {result}") # 👉 The sum is 35

Expected output

Hello Priya, welcome to AI agents.
Rohan is a Data Analyst who is skilled in Python.
The sum is 35

✅ Verify: Run python functions_demo.py and confirm the three lines above appear.

2️⃣ Importing Libraries

# Save as: imports_demo.py
import os # Standard library – file‑system utilities
import pandas as pd # Third‑party – data manipulation
import matplotlib.pyplot as plt # Third‑party – plotting (optional for this chapter)

print("Modules imported successfully!")

Expected output

Modules imported successfully!

✅ Verify: Execute python imports_demo.py. If you see the message, the imports work. ⚠️ If you get ModuleNotFoundError for pandas or matplotlib, install the dependencies (see requirements.txt).

3️⃣ Working with Pandas

# Save as: pandas_demo.py
import pandas as pd

# 1️⃣ Create a dictionary that mimics an Excel sheet
students = {
 "name": ["Alice", "Bob", "Charlie", "Diana"],
 "score": [88, 92, 67, 79],
 "hours": [10, 12, 8, 9]
}

# 2️⃣ Convert the dictionary to a DataFrame (think of it as an Excel table)
df = pd.DataFrame(students)
print("Initial DataFrame:")
print(df)

# 3️⃣ Add a computed column: final_score = score + 0.5 * hours
df["final_score"] = df["score"] + 0.5 * df["hours"]
print("\nAfter adding `final_score` column:")
print(df)

# 4️⃣ Classify each student as 'advanced' or 'beginner' using a lambda
df["level"] = df["final_score"].apply(lambda x: "advanced" if x >= 90 else "beginner")
print("\nAfter adding `level` column:")
print(df)

# 5️⃣ Filter rows where final_score >= 75
filtered = df[df["final_score"] >= 75]
print("\nStudents with final_score >= 75:")
print(filtered)

# 6️⃣ Export the filtered DataFrame to CSV
filtered.to_csv("filtered_students.csv", index=False)
print("\nFiltered data saved to `filtered_students.csv`")

Expected output

Initial DataFrame:
 name score hours
0 Alice 88 10
1 Bob 92 12
2 Charlie 67 8
3 Diana 79 9

After adding `final_score` column:
 name score hours final_score
0 Alice 88 10 93.0
1 Bob 92 12 98.0
2 Charlie 67 8 71.0
3 Diana 79 9 83.5

After adding `level` column:
 name score hours final_score level
0 Alice 88 10 93.0 advanced
1 Bob 92 12 98.0 advanced
2 Charlie 67 8 71.0 beginner
3 Diana 79 9 83.5 beginner

Students with final_score >= 75:
 name score hours final_score level
0 Alice 88 10 93.0 advanced
1 Bob 92 12 98.0 advanced
3 Diana 79 9 83.5 beginner

Filtered data saved to `filtered_students.csv`

✅ Verify: Run python pandas_demo.py. 💡 Open filtered_students.csv with any spreadsheet program to see the same rows.

4️⃣ Putting It All Together

# Save as: main.py
import pandas as pd

# ---------- Functions ----------
def greet(name: str) -> str:
 return f"Hello {name}, welcome to AI agents."

def summarise_profile(name: str, role: str, skill: str) -> str:
 return f"{name} is a {role} who is skilled in {skill}."

def add_numbers(a: int, b: int) -> int:
 return a + b

# ---------- Data Processing ----------
def build_student_dataframe() -> pd.DataFrame:
 students = {
 "name": ["Alice", "Bob", "Charlie", "Diana"],
 "score": [88, 92, 67, 79],
 "hours": [10, 12, 8, 9]
 }
 df = pd.DataFrame(students)
 df["final_score"] = df["score"] + 0.5 * df["hours"]
 df["level"] = df["final_score"].apply(lambda x: "advanced" if x >= 90 else "beginner")
 return df

def filter_and_save(df: pd.DataFrame, threshold: float = 75.0, filename: str = "filtered_students.csv"):
 filtered = df[df["final_score"] >= threshold]
 filtered.to_csv(filename, index=False)
 return filtered

# ---------- Main Execution ----------
if __name__ == "__main__":
 # Function demos
 print(greet("Priya"))
 print(summarise_profile("Rohan", "Data Analyst", "Python"))
 print(f"The sum of 10 and 25 is {add_numbers(10, 25)}\n")

 # DataFrame workflow
 df = build_student_dataframe()
 print("Full DataFrame:")
 print(df, "\n")

 filtered_df = filter_and_save(df)
 print("Filtered DataFrame (saved to CSV):")
 print(filtered_df)

Expected output

Hello Priya, welcome to AI agents.
Rohan is a Data Analyst who is skilled in Python.
The sum of 10 and 25 is 35

Full DataFrame:
 name score hours final_score level
0 Alice 88 10 93.0 advanced
1 Bob 92 12 98.0 advanced
2 Charlie 67 8 71.0 beginner
3 Diana 79 9 83.5 beginner 

Filtered DataFrame (saved to CSV):
 name score hours final_score level
0 Alice 88 10 93.0 advanced
1 Bob 92 12 98.0 advanced
3 Diana 79 9 83.5 beginner

✅ Verify: Run python main.py. A file named filtered_students.csv should appear in the same directory.

📁 Project Files

# Save as: requirements.txt
pandas==2.2.2
matplotlib==3.9.0

Tip: The exact version numbers are optional; you can use pandas and matplotlib without specifying a version if you prefer the latest releases.

🚀 What You Just Built

• Reusable functions that encapsulate logic.
• Modular code that can be imported elsewhere.
• A pandas DataFrame built from a Python dictionary.
• Computed columns (final_score) and categorical labeling (level) using apply + lambda.
• Filtering based on a numeric threshold.
• CSV export for downstream consumption (e.g., Excel, BI tools).

All of this is ready to be extended—add more columns, visualise with matplotlib, or plug into an AI‑agent pipeline.

Common Mistakes

Troubleshooting

1. ModuleNotFoundError: No module named 'pandas'

2. Run pip install -r requirements.txt inside your activated virtual environment.

3. SettingWithCopyWarning when adding a column after filtering

4. Use df = df.copy() after the filter, or assign with .loc[:, "col"] =..

5. CSV file is empty

6. Verify that the filter condition actually matches rows (df["final_score"] >= 75).

7. Unexpected data types (e.g., strings instead of numbers)

8. Ensure the dictionary values are numeric (int or float). Use pd.to_numeric if needed.

Key Takeaways

• Functions let you write code once and reuse it everywhere.
• Imports give you instant access to a massive ecosystem; never reinvent the wheel.
• Pandas turns plain Python data structures into powerful, spreadsheet‑like tables.
• Lambda + apply is a concise way to create derived columns.
• Filtering and exporting are essential for real‑world data pipelines.

Master these fundamentals, and you’ll be ready to build more sophisticated AI agents, data pipelines, and production services.

🧪 Try It Yourself

1. Extend students with a new column attendance (percentage).
2. Update final_score to also factor in attendance (e.g., + 0.2 * attendance).
3. Add a new classification: "expert" if final_score >= 95.
4. Plot a bar chart of final_score per student using matplotlib (optional).

# Save as: challenge.py
import pandas as pd
import matplotlib.pyplot as plt

students = {
 "name": ["Alice", "Bob", "Charlie", "Diana"],
 "score": [88, 92, 67, 79],
 "hours": [10, 12, 8, 9],
 "attendance": [95, 88, 70, 80] # <-- new data
}

df = pd.DataFrame(students)
df["final_score"] = df["score"] + 0.5 * df["hours"] + 0.2 * df["attendance"]
df["level"] = df["final_score"].apply(
 lambda x: "expert" if x >= 95 else ("advanced" if x >= 90 else "beginner")
)

print(df)

# Optional visualisation
df.plot.bar(x="name", y="final_score", legend=False, title="Final Scores")
plt.ylabel("Score")
plt.tight_layout()
plt.show()

Run python challenge.py. Verify that the new column appears, the classification updates, and (if you kept the plot code) a bar chart pops up.

Happy coding! 🚀

Why This Matters

Modern applications rarely live in isolation. They talk to other services—whether it’s a payment gateway, a weather API, or a large language model (LLM) like OpenAI’s ChatGPT. Understanding how to securely store credentials, load them at runtime, and wrap API calls in clean, reusable code is a core skill for any production‑grade Python developer.

What You'll Build

In this section you will create a tiny, production‑ready wrapper around the OpenAI Chat Completion API:

By the end of the chapter you will have a stand‑alone script (app.py) that you can run without any extra research.

Content

1️⃣ Set Up the Project Skeleton

Create a fresh folder for the demo (e.g., openai_demo). Inside it, add the following files:

2️⃣ Install Dependencies

# From the project root
python -m venv.venv
source.venv/bin/activate # Windows:.venv\Scripts\activate
pip install -r requirements.txt

✅ Verify:

Successfully installed openai python-dotenv

3️⃣ Create the .env File

⚠️ Never push this file to a public repository. Add it to .gitignore.

# Save as:.env
OPENAI_API_KEY="sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

💡 Tip: If you don’t have an API key yet, generate one at https://platform.openai.com/account/api-keys.

4️⃣ Write requirements.txt

# Save as: requirements.txt
openai>=1.0.0
python-dotenv>=1.0.0

5️⃣ Build the Wrapper – openai_client.py

# Save as: openai_client.py
import os
from typing import List, Dict, Any

import openai
from dotenv import load_dotenv

# Load environment variables from.env (if present)
load_dotenv()

class OpenAIClient:
 """
 A thin wrapper around the OpenAI Chat Completion API.
 Keeps credential handling, model selection, and request formatting in one place.
 """

 def __init__(self, model: str = "gpt-4o-mini"):
 """
 Initialise the client.

 Parameters
 ----------
 model: str
 The model name to use for completions. Defaults to the cheap, fast `gpt-4o-mini`.
 """
 api_key = os.getenv("OPENAI_API_KEY")
 if not api_key:
 raise RuntimeError(
 "OPENAI_API_KEY not found. Set it in a.env file or export it in your shell."
 )
 openai.api_key = api_key
 self.model = model

 def chat(
 self,
 messages: List[Dict[str, str]],
 temperature: float = 0.7,
 max_tokens: int = 500,
 ) -> str:
 """
 Send a list of messages to the model and return the assistant's reply.

 Parameters
 ----------
 messages: List[Dict[str, str]]
 Conversation history. Each dict must have a ``role`` (system|user|assistant)
 and a ``content`` field.
 temperature: float
 Controls randomness. 0 = deterministic, 1 = very creative.
 max_tokens: int
 Upper bound on the number of tokens in the response.

 Returns
 -------
 str
 The assistant's generated text.
 """
 response = openai.ChatCompletion.create(
 model=self.model,
 messages=messages,
 temperature=temperature,
 max_tokens=max_tokens,
 )
 # The response schema is stable across SDK versions:
 # response.choices[0].message.content holds the text.
 return response.choices[0].message.content.strip()

✅ Verify:

python -c "import openai_client; print('Wrapper imported successfully')"

Expected output:

Wrapper imported successfully

6️⃣ CLI Demo – app.py

# Save as: app.py
import sys
from getpass import getpass

from openai_client import OpenAIClient


def main() -> None:
 """
 Simple command‑line interface that asks the user for a prompt,
 sends it to the OpenAI model, and prints the response.
 """
 # Optional: allow the user to override the model via an env var or CLI arg
 model = os.getenv("OPENAI_MODEL", "gpt-4o-mini")
 client = OpenAIClient(model=model)

 # Gather a prompt from the user. Using getpass hides the input on the terminal,
 # which is handy if you ever want to type a secret (not required here).
 prompt = input("🗣️ Enter your question for the LLM: ").strip()
 if not prompt:
 print("❌ No prompt provided – exiting.")
 sys.exit(1)

 # Build the message list expected by the API
 messages = [
 {"role": "system", "content": "You are a helpful, concise assistant."},
 {"role": "user", "content": prompt},
 ]

 try:
 answer = client.chat(messages)
 print("\n🤖 Model response:\n")
 print(answer)
 except Exception as exc:
 print(f"❌ An error occurred while contacting the API: {exc}")
 sys.exit(1)


if __name__ == "__main__":
 main()

✅ Verify: Run the script

python app.py

Sample interaction

🗣️ Enter your question for the LLM: What is the capital of France?

🤖 Model response:

Paris

7️⃣ (Optional) Add a Quick Test – test_openai_client.py

# Save as: test_openai_client.py
import os
from unittest.mock import patch, MagicMock

import pytest

from openai_client import OpenAIClient


@pytest.fixture
def dummy_key(monkeypatch):
 monkeypatch.setenv("OPENAI_API_KEY", "test-key")


def test_client_initialises_with_key(dummy_key):
 client = OpenAIClient()
 assert client.model == "gpt-4o-mini"


@patch("openai.ChatCompletion.create")
def test_chat_returns_content(mock_create, dummy_key):
 # Mock the OpenAI response structure
 mock_create.return_value = MagicMock(
 choices=[MagicMock(message=MagicMock(content="Mocked answer"))]
 )
 client = OpenAIClient()
 answer = client.chat([{"role": "user", "content": "Hello"}])
 assert answer == "Mocked answer"
 mock_create.assert_called_once()

Run the test:

pytest -q

Expected output:

```. [100%] 2 passed in 0.12s

---

## 📁 Project Files

openai_demo/ ├─.env # ← secret key (never commit) ├─ requirements.txt ├─ openai_client.py ├─ app.py └─ test_openai_client.py # optional, for CI pipelines

---

## 🚀 What You Just Built
- **Secure credential loading** via `python-dotenv` and `os.getenv`.
- **Reusable, typed wrapper** (`OpenAIClient`) that abstracts the raw SDK.
- **Command‑line demo** that shows a real‑world interaction with an LLM.
- **Skeleton for unit testing** using `unittest.mock` (critical for CI).

All of this is ready to be dropped into a larger codebase or used as a template for other APIs.

---

## Common Mistakes 

| Mistake | Why it Happens | Fix |
|---------|----------------|-----|
| Forgetting to **activate the virtual environment** before installing packages. | The system Python may not have the required libs. | Run `source.venv/bin/activate` (or the Windows equivalent) each time you open a new terminal. |
| **Hard‑coding** the API key in source files. | Easy to commit accidentally. | Keep the key only in `.env` and load it with `dotenv`. |
| Using the **wrong model name** (`gpt‑4o‑mini` vs `gpt‑4o-mini`). | Typos cause a 404 from the API. | Copy the model identifier directly from the OpenAI docs. |
| Not handling **network errors**. | API calls can fail (rate limits, timeouts). | Wrap the call in `try/except` and surface a friendly message (as shown in `app.py`). |
| Running the script **without the `.env` file**. | `os.getenv` returns `None`, raising `RuntimeError`. | Ensure `.env` exists or export `OPENAI_API_KEY` in the shell. |

---

## Troubleshooting 

| Symptom | Likely Cause | Remedy |
|---------|--------------|--------|
| `RuntimeError: OPENAI_API_KEY not found` | `.env` missing or not loaded. | Verify `.env` exists, run `load_dotenv()` before creating the client, or export the variable manually. |
| `openai.error.AuthenticationError` | Wrong or expired key. | Regenerate the key on the OpenAI portal and update `.env`. |
| `openai.error.RateLimitError` | Too many requests in a short period. | Add exponential back‑off or request a higher quota. |
| `ImportError: No module named 'dotenv'` | Dependency not installed. | Run `pip install -r requirements.txt` inside the activated venv. |
| Empty response from the model | `temperature` set to 0 and prompt ambiguous. | Adjust the prompt or increase `temperature`. |

---

## Key Takeaways 

1. **Never store secrets in code** – use environment variables and `.env` files. 
2. **Encapsulate third‑party SDK calls** in a small, well‑documented class. 
3. **Graceful error handling** makes your CLI robust and user‑friendly. 
4. **Unit‑testable design** (dependency injection, mocking) prepares you for production pipelines. 

---

## 🧪 Try It Yourself 

1. **Swap models** – change `OPENAI_MODEL` in the environment to `"gpt-4o"` and observe the difference in response quality and latency. 
2. **Add system messages** – prepend a custom instruction (e.g., “Speak like a pirate”) and see how the model adapts. 
3. **Create a batch script** that reads prompts from a CSV file, calls `OpenAIClient.chat` for each row, and writes the answers back to a new CSV. 

Happy coding! 🚀

## Why This Matters
AI agents are becoming the backbone of modern applications—think personal tutors, code assistants, or customer‑service bots. Being able to **switch seamlessly between providers** (OpenAI, Gemini, etc.) gives you flexibility, cost control, and resilience against service outages. This chapter shows you how to wrap multiple LLM APIs behind a single, clean Python function.

## What You'll Build
A tiny yet powerful library:

* **`ask_openai(prompt, **kwargs)`** – Calls OpenAI’s ChatCompletion.
* **`ask_gemini(prompt, **kwargs)`** – Calls Google Gemini.
* **`ask_llm(prompt, provider="openai", **kwargs)`** – A unified interface that picks the right backend.
* Example scripts that request concise answers (token‑efficient) for different user groups.
> **What is a token?** A token is how AI models count text. Think of it as a "word piece" — roughly 3-4 characters. "Hello" = 1 token. "Hello world" = 2 tokens. Models have a limit on how many tokens they can process at once (called the "context window").



## Content
1. **Setup** – Install dependencies, store API keys safely. 
2. **Provider wrappers** – Minimal code to talk to each service. 
3. **Unified dispatcher** – `ask_llm` decides which wrapper to invoke. 
4. **Demo usage** – One‑liner queries for students, professionals, and prompt‑engineering. 
5. **Running the demo** – Expected console output.

---

## 📁 Project Files

### 1️⃣ `config.py` – Centralised configuration 
```python
# Save as: config.py
import os
from pathlib import Path
from dotenv import load_dotenv

# Load.env file located at the project root
env_path = Path(__file__).parent / ".env"
load_dotenv(dotenv_path=env_path)

# ----------------------------------------------------------------------
# API Keys – keep them out of source control!
# ----------------------------------------------------------------------
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")

# Default model identifiers
OPENAI_MODEL = "gpt-3.5-turbo"
GEMINI_MODEL = "gemini-1.5-flash"

2️⃣ llm_wrappers.py – Provider‑specific helpers

# Save as: llm_wrappers.py
import json
import logging
from typing import Any, Dict

import openai
import google.generativeai as genai

from config import OPENAI_API_KEY, GEMINI_API_KEY, OPENAI_MODEL, GEMINI_MODEL

# ----------------------------------------------------------------------
# Initialise clients
# ----------------------------------------------------------------------
openai.api_key = OPENAI_API_KEY
genai.configure(api_key=GEMINI_API_KEY)

logger = logging.getLogger(__name__)

def _extract_openai_text(response: Dict[str, Any]) -> str:
 """Extract the assistant's reply from OpenAI's response."""
 try:
 return response["choices"][0]["message"]["content"].strip()
 except (KeyError, IndexError) as exc:
 logger.error("Unexpected OpenAI response shape: %s", json.dumps(response))
 raise exc

def _extract_gemini_text(response: Any) -> str:
 """Gemini returns a `GenerateContentResponse`; we need `text`."""
 try:
 # `text` may be a list of parts; join them.
 return "".join(part.text for part in response.candidates[0].content.parts).strip()
 except Exception as exc:
 logger.error("Failed to parse Gemini response.")
 raise exc

def ask_openai(prompt: str, max_tokens: int = 150, temperature: float = 0.7) -> str:
 """
 Send a prompt to OpenAI's ChatCompletion endpoint.
 Returns the raw text answer.
 """
 response = openai.ChatCompletion.create(
 model=OPENAI_MODEL,
 messages=[{"role": "user", "content": prompt}],
 max_tokens=max_tokens,
 temperature=temperature,
 )
 return _extract_openai_text(response)

def ask_gemini(prompt: str, max_output_tokens: int = 150, temperature: float = 0.7) -> str:
 """
 Send a prompt to Google Gemini.
 Returns the raw text answer.
 """
 model = genai.GenerativeModel(GEMINI_MODEL)
 response = model.generate_content(
 prompt,
 generation_config=genai.types.GenerationConfig(
 max_output_tokens=max_output_tokens,
 temperature=temperature,
 ),
 )
 return _extract_gemini_text(response)

3️⃣ ask_llm.py – Unified dispatcher

# Save as: ask_llm.py
from typing import Literal

from llm_wrappers import ask_openai, ask_gemini

Provider = Literal["openai", "gemini"]

def ask_llm(
 prompt: str,
 provider: Provider = "openai",
 *,
 max_tokens: int = 150,
 temperature: float = 0.7,
) -> str:
 """
 One‑stop function to query either OpenAI or Gemini.

 Parameters
 ----------
 prompt: str
 The user query.
 provider: {"openai", "gemini"}
 Which backend to use.
 max_tokens: int
 Upper bound on the generated token count (helps keep costs low).
 temperature: float
 Controls randomness; 0 = deterministic, 1 = very creative.

 Returns
 -------
 str
 The model's raw textual answer.
 """
 if provider == "openai":
 return ask_openai(prompt, max_tokens=max_tokens, temperature=temperature)
 elif provider == "gemini":
 return ask_gemini(prompt, max_output_tokens=max_tokens, temperature=temperature)
 else:
 raise ValueError(f"Unsupported provider: {provider!r}")

4️⃣ demo.py – Putting it all together

# Save as: demo.py
import textwrap

from ask_llm import ask_llm

def print_section(title: str, answer: str) -> None:
 """Pretty‑print a demo section."""
 separator = "=" * len(title)
 print(f"\n{title}\n{separator}\n{answer}\n")

def main() -> None:
 # 1️⃣ One‑line use case for a student (OpenAI)
 student_prompt = (
 "Give one concise use case of an AI agent for a student, in one sentence."
 )
 student_answer = ask_llm(student_prompt, provider="openai", max_tokens=30)
 print_section("Student Use‑Case (OpenAI)", student_answer)

 # 2️⃣ One‑line use case for a working professional (Gemini)
 professional_prompt = (
 "Give one concise use case of an AI agent for a working professional, in one sentence."
 )
 professional_answer = ask_llm(professional_prompt, provider="gemini", max_tokens=30)
 print_section("Professional Use‑Case (Gemini)", professional_answer)

 # 3️⃣ Prompt‑engineering definition (OpenAI, very short)
 pe_prompt = "Explain prompt engineering in one line."
 pe_answer = ask_llm(pe_prompt, provider="openai", max_tokens=20)
 print_section("Prompt Engineering (OpenAI)", pe_answer)

if __name__ == "__main__":
 main()

Expected console output (your exact wording may vary slightly depending on the model’s current knowledge):

Student Use‑Case (OpenAI)
=========================
An AI agent can act as a personalized tutor that explains concepts and generates practice quizzes on demand.

Professional Use‑Case (Gemini)
=============================
An AI agent can serve as a smart meeting assistant that summarizes discussions and drafts follow‑up emails.

Prompt Engineering (OpenAI)
===========================
Prompt engineering is the craft of designing inputs that guide LLMs to produce the desired output.

✅ Verify: Run python demo.py after setting the environment variables (see below). You should see three sections printed exactly as shown.

🚀 What You Just Built

Common Mistakes

Troubleshooting

Key Takeaways

• Abstraction matters – A thin dispatcher (ask_llm) gives you the freedom to swap providers without touching the rest of your code.
• Control cost – max_tokens caps spend and forces the model to be concise.
• Keep secrets out of code – Use environment variables (python-dotenv) for API keys.
• Modular design – Adding a new LLM is a matter of a few lines, not a rewrite.

🧪 Try It Yourself

1. Create a .env file in the project root:

dotenv OPENAI_API_KEY=sk-. GEMINI_API_KEY=AIza.

1. Install dependencies:

bash pip install openai google-generativeai python-dotenv

1. Run the demo:

bash python demo.py

1. Extend the library:
2. Add a wrapper for Anthropic’s Claude.
3. Implement a caching layer (e.g., functools.lru_cache) to avoid duplicate calls.
4. Build a tiny Flask API that exposes ask_llm over HTTP.

💡 Tip: When you start building a UI, keep the ask_llm signature unchanged; the UI layer can pass provider="openai" or "gemini" based on user preference.

⚠️ Warning: Never commit your .env file to version control. Add it to .gitignore immediately.

Happy coding! 🎉

What's Next

Continue to the next chapter to keep building.

Chapter 6

From LLM to Agent

Why This Matters

Activate Your Virtual Environment

If you have not activated your venv yet (check: do you see (.venv) in your prompt?):

Windows PowerShell:

   .venv\Scripts\Activate

Mac/Linux:

   source .venv/bin/activate

Expected: Your prompt now starts with (.venv).

Before You Start This Chapter

• Your venv is active (you see `(.

  What is a virtual environment (venv)? It is a separate, isolated Python world for your project. Without it, packages from different projects can conflict. With a venv, each project gets its own clean set of packages. Think of it like a separate browser profile for each website.

venv)in your prompt) - Previous chapter's project is working - Your.env` file has your API key

What is an API? An API (Application Programming Interface) is how one program talks to another. Think of it like a waiter in a restaurant — you (your code) tell the waiter (API) what you want, the waiter goes to the kitchen (the server), and brings back your food (the response). You never talk to the kitchen directly.

• You are in the correct folder (run pwd to check)

Get Your OpenAI API Key

1. Go to https://platform.openai.com/api-keys
2. Log in (free account)
3. Click "Create new secret key"
4. Name it (e.g., "adhikk")
5. Click "Create"
6. Copy the key (starts with sk-) — you will not see it again
7. Paste into your .env file

New accounts get $5 free credit — enough for this entire book.

Large Language Models (LLMs) are the engine behind every modern AI‑powered chat, code‑assistant, and autonomous agent you see today. Understanding what an LLM is, how it “remembers”, and how to shape its behavior with a context window is the foundation for building any AI system—whether the next framework you use is open‑source or a proprietary cloud service. Master these concepts now, and you’ll never be caught off‑guard by a new model release.

What You’ll Build

In this chapter you will create a minimal, production‑ready chat agent that:

1. Sets a system prompt (the “role” you want the model to play).

2. Manages the context window so the conversation never exceeds the model’s token limit.

   What is a token? A token is how AI models count text. Think of it as a "word piece" — roughly 3-4 characters. "Hello" = 1 token. "Hello world" = 2 tokens. Models have a limit on how many tokens they can process at once (called the "context window").

3. Counts tokens with the tiktoken library and truncates older messages when needed.

4. Runs locally with a single Python file and a tiny helper module—no extra research required.

By the end you’ll have a reusable skeleton you can plug into any LLM (OpenAI, Anthropic, Cohere, etc.) and extend into a full‑blown AI agent.

Content

1. LLM Basics

2. Tokens & Context Window

• Token ≈ word (but not exactly; punctuation and sub‑words count too).
• Example: "My name is Ishant." → 5 tokens.
• A model with a 4,096‑token window can handle roughly 2,000 words of input plus the model’s response.

💡 Tip: Use the tiktoken library to count tokens precisely; this avoids “Token limit exceeded” errors at runtime.

3. Prompt Engineering

A good prompt is a concatenation of messages:

[
 {"role": "system", "content": "You are a helpful AI assistant."},
 {"role": "user", "content": "What is the capital of France?"},
 {"role": "assistant", "content": "Paris."}
]

The system message stays at the top of the context window and never gets trimmed—think of it as the “desk” that always holds your instructions.

4. Building a Simple Chat Agent

We’ll write two files:

1. utils.py – token counting & truncation helpers.
2. chat_agent.py – the interactive loop that talks to the LLM.

Both files are fully runnable; just install the dependencies listed in the Project Files section.

📁 Project Files

utils.py

# Save as: utils.py
"""
Utility functions for token counting and context‑window management.
Works with any OpenAI‑compatible model.
"""

import tiktoken
from typing import List, Dict

def num_tokens_from_messages(messages: List[Dict[str, str]], model: str = "gpt-3.5-turbo") -> int:
 """
 Returns the number of tokens used by a list of messages.
 Mirrors the counting logic used by OpenAI's API.
 """
 try:
 encoding = tiktoken.encoding_for_model(model)
 except KeyError:
 encoding = tiktoken.get_encoding("cl100k_base")

 # Every message follows <im_start>{role/name}\n{content}<im_end>\n
 tokens_per_message = 4 # every message has 4 tokens of overhead
 tokens_per_name = -1 # if a name is present, we subtract 1 token

 num_tokens = 0
 for message in messages:
 num_tokens += tokens_per_message
 for key, value in message.items():
 num_tokens += len(encoding.encode(value))
 if key == "name":
 num_tokens += tokens_per_name
 num_tokens += 2 # every reply is primed with <im_start>assistant
 return num_tokens

def trim_messages(messages: List[Dict[str, str]],
 max_tokens: int,
 model: str = "gpt-3.5-turbo") -> List[Dict[str, str]]:
 """
 Trims the oldest *user/assistant* messages until the total token count
 fits within `max_tokens`. The system message (first entry) is never removed.
 """
 if not messages:
 return messages

 # Preserve the system message
 system_msg = messages[0]
 convo = messages[1:]

 while convo and num_tokens_from_messages([system_msg] + convo, model) > max_tokens:
 # Remove the oldest user‑assistant pair
 convo = convo[2:] # assumes messages alternate user/assistant
 return [system_msg] + convo

Expected output (when imported): No output; the module simply defines functions.

✅ Verify: Run python -c "import utils; print(utils.num_tokens_from_messages([{'role':'system','content':'You are a bot.'}]))" – it should print an integer (e.g., 7).

chat_agent.py

# Save as: chat_agent.py
"""
A minimal interactive chat agent that:
- Sets a system prompt (role definition)
- Keeps the conversation inside the model's context window
- Demonstrates token counting and automatic truncation
"""

import os
import sys
import json
import openai
from utils import num_tokens_from_messages, trim_messages

# ------------------------------------------------------------
# Configuration – replace with your own API key or set env var
# ------------------------------------------------------------
openai.api_key = os.getenv("OPENAI_API_KEY") # ⚠️ Ensure this env var is set

MODEL_NAME = "gpt-3.5-turbo"
MAX_TOKENS = 4096 # Model's context window
RESERVED_FOR_RESPONSE = 500 # Tokens we keep for the model's reply

SYSTEM_PROMPT = (
 "You are a professional sales assistant. "
 "Answer concisely, stay friendly, and always ask a clarifying question "
 "if the user's request is ambiguous."
)

def build_initial_messages() -> list:
 """Create the initial message list with the immutable system prompt."""
 return [{"role": "system", "content": SYSTEM_PROMPT}]

def chat_loop():
 messages = build_initial_messages()
 print("\n🤖 AI Sales Assistant – type 'exit' to quit.\n")
 while True:
 user_input = input("You: ").strip()
 if user_input.lower() in {"exit", "quit"}:
 print("👋 Goodbye!")
 break

 # Append user message
 messages.append({"role": "user", "content": user_input})

 # Ensure we stay within the context window
 max_allowed = MAX_TOKENS - RESERVED_FOR_RESPONSE
 if num_tokens_from_messages(messages, MODEL_NAME) > max_allowed:
 messages = trim_messages(messages, max_allowed, MODEL_NAME)

 # Call the OpenAI chat completion endpoint
 try:
 response = openai.ChatCompletion.create(
 model=MODEL_NAME,
 messages=messages,
 temperature=0.7,
 max_tokens=RESERVED_FOR_RESPONSE,
 n=1,
 stop=None,
 )
 except openai.error.OpenAIError as e:
 print(f"⚠️ API error: {e}")
 continue

 assistant_msg = response.choices[0].message["content"].strip()
 print(f"Assistant: {assistant_msg}\n")

 # Store assistant reply for future context
 messages.append({"role": "assistant", "content": assistant_msg})

if __name__ == "__main__":
 # Simple sanity check for the API key
 if not openai.api_key:
 sys.exit("⚠️ Please set the OPENAI_API_KEY environment variable.")
 chat_loop()

Sample Interaction

🤖 AI Sales Assistant – type 'exit' to quit.

You: I need a quick pitch for a new smartwatch.
Assistant: Absolutely! Our new smartwatch combines sleek design with cutting‑edge health tracking. It offers 24/7 heart‑rate monitoring, sleep analysis, and a battery life of up to 10 days—all on a vibrant, always‑on display. Would you like me to tailor the pitch for a specific audience?

You: Yes, for tech‑savvy millennials.
Assistant: Great! For tech‑savvy millennials, highlight the smartwatch’s seamless integration with popular fitness apps, customizable watch faces, and voice‑assistant support. Emphasize its sleek, minimalist aesthetic that pairs perfectly with both casual and professional attire. Want a one‑sentence tagline to cap it off?

You: exit
👋 Goodbye!

✅ Verify: 1. Install dependencies: pip install openai tiktoken. 2. Set your API key: export OPENAI_API_KEY=sk-.. 3. Run python chat_agent.py and follow the sample interaction above.

🚀 What You Just Built

• System Prompt – a fixed instruction that never gets trimmed.
• Dynamic Context Management – older turns are discarded automatically once the token budget is exceeded.
• Token‑aware API Calls – we reserve space for the model’s reply, preventing “context length exceeded” errors.
• Reusable Skeleton – swap MODEL_NAME for any OpenAI‑compatible model, adjust MAX_TOKENS, and you have a ready‑to‑go chat agent.

Common Mistakes

Troubleshooting

Key Takeaways

• LLMs are stateless; they only know what you feed them via the context window.
• Prompt engineering (system messages) is the primary way to give an LLM a “role”.
• Token limits are real; always count tokens and reserve space for the model’s reply.
• A few helper functions (num_tokens_from_messages, trim_messages) make token‑aware chat agents trivial to build.
• The pattern shown here scales to complex agents (tool use, tool‑calling, retrieval‑augmented generation) with minimal changes.

🧪 Try It Yourself

1. Add a memory layer: Store the full conversation in a JSON file and reload it on startup.
2. Introduce tool calling: When the user asks for a weather forecast, call a public API and inject the result into the next prompt.
3. Experiment with temperature: Set temperature=0 for deterministic answers, temperature=1.2 for creative responses. Observe the difference.

Happy hacking! 🚀

Why This Matters

Large Language Models (LLMs) are brilliant at generating text, but on their own they lack:

• Persistent memory – they forget everything once the context window is full.
• Access to external tools – they cannot look up the current date, query a database, or call an API.

Turning an LLM into an AI agent gives you both: a short‑term “working memory” that persists across turns, and a toolbox of functions the model can invoke when it needs real‑world data. This is the foundation of production‑grade assistants, chat‑bots, and autonomous agents.

What You’ll Build

In this chapter you will create a minimal AI agent that can:

1. Maintain conversation history (in‑memory memory).
2. Call external tools via OpenAI’s function calling feature:
3. get_current_date() – returns today’s date.
4. search_policy(query) – looks up a short HR policy JSON file.
5. Gracefully fall back to plain LLM generation when no tool is needed.

All code runs locally with the openai Python SDK – no additional services required.

Content

1. Project Overview

ai_agent/
├─ policies.json # tiny HR policy “knowledge base”
├─ tools.py # tool implementations + OpenAI function specs
├─ memory.py # simple conversation memory class
├─ agent.py # orchestrates the LLM, memory, and tools
└─ run.py # tiny REPL to talk to the agent

2. Install Dependencies

pip install openai==1.30.0 # latest stable at time of writing

Set your OpenAI API key as an environment variable:

export OPENAI_API_KEY="sk-."

3. Create the Knowledge Base (policies.json)

# Save as: policies.json
{
 "maternity_leave": {
 "eligibility": "All full‑time employees who have completed 12 months of service.",
 "duration": "12 weeks paid, followed by 4 weeks unpaid.",
 "procedure": "Submit a request to HR via the employee portal at least 30 days before the expected due date."
 },
 "remote_work": {
 "eligibility": "All employees after 6 months of tenure.",
 "max_days_per_month": 10,
 "approval": "Manager approval required via the internal ticketing system."
 }
}

✅ Verify: The file should be valid JSON and placed in the project root.

4. Define Tools & Function Specs (tools.py)

# Save as: tools.py
import json
from datetime import datetime
from pathlib import Path
> **What is PATH?** PATH is a list of folders your computer checks when you type a command. If you type `python`, your computer looks in each PATH folder for a file called `python.exe`. If it finds it, it runs it. If not, you get "command not found." Installing Python with "Add to PATH" checked adds Python's folder to this list.


from typing import Any, Dict, List

# ----------------------------------------------------------------------
# 1️⃣ Tool: Get Current Date
# ----------------------------------------------------------------------
def get_current_date() -> str:
 """Return today's date in ISO format (YYYY‑MM‑DD)."""
 return datetime.utcnow().date().isoformat()

# ----------------------------------------------------------------------
# 2️⃣ Tool: Search HR Policy
# ----------------------------------------------------------------------
_POLICY_PATH = Path(__file__).parent / "policies.json"
_POLICIES: Dict[str, Any] = json.loads(_POLICY_PATH.read_text())

def search_policy(topic: str) -> str:
 """
 Look up a short HR policy by *topic* (e.g., "maternity_leave").
 Returns a human‑readable paragraph or a not‑found message.
 """
 policy = _POLICIES.get(topic.lower())
 if not policy:
 return f"Sorry, I couldn't find a policy for '{topic}'."
 # Build a concise paragraph
 parts = [f"{k.capitalize()}: {v}" for k, v in policy.items()]
 return " ".join(parts)

# ----------------------------------------------------------------------
# 3️⃣ OpenAI Function Specifications (JSON schema)
# ----------------------------------------------------------------------
def get_function_definitions() -> List[Dict[str, Any]]:
 """Return the function specs that will be sent to the OpenAI API."""
 return [
 {
 "name": "get_current_date",
 "description": "Get today's date in ISO format.",
 "parameters": {
 "type": "object",
 "properties": {}
 }
 },
 {
 "name": "search_policy",
 "description": "Search a short HR policy by topic.",
 "parameters": {
 "type": "object",
 "properties": {
 "topic": {
 "type": "string",
 "description": "The policy topic, e.g., 'maternity_leave' or 'remote_work'."
 }
 },
 "required": ["topic"]
 }
 }
 ]

✅ Verify: Running python -c "import tools; print(tools.search_policy('maternity_leave'))" should print a paragraph about the maternity leave policy.

5. Simple In‑Memory Memory (memory.py)

# Save as: memory.py
from typing import List, Tuple

class ConversationMemory:
 """
 Stores a list of (role, content) tuples.
 Role is one of:'system', 'user', 'assistant', or 'function'.
 """
 def __init__(self, system_prompt: str):
 self.history: List[Tuple[str, str]] = [("system", system_prompt)]

 def add(self, role: str, content: str) -> None:
 self.history.append((role, content))

 def get_messages(self) -> List[dict]:
 """Return the history in the format expected by OpenAI's chat API."""
 return [{"role": role, "content": content} for role, content in self.history]

 def clear(self) -> None:
 """Reset to only the system prompt."""
 system_msg = self.history[0]
 self.history = [system_msg]

✅ Verify: Instantiate ConversationMemory and call get_messages() – you should see a list with a single system message.

6. The Agent Orchestrator (agent.py)

# Save as: agent.py
import json
import os
from typing import Any, Dict, List

import openai
from openai import OpenAI

from tools import get_function_definitions, get_current_date, search_policy
from memory import ConversationMemory

# ----------------------------------------------------------------------
# Configuration
# ----------------------------------------------------------------------
MODEL = "gpt-4o-mini" # cheap, function‑calling capable model
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

SYSTEM_PROMPT = (
 "You are a helpful HR assistant. Use the provided tools when appropriate. "
 "If a user asks for a date, call `get_current_date`. "
 "If they ask about company policies, call `search_policy` with the correct topic. "
 "Otherwise answer directly."
)

# ----------------------------------------------------------------------
# Helper: Dispatch function calls from the model
# ----------------------------------------------------------------------
def _dispatch_function_call(name: str, arguments: Dict[str, Any]) -> str:
 if name == "get_current_date":
 return get_current_date()
 if name == "search_policy":
 return search_policy(arguments["topic"])
 raise ValueError(f"Unknown function: {name}")

# ----------------------------------------------------------------------
# Core Agent Class
# ----------------------------------------------------------------------
class AIAgent:
 def __init__(self):
 self.memory = ConversationMemory(SYSTEM_PROMPT)
 self.function_defs = get_function_definitions()

 def chat(self, user_input: str) -> str:
 # 1️⃣ Append user message
 self.memory.add("user", user_input)

 # 2️⃣ First LLM call – allow function calls
 response = client.chat.completions.create(
 model=MODEL,
 messages=self.memory.get_messages(),
 functions=self.function_defs,
 function_call="auto", # let model decide
 )
 message = response.choices[0].message

 # 3️⃣ Did the model request a function?
 if message.get("function_call"):
 func_name = message["function_call"]["name"]
 arguments = json.loads(message["function_call"]["arguments"])
 # Call the real function
 function_result = _dispatch_function_call(func_name, arguments)

 # 4️⃣ Append function result to memory
 self.memory.add("function", json.dumps({
 "name": func_name,
 "arguments": arguments,
 "result": function_result
 }))

 # 5️⃣ Second LLM call – let model generate final answer using result
 second_response = client.chat.completions.create(
 model=MODEL,
 messages=self.memory.get_messages(),
 functions=self.function_defs,
 # No function call this time; we just want a plain answer
 function_call="none",
 )
 final_msg = second_response.choices[0].message["content"]
 self.memory.add("assistant", final_msg)
 return final_msg

 # ------------------------------------------------------------------
 # No function needed – plain answer from the model
 # ------------------------------------------------------------------
 answer = message["content"]
 self.memory.add("assistant", answer)
 return answer

 def reset(self) -> None:
 """Clear conversation history (except system prompt)."""
 self.memory.clear()

✅ Verify:

>>> from agent import AIAgent
>>> bot = AIAgent()
>>> bot.chat("What is today's date?")
'2026-09-15' # (or whatever the current UTC date is)
>>> bot.chat("Tell me about the maternity leave policy.")
'Eligibility: All full‑time employees who have completed 12 months of service. Duration: 12 weeks paid, followed by 4 weeks unpaid. Procedure: Submit a request to HR via the employee portal at least 30 days before the expected due date.'

7. Interactive REPL (run.py)

# Save as: run.py
import sys
from agent import AIAgent

def main() -> None:
 print("🤖 HR Assistant – type 'exit' to quit, 'reset' to start a new conversation.")
 bot = AIAgent()
 while True:
 try:
 user_input = input("\nYou: ").strip()
 except (EOFError, KeyboardInterrupt):
 print("\nGoodbye!")
 break

 if user_input.lower() in {"exit", "quit"}:
 print("Goodbye!")
 break
 if user_input.lower() == "reset":
 bot.reset()
 print("🧹 Conversation cleared.")
 continue

 answer = bot.chat(user_input)
 print(f"\nAssistant: {answer}")

if __name__ == "__main__":
 main()

Run it:

python run.py

Sample Interaction

🤖 HR Assistant – type 'exit' to quit, 'reset' to start a new conversation.

You: What is today's date?

Assistant: 2026-09-15

You: Can you tell me the remote work policy?

Assistant: Eligibility: All employees after 6 months of tenure. Max_days_per_month: 10. Approval: Manager approval required via the internal ticketing system.

You: reset
🧹 Conversation cleared.

You: Who won the FIFA World Cup 2022?
Assistant: Argentina won the 2022 FIFA World Cup, defeating France in the final.

You: exit
Goodbye!

✅ Verify: The REPL should behave exactly as shown (dates will differ based on the current day).

📁 Project Files

🚀 What You Just Built

You now have a complete, runnable AI agent that:

• Persists conversation context across turns (until you call reset).
• Dynamically decides whether to invoke a tool based on the model’s function_call.
• Retrieves structured data from a local JSON “knowledge base”.
• Provides a clean REPL for rapid experimentation.

All of this is achieved with just 150 lines of Python and the OpenAI SDK – no external orchestration frameworks required.

Common Mistakes

Troubleshooting

Key Takeaways

• Function calling bridges the gap between pure text generation and real‑world actions.
• A lightweight memory layer (list of messages) gives the illusion of stateful conversation.
• Keep the knowledge base minimal – only feed the model the exact snippet it needs.
• Always verify token usage; a full conversation can quickly exceed the model’s context window.

With these building blocks you can now expand the agent: add more tools (e.g., calendar lookup, ticket creation), swap the JSON store for a vector DB, or integrate LangChain for richer pipelines.

🧪 Try It Yourself

1. Add a new tool that fetches the current weather from a public API (e.g., OpenWeatherMap).
2. Define the function in tools.py.
3. Add its spec to get_function_definitions().

4. Extend _dispatch_function_call to call it.

5. Persist memory to disk so the conversation survives a program restart.

6. Serialize self.memory.history to a JSON file after each turn.

7. Load it back in ConversationMemory.__init__ if the file exists.

8. Replace the static JSON policy file with a simple vector store (e.g., faiss + sentence‑transformers).

9. When search_policy receives a query, embed it, retrieve the most similar policy snippet, and return that.

Happy building! 🚀

Why This Matters

Modern LLMs are great at answering questions, but they don’t have direct access to your data or external services. An AI agent bridges that gap: it lets the model decide when to call a tool (e.g., Google Calendar, Gmail), feeds the tool’s result back into its own reasoning, and repeats until the user’s goal is satisfied.

Understanding the agent loop is essential for building assistants that can:

• Search the web for up‑to‑date facts.
• Read a user’s email to extract context.
• Book meetings, create tasks, or run code on demand.

In this chapter you’ll build a minimal, fully‑runnable AI agent that can:

1. Parse a natural‑language request.
2. Detect that a calendar tool is needed.
3. Call the tool with the correct parameters.
4. Re‑evaluate the tool’s response and, if necessary, call the tool again.
5. Return a final, human‑readable answer.

💡 Tip – Even though we’ll mock Google Calendar, the same pattern works with the real API (just replace the mock with the official client).

What You’ll Build

A single‑file Python program (agent.py) that:

• Uses OpenAI’s function‑calling feature to let the LLM decide when and how to invoke a find_free_slot and create_event function.
• Maintains an in‑memory calendar for two users (me and Priya).
• Demonstrates the full agent loop: request → tool call → LLM re‑reason → final answer.

Content

1. Define the tool signatures (function schemas)

OpenAI expects a JSON schema that describes each callable function. We’ll expose two functions:

2. Mock calendar data

A simple dictionary stores events per user. Each event is a tuple: (start_datetime, end_datetime, title).

3. The agent loop

while not done:
 # 1️⃣ Send user + any tool output back to the model
 # 2️⃣ If the model returns a function call → execute it
 # 3️⃣ Append the function’s result to the conversation
 # 4️⃣ If the model replies with a normal message → we’re finished

4. Putting it together

The script:

1. Reads the user query from stdin.
2. Starts the loop with the initial user message.
3. Handles function calls automatically.
4. Prints the final assistant message.

📁 Project Files

agent.py

# Save as: agent.py
"""
Minimal AI Agent that can schedule a meeting using a mock calendar.
It demonstrates the agent loop with OpenAI function calling.
"""

import os
import json
import datetime as dt
from typing import List, Tuple, Dict, Any

import openai # pip install openai

# ------------------------------------------------------------
# 1️⃣ Mock Calendar (in‑memory)
# ------------------------------------------------------------
CalendarDB: Dict[str, List[Tuple[dt.datetime, dt.datetime, str]]] = {
 "me": [], # Your own events
 "Priya": [] # Priya's events
}

def _print_calendar():
 """Utility to visualize the mock calendar (used in debugging)."""
 for user, events in CalendarDB.items():
 print(f"\n=== {user}'s Calendar ===")
 for start, end, title in events:
 print(f"{start.isoformat()} → {end.isoformat()} : {title}")

# ------------------------------------------------------------
# 2️⃣ Tool: find_free_slot
# ------------------------------------------------------------
def find_free_slot(date: str, duration_minutes: int,
 participants: List[str]) -> Dict[str, Any]:
 """
 Return the earliest free 1‑hour slot on `date` for all `participants`.
 If no slot exists, return an empty dict.
 """
 target_date = dt.datetime.strptime(date, "%Y-%m-%d").date()
 day_start = dt.datetime.combine(target_date, dt.time(9, 0)) # 9 AM
 day_end = dt.datetime.combine(target_date, dt.time(17, 0)) # 5 PM

 # Build a list of busy intervals for each participant
 busy: List[Tuple[dt.datetime, dt.datetime]] = []
 for p in participants:
 for ev_start, ev_end, _ in CalendarDB.get(p, []):
 if ev_start.date() == target_date:
 busy.append((ev_start, ev_end))

 # Sort and merge overlapping busy intervals
 busy.sort()
 merged: List[Tuple[dt.datetime, dt.datetime]] = []
 for start, end in busy:
 if not merged or start > merged[-1][1]:
 merged.append([start, end])
 else:
 merged[-1][1] = max(merged[-1][1], end)

 # Scan for a free slot
 cursor = day_start
 slot_delta = dt.timedelta(minutes=duration_minutes)

 for start, end in merged:
 if cursor + slot_delta <= start: # free before this busy block
 break
 cursor = max(cursor, end)

 # Final check against day_end
 if cursor + slot_delta > day_end:
 return {} # No slot found

 return {
 "start_time": cursor.isoformat(),
 "end_time": (cursor + slot_delta).isoformat()
 }

# ------------------------------------------------------------
# 3️⃣ Tool: create_event
# ------------------------------------------------------------
def create_event(title: str, start_time: str, end_time: str,
 participants: List[str]) -> Dict[str, Any]:
 """
 Insert an event into the mock calendar for every participant.
 Returns a confirmation dict.
 """
 start_dt = dt.datetime.fromisoformat(start_time)
 end_dt = dt.datetime.fromisoformat(end_time)

 for p in participants:
 CalendarDB.setdefault(p, []).append((start_dt, end_dt, title))

 return {
 "status": "ok",
 "event": {
 "title": title,
 "start_time": start_time,
 "end_time": end_time,
 "participants": participants
 }
 }

# ------------------------------------------------------------
# 4️⃣ OpenAI function schemas
# ------------------------------------------------------------
function_schemas = [
 {
 "name": "find_free_slot",
 "description": "Find the earliest free time slot for given participants on a specific date.",
 "parameters": {
 "type": "object",
 "properties": {
 "date": {
 "type": "string",
 "description": "Date in YYYY-MM-DD format."
 },
 "duration_minutes": {
 "type": "integer",
 "description": "Length of the meeting in minutes."
 },
 "participants": {
 "type": "array",
 "items": {"type": "string"},
 "description": "List of participant names (must match keys in CalendarDB)."
 }
 },
 "required": ["date", "duration_minutes", "participants"]
 }
 },
 {
 "name": "create_event",
 "description": "Create a calendar event with the given details.",
 "parameters": {
 "type": "object",
 "properties": {
 "title": {"type": "string"},
 "start_time": {"type": "string", "format": "date-time"},
 "end_time": {"type": "string", "format": "date-time"},
 "participants": {
 "type": "array",
 "items": {"type": "string"}
 }
 },
 "required": ["title", "start_time", "end_time", "participants"]
 }
 }
]

# ------------------------------------------------------------
# 5️⃣ Agent Loop
# ------------------------------------------------------------
def run_agent(user_query: str) -> str:
 """
 Executes the agent loop until the LLM returns a final answer.
 Returns the assistant's final message.
 """
 # Initial conversation
 messages = [
 {"role": "system",
 "content": "You are an AI assistant that can schedule meetings using the provided tools. "
 "When you need to call a tool, use the function calling feature. "
 "Only call a tool when it is necessary to achieve the user's goal."},
 {"role": "user", "content": user_query}
 ]

 while True:
 response = openai.ChatCompletion.create(
 model="gpt-4o-mini", # or any model that supports function calling
 messages=messages,
 functions=function_schemas,
 function_call="auto" # let the model decide
 )
 message = response["choices"][0]["message"]

 # ----------------------------------------------------
 # 5️⃣a If the model decided to call a function
 # ----------------------------------------------------
 if message.get("function_call"):
 func_name = message["function_call"]["name"]
 arguments = json.loads(message["function_call"]["arguments"])

 # Dispatch to the real Python function
 if func_name == "find_free_slot":
 result = find_free_slot(**arguments)
 elif func_name == "create_event":
 result = create_event(**arguments)
 else:
 raise RuntimeError(f"Unknown function {func_name}")

 # Append the function result to the conversation
 messages.append(message) # the model's function call request
 messages.append({
 "role": "function",
 "name": func_name,
 "content": json.dumps(result)
 })
 # Loop again – the model will now see the result and decide next steps
 continue

 # ----------------------------------------------------
 # 5️⃣b Normal assistant reply → we are done
 # ----------------------------------------------------
 final_answer = message["content"]
 return final_answer

# ------------------------------------------------------------
# 6️⃣ Entry point
# ------------------------------------------------------------
if __name__ == "__main__":
 # Ensure the OpenAI key is available
 if not os.getenv("OPENAI_API_KEY"):
 raise EnvironmentError("Set the OPENAI_API_KEY environment variable.")

 # Example query (you can replace it with any other request)
 query = "Find a suitable 1 hour slot tomorrow for me and Priya and schedule a meeting titled 'Project Sync'."
 answer = run_agent(query)

 print("\n🤖 Assistant:", answer)
 _print_calendar() # Show the mock calendar after the run

Expected output (when run on 2026‑09‑15)

🤖 Assistant: I’ve scheduled “Project Sync” on 2026-09-16 from 09:00 to 10:00 for you and Priya.

=== me's Calendar ===
2026-09-16T09:00:00+00:00 → 2026-09-16T10:00:00+00:00 : Project Sync

=== Priya's Calendar ===
2026-09-16T09:00:00+00:00 → 2026-09-16T10:00:00+00:00 : Project Sync

⚠️ Warning – The mock calendar assumes the day starts at 9 AM and ends at 5 PM UTC. Adjust day_start / day_end if you need a different working window.

✅ Verify: Run python agent.py after setting OPENAI_API_KEY. The assistant should print a confirmation and the two calendars should contain the new event.

🚀 What You Just Built

The loop mimics a human assistant: understand → act → verify → act again if needed.

Common Mistakes

Troubleshooting

1. openai.error.InvalidRequestError: This model's maximum context length is. Cause: The conversation (including function results) exceeds the model’s token limit. Fix: Summarise older messages or truncate the calendar data before appending it.

2. json.decoder.JSONDecodeError Cause: The LLM returned malformed JSON. Fix: Wrap the json.loads call in a try/except and ask the model to re‑format the arguments.

3. No meeting is created Cause: The model decided the request was ambiguous. Fix: Provide a clearer user prompt, e.g., include the meeting title and exact duration.

4. OPENAI_API_KEY not set Cause: Environment variable missing. Fix: export OPENAI_API_KEY=sk-. on Unix or set it in PowerShell ($env:OPENAI_API_KEY = "sk-.").

✅ Verify: After fixing any issue, re‑run python agent.py. The assistant should now schedule the meeting and display the calendars.

Key Takeaways

• Agent Loop – The core pattern: LLM → (optional) tool call → result → LLM repeats until the goal is met.
• Function calling gives the model a structured, safe way to invoke external services.
• Context window is the only place the LLM “sees” data; feeding tool results back is how you extend its knowledge.
• Mocking external APIs lets you develop and test locally; swapping in real APIs only requires changing the function bodies.

🧪 Try It Yourself

1. Add a third participant (Alex) with a pre‑existing event on the same day. Modify CalendarDB before the loop:

python CalendarDB["Alex"] = [ (dt.datetime(2026, 9, 16, 9, 30), dt.datetime(2026, 9, 16, 11, 0), "Team Standup") ]

1. Change the user query to include Alex:

python query = "Find a suitable 1 hour slot tomorrow for me, Priya, and Alex and schedule a meeting titled 'Design Review'."

1. Run the script and observe how the agent now picks a later slot (e.g., 11 AM‑12 PM).

2. Experiment with different durations (duration_minutes) and dates to see the loop adapt.

Happy building! 🎉

What's Next

Continue to the next chapter to keep building.

Chapter 7

How Agents Reason, Remember, and Act

Why This Matters

Before You Start This Chapter

• Your venv is active (you see `(.

  What is a virtual environment (venv)? It is a separate, isolated Python world for your project. Without it, packages from different projects can conflict. With a venv, each project gets its own clean set of packages. Think of it like a separate browser profile for each website.

venv)in your prompt) - Previous chapter's project is working - Your.env` file has your API key

What is an API? An API (Application Programming Interface) is how one program talks to another. Think of it like a waiter in a restaurant — you (your code) tell the waiter (API) what you want, the waiter goes to the kitchen (the server), and brings back your food (the response). You never talk to the kitchen directly.

• You are in the correct folder (run pwd to check)

Get Your OpenAI API Key

1. Go to https://platform.openai.com/api-keys
2. Log in (free account)
3. Click "Create new secret key"
4. Name it (e.g., "adhikk")
5. Click "Create"
6. Copy the key (starts with sk-) — you will not see it again
7. Paste into your .env file

New accounts get $5 free credit — enough for this entire book.

Large Language Models (LLMs) are fantastic at generating text, but real‑world applications need them to act—book a flight, fetch a price, or write a file. When you give an LLM access to tools (APIs, functions, databases) and a memory of past interactions, it becomes an AI Agent that can:

• Decide what to do (which tool to call).
• Decide when to do it (loop until the goal is satisfied).
• Keep track of what it has learned (memory) across calls.

Understanding this workflow lets you build assistants that go beyond chat—think travel planners, code generators, or automated help desks.

What You’ll Build

A Travel Planner Agent that can:

1. Parse a user request like “Plan a two‑day trip to Jaipur with a budget of $300”.
2. Call tool functions (flight search, hotel search, budget check) as needed.
3. Store intermediate results in a memory buffer.
4. Loop until it can produce a complete itinerary or ask the user for confirmation.

All code runs locally with the OpenAI gpt-3.5-turbo model (or any compatible API). No external services are required beyond the OpenAI endpoint.

Content

1. Core Concepts Recap

2. Project Overview

travel_agent/
│
├─ # Save as: tools.py
│ └─ Functions that simulate external services.
│
├─ # Save as: memory.py
│ └─ Simple in‑memory store for observations.
│
├─ # Save as: agent.py
│ └─ The orchestrator that talks to the LLM, decides which tool to call,
│ updates memory, and loops.
│
└─ # Save as: run.py
 └─ Entry point that starts the conversation.

3. Implementing the Tools

# Save as: tools.py
import random
from typing import Dict, Any

def search_flights(origin: str, destination: str, date: str) -> Dict[str, Any]:
 """Mock flight search – returns a random price."""
 price = random.randint(50, 150)
 return {
 "origin": origin,
 "destination": destination,
 "date": date,
 "price_usd": price,
 "airline": random.choice(["AirAlpha", "SkyJet", "Nimbus"])
 }

def search_hotels(city: str, check_in: str, nights: int) -> Dict[str, Any]:
 """Mock hotel search – returns a random nightly rate."""
 nightly = random.randint(30, 80)
 total = nightly * nights
 return {
 "city": city,
 "check_in": check_in,
 "nights": nights,
 "nightly_usd": nightly,
 "total_usd": total,
 "hotel_name": random.choice(["Grand Palace", "City Inn", "Heritage Stay"])
 }

def check_budget(total_cost: int, budget: int) -> bool:
 """Simple budget validator."""
 return total_cost <= budget

Expected output (when called directly):

>>> from tools import search_flights
>>> search_flights("DEL", "JAI", "2024-10-01")
{'origin': 'DEL', 'destination': 'JAI', 'date': '2024-10-01', 'price_usd': 112, 'airline': 'Nimbus'}

✅ Verify: Run the snippet above in a Python REPL; you should see a dictionary with a random price.

4. Memory Module

# Save as: memory.py
from typing import List, Dict

class Memory:
 """A very small in‑memory store that the agent can read/write."""
 def __init__(self):
 self._store: List[Dict] = []

 def add(self, entry: Dict) -> None:
 """Append a new observation."""
 self._store.append(entry)

 def get_all(self) -> List[Dict]:
 """Return a copy of all stored entries."""
 return list(self._store)

 def __repr__(self) -> str:
 return f"<Memory entries={len(self._store)}>"

✅ Verify:

>>> from memory import Memory
>>> mem = Memory()
>>> mem.add({"type": "flight", "price_usd": 120})
>>> mem.get_all()
[{'type': 'flight', 'price_usd': 120}]

5. The Agent Core

# Save as: agent.py
import json
import os
from typing import Any, Dict, List

import openai # pip install openai
from tools import search_flights, search_hotels, check_budget
from memory import Memory

# -------------------------------------------------
# Configuration – replace with your own key or set env var OPENAI_API_KEY
# -------------------------------------------------
openai.api_key = os.getenv("OPENAI_API_KEY", "sk-.") # <-- put your key here

# -------------------------------------------------
# Helper: Build the function specifications for OpenAI function calling
# -------------------------------------------------
TOOL_DEFINITIONS = [
 {
 "name": "search_flights",
 "description": "Find a flight between two cities on a given date.",
 "parameters": {
 "type": "object",
 "properties": {
 "origin": {"type": "string", "description": "IATA code of departure city"},
 "destination": {"type": "string", "description": "IATA code of arrival city"},
 "date": {"type": "string", "description": "Travel date in YYYY-MM-DD"},
 },
 "required": ["origin", "destination", "date"],
 },
 },
 {
 "name": "search_hotels",
 "description": "Find a hotel in a city for a given stay.",
 "parameters": {
 "type": "object",
 "properties": {
 "city": {"type": "string"},
 "check_in": {"type": "string", "description": "YYYY-MM-DD"},
 "nights": {"type": "integer"},
 },
 "required": ["city", "check_in", "nights"],
 },
 },
 {
 "name": "check_budget",
 "description": "Validate that total cost does not exceed the user's budget.",
 "parameters": {
 "type": "object",
 "properties": {
 "total_cost": {"type": "integer"},
 "budget": {"type": "integer"},
 },
 "required": ["total_cost", "budget"],
 },
 },
]

# -------------------------------------------------
# Agent class
# -------------------------------------------------
class TravelAgent:
 def __init__(self, model: str = "gpt-3.5-turbo-0613"):
 self.model = model
 self.memory = Memory()
 self.messages: List[Dict] = [] # conversation history for the LLM

 def _add_user_message(self, content: str) -> None:
 self.messages.append({"role": "user", "content": content})

 def _call_llm(self) -> Dict:
 """Ask the LLM to either answer or request a tool."""
 response = openai.ChatCompletion.create(
 model=self.model,
 messages=self.messages,
 functions=TOOL_DEFINITIONS,
 function_call="auto", # let the model decide
 )
 return response["choices"][0]["message"]

 def _dispatch_tool(self, name: str, arguments: str) -> Dict:
 args = json.loads(arguments)
 if name == "search_flights":
 result = search_flights(**args)
 elif name == "search_hotels":
 result = search_hotels(**args)
 elif name == "check_budget":
 result = {"within_budget": check_budget(**args)}
 else:
 raise ValueError(f"Unknown tool {name}")
 # Store in memory
 self.memory.add({"tool": name, "arguments": args, "result": result})
 return result

 def run(self, user_query: str) -> str:
 """Main loop – returns the final human‑readable answer."""
 self._add_user_message(user_query)

 while True:
 llm_msg = self._call_llm()

 # 1️⃣ LLM decided to call a tool
 if llm_msg.get("function_call"):
 func_name = llm_msg["function_call"]["name"]
 arguments = llm_msg["function_call"]["arguments"]
 tool_result = self._dispatch_tool(func_name, arguments)

 # Feed the tool result back to the model
 self.messages.append({
 "role": "assistant",
 "content": None,
 "function_call": llm_msg["function_call"],
 })
 self.messages.append({
 "role": "function",
 "name": func_name,
 "content": json.dumps(tool_result),
 })
 continue # go back to the top of the loop

 # 2️⃣ LLM produced a final answer
 final_answer = llm_msg["content"]
 return final_answer

What the code does

1. Prompt → LLM – Sends the conversation (including memory) to the model.
2. Function Call? – If the model returns a function_call, we invoke the corresponding Python function.
3. Result → LLM – The result is added as a function message, letting the model see the observation.
4. Loop – The model may call another tool or finally answer.

✅ Verify:

>>> from agent import TravelAgent
>>> agent = TravelAgent()
>>> answer = agent.run("Plan a two‑day trip to Jaipur with a budget of $300")
>>> print(answer)

You should see a concise itinerary, e.g.:

Here is your Jaipur itinerary within $300:
- Flight: DEL → JAI on 2024-10-01, $112 (AirAlpha)
- Hotel: Grand Palace, 2 nights, $140 total
Total cost: $252. Let me know if you’d like me to book these for you.

6. Entry Point

# Save as: run.py
from agent import TravelAgent

def main():
 print("🧳 Travel Planner Agent – type 'exit' to quit.")
 agent = TravelAgent()
 while True:
 user_input = input("\nYou: ")
 if user_input.lower() in {"exit", "quit"}:
 break
 answer = agent.run(user_input)
 print("\nAgent:", answer)

if __name__ == "__main__":
 main()

Run it:

python run.py

Sample interaction

🧳 Travel Planner Agent – type 'exit' to quit.

You: Plan a two-day trip to Jaipur with a budget of $300

Agent: Here is your Jaipur itinerary within $300:
- Flight: DEL → JAI on 2024-10-01, $112 (AirAlpha)
- Hotel: Grand Palace, 2 nights, $140 total
Total cost: $252. Let me know if you’d like me to book these for you.

✅ Verify: The conversation above should appear exactly as shown (prices will vary due to randomness, but total must stay ≤ 300).

📁 Project Files

All files are self‑contained; just place them in a folder and run python run.py.

🚀 What You Just Built

• An autonomous AI agent that decides what tool to invoke, when to invoke it, and how to combine results.
• A deterministic memory buffer that records every tool call, enabling the LLM to “remember” past observations.
• A reusable loop that can be extended with more tools (e.g., weather API, calendar integration) without touching the core logic.

Common Mistakes

Troubleshooting

Key Takeaways

• LLM = Brain, Context Window = Desk, Tools = Hands/Eyes, Memory = Notepad.
• An agent is just a loop: interpret → decide → act → observe → repeat.
• Function calling lets the LLM invoke real Python code safely and deterministically.
• Keep memory lightweight and prompt engineering clear to guide the model toward the right tool.

🧪 Try It Yourself

1. Add a new tool – e.g., search_restaurants(city) that returns a random restaurant list.
2. Update TOOL_DEFINITIONS in agent.py with the new function spec.
3. Modify the prompt (inside run.py or by adding a system message) to ask the agent to suggest dinner options.

# Example addition to tools.py
def search_restaurants(city: str) -> dict:
 return {
 "city": city,
 "restaurants": random.sample(
 ["Spice Route", "Maharaja", "Royal Dine", "Curry House"], k=2
 ),
 }

Run the agent again and ask:

You: I also want dinner recommendations for Jaipur.

Observe how the agent automatically calls search_restaurants and incorporates the result into its reply.

Happy building! 🚀

Why This Matters

Modern AI assistants are no longer just “chat‑bots” that spit out text. They can call external tools—read files, run calculations, query databases—so they act like real assistants that do work for you. Understanding how to wire an LLM to function calls and expose it through a front‑end UI is the foundation for every AI‑powered product you’ll build tomorrow (customer support bots, data‑analysis assistants, internal knowledge bases, …).

What You’ll Build

A single‑page Streamlit app that lets a user:

1. Upload a résumé (plain‑text .txt file).
2. Ask a natural‑language question about the résumé (e.g., “How many years of Python experience do I have?”).
3. The app’s LLM agent will:
4. Call a read‑resume tool to extract the raw text.
5. Call a calculate‑experience tool to compute the answer.
6. Display the final answer in the UI.

All the heavy lifting (LLM, function calling, tool implementation) lives in pure Python—no extra research required.

Content

1️⃣ Architecture Overview

┌─────────────────────┐
│ Streamlit UI │ ← User uploads résumé & asks question
└─────────┬───────────┘
 │
 ▼
┌─────────────────────┐
│ agent.py │ ← LLM + OpenAI function‑calling logic
│ - decides which │
│ tool to call │
│ - parses tool │
│ results │
└───────▲─────┬───────┘
 │ │
 │ ▼
 │ ┌─────────────────────┐
 │ │ tools.py │
 │ │ - read_resume() │
 │ │ - calc_experience()│
 │ └─────────────────────┘
 │
 ▼
 OpenAI API (gpt‑3.5‑turbo‑1106)

2️⃣ Core Concepts

📁 Project Files

tools.py – Helper functions that the LLM can call

# Save as: tools.py
import re
from pathlib import Path
> **What is PATH?** PATH is a list of folders your computer checks when you type a command. If you type `python`, your computer looks in each PATH folder for a file called `python.exe`. If it finds it, it runs it. If not, you get "command not found." Installing Python with "Add to PATH" checked adds Python's folder to this list.


from typing import Dict

def read_resume(file_path: str) -> Dict[str, str]:
 """
 Reads a plain‑text résumé and returns its content.
 The LLM expects a JSON‑compatible dict.
 """
 text = Path(file_path).read_text(encoding="utf-8")
 return {"content": text}

def calc_experience(resume_text: str, language: str = "Python") -> Dict[str, int]:
 """
 Very naive experience calculator:
 - Looks for lines like "Python – 2015‑2021"
 - Returns the total number of years for the given language.
 """
 # Regex to capture year ranges (e.g., 2015-2021 or 2018‑present)
 pattern = rf"{language}\s*[-–]\s*(\d{{4}})\s*[-–]\s*(\d{{4}}|present|now)"
 matches = re.findall(pattern, resume_text, flags=re.IGNORECASE)

 total_years = 0
 for start, end in matches:
 start_year = int(start)
 if end.lower() in {"present", "now"}:
 end_year = 2026 # current year for demo purposes
 else:
 end_year = int(end)
 total_years += max(0, end_year - start_year)

 return {"years": total_years}

Expected output (when called directly):

>>> from tools import read_resume, calc_experience
>>> data = read_resume("sample_resume.txt")
>>> data
{'content': 'John Doe\nPython – 2015‑2021\n.'}
>>> calc_experience(data["content"], language="Python")
{'years': 6}

✅ Verify: Run the snippet above in a Python REPL; it should print the dictionaries shown.

agent.py – LLM agent that decides which tool to invoke

# Save as: agent.py
import json
import os
from typing import Any, Dict, List

import openai

# -------------------------------------------------
# Set your OpenAI API key as an environment variable:
# export OPENAI_API_KEY="sk-."
# -------------------------------------------------
openai.api_key = os.getenv("OPENAI_API_KEY")

# Define the function schemas that the model can call
FUNCTIONS = [
 {
 "name": "read_resume",
 "description": "Read a résumé file and return its raw text.",
 "parameters": {
 "type": "object",
 "properties": {
 "file_path": {
 "type": "string",
 "description": "Absolute or relative path to the résumé file."
 }
 },
 "required": ["file_path"],
 },
 },
 {
 "name": "calc_experience",
 "description": "Calculate years of experience for a given programming language from résumé text.",
 "parameters": {
 "type": "object",
 "properties": {
 "resume_text": {
 "type": "string",
 "description": "Full résumé text extracted by read_resume."
 },
 "language": {
 "type": "string",
 "description": "Programming language to look for (e.g., Python).",
 "default": "Python"
 },
 },
 "required": ["resume_text"],
 },
 },
]

# -----------------------------------------------------------------
# Core agent logic – single round of function calling
# -----------------------------------------------------------------
def ask_agent(user_question: str, resume_path: str) -> str:
 """
 Sends the user question to the LLM. If the model decides to call a function,
 we execute it locally, feed the result back, and finally return the model's answer.
 """
 # 1️⃣ First request – let the model decide if it needs a tool
 response = openai.ChatCompletion.create(
 model="gpt-3.5-turbo-1106",
 messages=[{"role": "user", "content": user_question}],
 functions=FUNCTIONS,
 function_call="auto", # let the model choose
 )
 message = response["choices"][0]["message"]

 # -------------------------------------------------
 # Did the model request a function?
 # -------------------------------------------------
 if message.get("function_call"):
 func_name = message["function_call"]["name"]
 arguments = json.loads(message["function_call"]["arguments"])

 # 2️⃣ Execute the requested function
 if func_name == "read_resume":
 from tools import read_resume
 result = read_resume(arguments["file_path"])
 elif func_name == "calc_experience":
 from tools import calc_experience
 result = calc_experience(
 resume_text=arguments["resume_text"],
 language=arguments.get("language", "Python")
 )
 else:
 raise ValueError(f"Unsupported function: {func_name}")

 # 3️⃣ Send the function result back to the model
 follow_up = openai.ChatCompletion.create(
 model="gpt-3.5-turbo-1106",
 messages=[
 {"role": "user", "content": user_question},
 message, # the function call request
 {
 "role": "function",
 "name": func_name,
 "content": json.dumps(result),
 },
 ],
 )
 final_answer = follow_up["choices"][0]["message"]["content"]
 return final_answer.strip()
 else:
 # Model answered directly without needing a tool
 return message["content"].strip()

Quick sanity check (run in a Python shell):

>>> from agent import ask_agent
>>> answer = ask_agent(. "How many years of Python experience does my résumé show?",. resume_path="sample_resume.txt". )
>>> print(answer)
Your résumé shows about 6 years of Python experience.

✅ Verify: The printed sentence should match the example above.

app.py – Streamlit front‑end

# Save as: app.py
import os
import tempfile
import streamlit as st

from agent import ask_agent

st.set_page_config(page_title="Résumé Assistant", page_icon="🧑‍💻")

st.title("🧑‍💻 Résumé Assistant")
st.write(
 "Upload a plain‑text résumé and ask any question about it. "
 "The assistant will use an LLM + tool‑calling to give you an answer."
)

# -------------------------------------------------
# 1️⃣ Upload résumé
# -------------------------------------------------
uploaded_file = st.file_uploader(
 "📄 Upload your résumé (TXT only)",
 type=["txt"],
 help="The file must be plain text. PDF/Docx conversion is out of scope for this demo."
)

if uploaded_file:
 # Save to a temporary location so the LLM agent can read it
 with tempfile.NamedTemporaryFile(delete=False, suffix=".txt") as tmp:
 tmp.write(uploaded_file.getvalue())
 resume_path = tmp.name

 st.success("✅ Résumé uploaded successfully!")

 # -------------------------------------------------
 # 2️⃣ Ask a question
 # -------------------------------------------------
 question = st.text_input(
 "❓ What would you like to know?",
 placeholder="e.g., How many years of Python experience do I have?"
 )

 if st.button("🚀 Get Answer") and question:
 with st.spinner("Thinking."):
 answer = ask_agent(question, resume_path)
 st.markdown("**Answer:**")
 st.write(answer)

 # Clean up the temporary file after the session ends
 def _cleanup():
 try:
 os.remove(resume_path)
 except OSError:
 pass

 st.experimental_singleton.clear() # Force cleanup on rerun
 st.on_cleanup(_cleanup)
else:
 st.info("👈 Please upload a résumé to begin.")

Running the app

$ streamlit run app.py

A browser window opens at http://localhost:8501. Upload sample_resume.txt, type a question, and click Get Answer.

Expected UI flow & output

1. Upload → “✅ Résumé uploaded successfully!”
2. Enter question → Click → Spinner →
3. Final answer appears, e.g.:

**Answer:**
Your résumé shows about 6 years of Python experience.

✅ Verify: Follow the steps above; the answer should reflect the data in your résumé file.

🚀 What You Just Built

You now have a complete, end‑to‑end AI assistant that:

• Accepts user input via a web UI.
• Dynamically decides which backend tool to run.
• Returns a natural‑language answer that incorporates real data.

Common Mistakes

Troubleshooting

Key Takeaways

• Function calling transforms a static LLM into an agent that can interact with the real world.
• Keep tool signatures simple and JSON‑serializable; the model can only work with primitive types.
• Separate concerns: UI (Streamlit) ↔ Agent (LLM + decision logic) ↔ Tools (pure Python).
• Always verify each component in isolation before wiring them together.

🧪 Try It Yourself

1. Add a new tool – e.g., extract_email(resume_text) that returns the first email address found.
2. Update FUNCTIONS in agent.py with the new schema.
3. Ask the assistant: “What is my email address?”

Bonus: Replace gpt-3.5-turbo-1106 with gpt-4o-mini for cheaper, faster responses (adjust the model name in agent.py).

Happy hacking! 🚀

Why This Matters

Deploying your code turns a local experiment into a real‑world service that anyone on the internet can use—24 hours a day, 7 days a week. - Reach: Your friends, coworkers, or customers can interact with your AI agent from any device. - Reliability: A cloud server never sleeps (unless you shut it down), so the service is always available. - Scalability: Cloud platforms can automatically allocate more resources when traffic spikes.

In this chapter you’ll learn how to take the FastAPI‑based ChatGPT proxy you built locally and push it to the cloud with Docker and Render (a free‑tier PaaS). By the end you’ll have a live URL that anyone can call.

What You’ll Build

A production‑ready container that runs a FastAPI app exposing a single endpoint:

POST https://<your‑app>.onrender.com/chat
{
 "message": "Tell me a joke"
}

The service will:

1. Accept a JSON payload with a user message.
2. Forward the message to OpenAI’s gpt-3.5-turbo model.
3. Return the model’s reply as JSON.

All secrets (your OpenAI API key) are stored securely in Render’s environment variables, never hard‑coded.

Content

1️⃣ Create a Fresh Git Repository

mkdir gpt‑proxy‑render
cd gpt‑proxy‑render
git init

2️⃣ Write the FastAPI Application

# Save as: main.py
import os
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
import openai
import uvicorn

# Load the API key from environment (Render injects this)
openai.api_key = os.getenv("OPENAI_API_KEY")
if not openai.api_key:
 raise RuntimeError("OPENAI_API_KEY not set in environment")

app = FastAPI(title="ChatGPT Proxy")

class ChatRequest(BaseModel):
 message: str

class ChatResponse(BaseModel):
 reply: str

@app.post("/chat", response_model=ChatResponse)
async def chat_endpoint(req: ChatRequest):
 try:
 # Call OpenAI Chat Completion API
 response = await openai.ChatCompletion.acreate(
 model="gpt-3.5-turbo",
 messages=[{"role": "user", "content": req.message}],
 temperature=0.7,
 )
 reply = response.choices[0].message.content.strip()
 return ChatResponse(reply=reply)
 except openai.error.OpenAIError as e:
 raise HTTPException(status_code=502, detail=str(e))

# Development entry point (Render will use `gunicorn` instead)
if __name__ == "__main__":
 uvicorn.run(app, host="0.0.0.0", port=8000)

Expected output (local test):

$ curl -X POST http://127.0.0.1:8000/chat -H "Content-Type: application/json" -d '{"message":"Tell me a joke"}'
{"reply":"Why did the scarecrow win an award? Because he was outstanding in his field!"}

✅ Verify: Run uvicorn main:app --reload locally, send the curl request above, and confirm you receive a JSON reply.

3️⃣ Define Dependencies

# Save as: requirements.txt
fastapi==0.110.0
uvicorn[standard]==0.27.0
openai==1.12.0
pydantic==2.6.1

✅ Verify: pip install -r requirements.txt completes without errors.

4️⃣ Dockerize the Application

# Save as: Dockerfile
# Use the official lightweight Python image
FROM python:3.12-slim

# Set a non‑root user for security
RUN useradd -m appuser
WORKDIR /app
COPY requirements.txt.
RUN pip install --no-cache-dir -r requirements.txt

# Copy source code
COPY main.py.

# Switch to non‑root user
USER appuser

# Expose the port FastAPI will run on
EXPOSE 8000

# Use gunicorn with uvicorn workers (production‑ready)
CMD ["gunicorn", "-k", "uvicorn.workers.UvicornWorker", "main:app", "--bind", "0.0.0.0:8000"]

✅ Verify: Build and run locally.

docker build -t gpt-proxy.
docker run -d -p 8000:8000 -e OPENAI_API_KEY=sk-. gpt-proxy
curl -X POST http://localhost:8000/chat -H "Content-Type: application/json" -d '{"message":"Hello"}'

You should see a JSON reply similar to the earlier curl example.

5️⃣ Prepare Render Configuration

Render can auto‑detect a Dockerfile, but we’ll add a render.yaml for reproducibility.

# Save as: render.yaml
services:
 - type: web
 name: gpt-proxy
 env: docker
 dockerfilePath:./Dockerfile
 plan: free
 autoDeploy: true
 envVars:
 - key: OPENAI_API_KEY
 sync: false # We'll set this manually in the UI

✅ Verify: The file is syntactically correct (YAML lint tools can be used, but not required).

6️⃣ Push to GitHub

git add.
git commit -m "Initial FastAPI + Docker + Render config"
git branch -M main
git remote add origin https://github.com/<YOUR_USERNAME>/gpt-proxy-render.git
git push -u origin main

⚠️ Warning – Never commit your OPENAI_API_KEY. It must stay out of version control.

7️⃣ Deploy on Render

1. Create a Render account (free tier).
2. Click New → Web Service.
3. Connect your GitHub repository (gpt-proxy-render).
4. Render will detect render.yaml and pre‑fill the form.
5. In the Environment tab, add a new variable:
6. Key: OPENAI_API_KEY
7. Value: your secret key
8. Protected: ✅ (keeps it hidden).
9. Click Create Web Service.

Render will build the Docker image, start a container, and give you a live URL like https://gpt-proxy.onrender.com.

8️⃣ Test the Live Endpoint

curl -X POST https://gpt-proxy.onrender.com/chat \
 -H "Content-Type: application/json" \
 -d '{"message":"What is the capital of France?"}'

Expected output (example):

{
 "reply": "The capital of France is Paris."
}

✅ Verify: You receive a JSON response within a few seconds. If you see a 502 or 500 error, proceed to the Troubleshooting section.

📁 Project Files

# Save as:.gitignore
__pycache__/
*.pyc.env

🚀 What You Just Built

• A containerized FastAPI service that talks to OpenAI.
• A free, always‑on web endpoint (https://<your‑app>.onrender.com/chat) reachable from anywhere.
• Secure secret handling via Render’s environment variables.

Your AI agent is now a real product that can be shared, integrated into other apps, or used as a backend for a front‑end UI.

Common Mistakes

Troubleshooting

1. Build fails on Render
2. Check the Build Logs. Common causes: typo in requirements.txt or missing Dockerfile.

3. Ensure the base image (python:3.12-slim) can resolve pip packages (no network restrictions).

4. Endpoint returns 502

5. Verify the OPENAI_API_KEY is correct and not expired.

6. Look at Service Logs for OpenAI error messages (Rate limit exceeded, Invalid API key).

7. Slow responses (>5 s)

8. Free tier on Render has limited CPU; consider upgrading or adding a background worker (e.g., Celery) for heavy loads.

9. Enable OpenAI’s streaming if you need incremental responses (outside this chapter’s scope).

10. CORS errors when calling from a browser

11. Add FastAPI CORS middleware if you plan to call the endpoint from a front‑end:

python from fastapi.middleware.cors import CORSMiddleware app.add_middleware( CORSMiddleware, allow_origins=["*"], # tighten in production allow_methods=["*"], allow_headers=["*"], )

Key Takeaways

• Deployment = Availability. A cloud server makes your code reachable 24/7.
• Docker provides reproducibility. The same image you test locally runs unchanged in the cloud.
• Environment variables keep secrets safe. Never hard‑code API keys.
• Render’s free tier is perfect for prototypes; you can upgrade later without code changes.

You now have a complete, production‑ready pipeline from code to live service.

🧪 Try It Yourself

1. Add a new route that returns the model’s token usage statistics.

   What is a token? A token is how AI models count text. Think of it as a "word piece" — roughly 3-4 characters. "Hello" = 1 token. "Hello world" = 2 tokens. Models have a limit on how many tokens they can process at once (called the "context window").

2. Implement basic rate limiting (e.g., 5 requests per minute per IP) using the slowapi package.

3. Deploy a simple HTML front‑end that calls /chat via JavaScript and host it on the same Render service (static files).

Happy hacking! 🚀

What's Next

Continue to the next chapter to keep building.

Chapter 8

Building Your First Resume Q&A Agent

Why This Matters

Before You Start This Chapter

• Your venv is active (you see `(.

  What is a virtual environment (venv)? It is a separate, isolated Python world for your project. Without it, packages from different projects can conflict. With a venv, each project gets its own clean set of packages. Think of it like a separate browser profile for each website.

venv)in your prompt) - Previous chapter's project is working - Your.env` file has your API key

What is an API? An API (Application Programming Interface) is how one program talks to another. Think of it like a waiter in a restaurant — you (your code) tell the waiter (API) what you want, the waiter goes to the kitchen (the server), and brings back your food (the response). You never talk to the kitchen directly.

• You are in the correct folder (run pwd to check)

Get Your OpenAI API Key

1. Go to https://platform.openai.com/api-keys
2. Log in (free account)
3. Click "Create new secret key"
4. Name it (e.g., "adhikk")
5. Click "Create"
6. Copy the key (starts with sk-) — you will not see it again
7. Paste into your .env file

New accounts get $5 free credit — enough for this entire book.

Create & Activate Virtual Environment

uv venv

Activate (Windows PowerShell):

.venv\Scripts\Activate

Activate (Mac/Linux):

source .venv/bin/activate

How you'll know it worked: Your prompt shows (.venv) at the start.

Large Language Models (LLMs) like OpenAI’s ChatGPT are the backbone of modern AI‑driven applications—chatbots, code assistants, content generators, and more. Understanding how to call an LLM via its API, manage API keys securely, and craft effective prompts is a foundational skill for any developer who wants to build production‑ready AI products.

In this chapter you will learn:

• How to keep secrets (API keys) out of your source code using a .env file.
• How to make a clean, reusable wrapper around the OpenAI Chat Completion endpoint.
• How to experiment with system prompts and prompt engineering to steer the model’s behavior.
• How to stream responses for a more interactive experience.

What You’ll Build

A tiny command‑line utility called ai_assistant.py that:

1. Loads your OpenAI API key from a .env file.
2. Provides a helper function ask_llm() that accepts a user prompt and an optional system prompt.
3. Calls openai.ChatCompletion.create() with streaming enabled, printing the model’s reply in real time.

You’ll end up with a ready‑to‑run project that you can extend into a full‑featured AI assistant, a résumé‑review bot, or any other LLM‑powered tool.

Content

1️⃣ Set Up the Project Structure

ai_project/
├─.env.example
├─ requirements.txt
├─ llm_helper.py
└─ ai_assistant.py

2️⃣ Install Dependencies

pip install -r requirements.txt

requirements.txt

# Save as: requirements.txt
python-dotenv>=1.0.0
openai>=1.30.0

✅ Verify: Running pip install -r requirements.txt should finish without errors.

3️⃣ Create a Template for Your Secrets

.env.example

# Save as:.env.example
# -------------------------------------------------
# Copy this file to.env and fill in your keys.
# NEVER commit the real.env file to version control!
# -------------------------------------------------
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

1. Duplicate the file: cp.env.example.env
2. Replace the placeholder with your actual OpenAI API key.

✅ Verify: cat.env should show the key you just added (but keep this file private).

4️⃣ Load Environment Variables

We’ll use python-dotenv to read the .env file and inject the variables into os.environ.

llm_helper.py

# Save as: llm_helper.py
import os
from typing import List, Dict, Optional

import openai
from dotenv import load_dotenv

# Load.env file – override=True ensures the latest values are used
load_dotenv(override=True)

# Grab the API key from the environment
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
if not OPENAI_API_KEY:
 raise EnvironmentError("OPENAI_API_KEY not found in environment. Check your.env file.")

# Initialise the OpenAI client
client = openai.OpenAI(api_key=OPENAI_API_KEY)

def ask_llm(
 user_prompt: str,
 system_prompt: Optional[str] = "You are a helpful, friendly assistant.",
 model: str = "gpt-3.5-turbo",
 stream: bool = True,
) -> str:
 """
 Send a prompt to the OpenAI chat completion endpoint.

 Parameters
 ----------
 user_prompt : str
 The message you want the model to respond to.
 system_prompt : str, optional
 Sets the model's personality/behaviour. Defaults to a friendly assistant.
 model : str, optional
 Which model to use (e.g., "gpt-3.5-turbo", "gpt-4").
 stream : bool, optional
 If True, prints the response token‑by‑token as it arrives.
> **What is a token?** A token is how AI models count text. Think of it as a "word piece" — roughly 3-4 characters. "Hello" = 1 token. "Hello world" = 2 tokens. Models have a limit on how many tokens they can process at once (called the "context window").



 Returns
 -------
 str
 The full response text (useful when `stream=False`).
 """
 # Build the message list – order matters!
 messages: List[Dict[str, str]] = [
 {"role": "system", "content": system_prompt},
 {"role": "user", "content": user_prompt},
 ]

 # Call the API
 response = client.chat.completions.create(
 model=model,
 messages=messages,
 stream=stream,
 )

 # If streaming, concatenate tokens as they arrive
 if stream:
 full_reply = ""
 for chunk in response:
 # Each chunk may contain a partial delta
 delta = chunk.choices[0].delta
 if "content" in delta:
 token = delta["content"]
 print(token, end="", flush=True)
 full_reply += token
 print() # Newline after the streamed output
 return full_reply
 else:
 # Non‑streaming: the whole answer is in `response.choices[0].message.content`
 return response.choices[0].message.content

✅ Verify: Importing llm_helper in a Python REPL should not raise any exceptions.

>>> from llm_helper import ask_llm
>>> ask_llm("Say hello!")

Expected console output (the exact wording may vary):

Hello! How can I assist you today?

5️⃣ Build the CLI Wrapper

ai_assistant.py

# Save as: ai_assistant.py
import argparse
from llm_helper import ask_llm

def main() -> None:
 parser = argparse.ArgumentParser(
 description="Simple command‑line AI assistant using OpenAI's Chat API."
 )
 parser.add_argument(
 "prompt",
 type=str,
 help="The user message you want the model to answer."
 )
 parser.add_argument(
 "--system",
 type=str,
 default=None,
 help="Optional system prompt to change the model's personality."
 )
 parser.add_argument(
 "--model",
 type=str,
 default="gpt-3.5-turbo",
 help="OpenAI model name (default: gpt-3.5-turbo)."
 )
 args = parser.parse_args()

 # Call the helper; streaming is enabled by default
 ask_llm(
 user_prompt=args.prompt,
 system_prompt=args.system,
 model=args.model,
 stream=True,
 )

if __name__ == "__main__":
 main()

Run the script:

python ai_assistant.py "Give me three bullet‑point tips for a junior developer résumé."

Sample Output

• Highlight measurable achievements (e.g., “Improved page load speed by 30%”).
• Use strong action verbs like “Implemented”, “Designed”, “Optimized”.
• Keep each bullet under 15 words for quick scanning.

✅ Verify: The three bullet points appear exactly as shown (wording may differ slightly but the format should be three concise lines).

📁 Project Files

🚀 What You Just Built

You now have a reusable, secure, and extensible Python utility that:

• Safely loads API credentials from a hidden .env file.
• Encapsulates the OpenAI call in a single function (ask_llm).
• Supports custom system prompts, allowing you to change the model’s “personality” on the fly.
• Streams responses for a more interactive feel.

From here you can:

• Add a conversation history list to give the model context.
• Wrap the CLI in a Flask or FastAPI endpoint for a web service.
• Plug in other LLM providers (e.g., Anthropic, Cohere) by swapping the client logic.

Common Mistakes

💡 Tip: Keep your .env file outside version control (git add.gitignore with a line containing .env).

Troubleshooting

Key Takeaways

• Never hard‑code secrets; use a .env file and python-dotenv.
• System prompts define the model’s persona; experiment to get the desired tone.
• Message order matters – system → user → (assistant).
• Streaming provides a snappy UI but requires a small loop to concatenate tokens.
• A thin wrapper (ask_llm) makes your code DRY and future‑proof for other LLM providers.

🧪 Try It Yourself

1. Change the system prompt to something quirky, e.g., "You are a pirate who loves coding." and observe the pirate‑flavored response.

bash python ai_assistant.py "Explain recursion in two sentences." --system "You are a pirate who loves coding."

1. Add a conversation history: modify llm_helper.py to accept a history: List[Dict] argument and prepend it to messages.

2. Swap models: try "gpt-4" (if you have access) and compare answer quality.

3. Build a tiny web UI with Flask that calls ask_llm behind a /chat endpoint.

Happy coding! 🎉

Why This Matters

Large Language Models (LLMs) are stateless – they only know what you send them in the current request. To build a useful assistant (e.g., a resume‑question‑answering bot) we must:

1. Persist conversation history so the model can “remember” prior turns.
2. Expose tools (Python functions) that the model can invoke when it needs external knowledge (e.g., searching a resume).
3. Wrap everything in a clean, reusable project that a junior developer can run with a single python main.py.

What You'll Build

A Resume Q&A Agent that:

• Loads a plain‑text résumé from resume.txt.
• Keeps a running list of messages (history) and sends the full history to OpenAI on every turn.
• Offers a search tool (search_resume) that the model can call to fetch the most relevant résumé snippet.
• Returns the model’s answer (or the tool’s result) to the user in a friendly console UI.

Content

1️⃣ Project Layout

resume_qa/
│
├─ resume.txt # Your résumé as plain text
├─ utils.py # Helper: load résumé, simple keyword search
├─ tools.py # Function that the LLM can call (search_resume)
└─ main.py # Orchestrates the conversation loop

2️⃣ resume.txt (sample résumé)

Save as: resume.txt ```text Maya Rao Junior AI Developer

Skills: - Python, PyTorch, LangChain - Prompt Engineering, API Integration

Experience: 2023‑Present: AI Intern at TechCorp • Built a chatbot that reduced support tickets by 15% • Implemented function‑calling pipelines with OpenAI

Education: B.Sc. Computer Science, University of Delhi, 2022 ```

3️⃣ utils.py

# Save as: utils.py
import pathlib
from typing import List, Tuple

def load_resume(path: str = "resume.
> **What is PATH?** PATH is a list of folders your computer checks when you type a command. If you type `python`, your computer looks in each PATH folder for a file called `python.exe`. If it finds it, it runs it. If not, you get "command not found." Installing Python with "Add to PATH" checked adds Python's folder to this list.

txt") -> str:
 """
 Reads the résumé file and returns its content as a single string.
 """
 resume_path = pathlib.Path(path)
 if not resume_path.is_file():
 raise FileNotFoundError(f"Résumé not found at {resume_path.resolve()}")
 return resume_path.read_text(encoding="utf-8")

def keyword_search(resume: str, query: str, top_n: int = 3) -> List[Tuple[str, int]]:
 """
 Very naive search: split the résumé into sentences and return the
 `top_n` sentences that contain the most query keywords.
 Returns a list of (sentence, match_score) tuples.
 """
 import re
 sentences = re.split(r'\n|\r\n|\. ', resume)
 query_terms = set(re.findall(r"\w+", query.lower()))
 scored = []
 for s in sentences:
 words = set(re.findall(r"\w+", s.lower()))
 score = len(query_terms & words)
 if score > 0:
 scored.append((s.strip(), score))
 # Sort by score descending, then by original order
 scored.sort(key=lambda x: -x[1])
 return scored[:top_n]

Expected output (when imported): No console output – just helper functions ready for import.

✅ Verify: Run python -c "import utils; print(utils.load_resume()[:30])" – you should see the first 30 characters of the résumé.

4️⃣ tools.py – the function the LLM can call

# Save as: tools.py
from typing import List, Dict
from utils import load_resume, keyword_search

# Load résumé once at import time (cheap for this demo)
_RESUME_TEXT = load_resume()

def search_resume(query: str) -> Dict[str, str]:
 """
 LLM‑callable tool that returns the most relevant résumé snippet(s)
 for a given user query.
 """
 results = keyword_search(_RESUME_TEXT, query)
 if not results:
 return {"answer": "I couldn't find any relevant information in the résumé."}

 # Concatenate top results into a single string
 snippets = "\n".join([f"- {s}" for s, _ in results])
 return {"answer": f"Relevant résumé sections:\n{snippets}"}

Expected output: No direct output; the function is ready for OpenAI function‑calling.

✅ Verify:

from tools import search_resume
print(search_resume("Python"))

You should see something like:

Relevant résumé sections:
- Skills:
- - Python, PyTorch, LangChain
- - Prompt Engineering, API Integration

5️⃣ main.py – the heart of the agent

# Save as: main.py
import os
import json
import openai
from typing import List, Dict
from tools import search_resume

# -------------------------------------------------
# 📦 Configuration
# -------------------------------------------------
# Set your OpenAI API key as an environment variable:
# export OPENAI_API_KEY="sk-."
openai.api_key = os.getenv("OPENAI_API_KEY")
if not openai.api_key:
 raise EnvironmentError("Please set the OPENAI_API_KEY environment variable.")

MODEL = "gpt-4-1106-preview" # Supports function calling
SYSTEM_PROMPT = (
 "You are a helpful AI assistant specialized in answering questions about a candidate's résumé. "
 "When you need factual information from the résumé, call the provided `search_resume` tool."
)

# -------------------------------------------------
# 🧠 Conversation memory (list of message dicts)
# -------------------------------------------------
history: List[Dict[str, str]] = [
 {"role": "system", "content": SYSTEM_PROMPT}
]

# -------------------------------------------------
# 🛠️ Define the function schema for OpenAI
# -------------------------------------------------
function_schema = [
 {
 "name": "search_resume",
 "description": "Search the candidate's résumé for relevant information.",
 "parameters": {
 "type": "object",
 "properties": {
 "query": {
 "type": "string",
 "description": "A short natural‑language query describing what to look for in the résumé."
 }
 },
 "required": ["query"]
 }
 }
]

def ask_llm(messages: List[Dict[str, str]]) -> Dict:
 """
 Sends the full message history to OpenAI and returns the raw response.
 """
 response = openai.ChatCompletion.create(
 model=MODEL,
 messages=messages,
 functions=function_schema,
 function_call="auto", # Let the model decide when to call a function
 temperature=0.2
 )
 return response

def handle_response(response: Dict) -> str:
 """
 Parses the LLM response. If a function call is present, execute it,
 append the function result to history, and make a second LLM call
 to generate the final answer.
 """
 message = response["choices"][0]["message"]

 # 1️⃣ Did the model request a function call?
 if message.get("function_call"):
 func_name = message["function_call"]["name"]
 arguments = json.loads(message["function_call"]["arguments"])
 print(f"\n🤖 LLM wants to call function `{func_name}` with args: {arguments}")

 # 2️⃣ Execute the requested function
 if func_name == "search_resume":
 func_response = search_resume(**arguments)
 else:
 func_response = {"answer": "Function not implemented."}

 # 3️⃣ Append both the LLM request and the function result to history
 history.append(message) # LLM's function call request
 history.append({
 "role": "function",
 "name": func_name,
 "content": json.dumps(func_response)
 })

 # 4️⃣ Make a second LLM call to get the final user‑facing answer
 second_response = openai.ChatCompletion.create(
 model=MODEL,
 messages=history,
 temperature=0.2
 )
 final_message = second_response["choices"][0]["message"]["content"]
 history.append({"role": "assistant", "content": final_message})
 return final_message
 else:
 # No function call – plain answer
 answer = message["content"]
 history.append({"role": "assistant", "content": answer})
 return answer

def main() -> None:
 print("📝 Resume Q&A Assistant – type 'exit' to quit.\n")
 while True:
 user_input = input("You: ").strip()
 if user_input.lower() in {"exit", "quit"}:
 print("👋 Goodbye!")
 break

 # Append user message to history
 history.append({"role": "user", "content": user_input})

 # Call the LLM
 raw_response = ask_llm(history)
 answer = handle_response(raw_response)
 print(f"\nAssistant: {answer}\n")

if __name__ == "__main__":
 main()

Expected console interaction (sample)

📝 Resume Q&A Assistant – type 'exit' to quit.

You: What programming languages does Maya know?

🤖 LLM wants to call function `search_resume` with args: {'query': 'programming languages'}

Assistant: Relevant résumé sections:
- Skills:
- - Python, PyTorch, LangChain
- - Prompt Engineering, API Integration

You: When did Maya start at TechCorp?

🤖 LLM wants to call function `search_resume` with args: {'query': 'TechCorp'}

Assistant: Relevant résumé sections:
- 2023‑Present: AI Intern at TechCorp
- • Built a chatbot that reduced support tickets by 15%
- • Implemented function‑calling pipelines with OpenAI

You: exit
👋 Goodbye!

✅ Verify: 1. Install dependencies: pip install openai python-dotenv. 2. Set your API key: export OPENAI_API_KEY="sk-.". 3. Run python main.py and try the sample questions above.

📁 Project Files

🚀 What You Just Built

• Stateless LLM → Stateful assistant – by persisting history you give the model a “memory”.
• Tool integration – the model can decide when to call search_resume, keeping the user experience seamless.
• Extensible architecture – add more tools (e.g., calendar lookup, calculator) by defining a new function in tools.py and adding its schema to function_schema.

Common Mistakes

Troubleshooting

Key Takeaways

• Memory = message list – the simplest way to give an LLM context.
• Tools = Python functions – expose them via OpenAI’s function‑calling spec.
• Agents = LLM + memory + tools – they can reason, call functions, and iterate toward a goal.
• Keep the prompt short and delegate heavy lifting (search, calculations) to tools.

🧪 Try It Yourself

1. Add a new tool – e.g., calculate_years_experience(start_year: int) -> str.
2. Define the function in tools.py.
3. Add its schema to function_schema.

4. Update handle_response to route the call.

5. Swap the résumé – replace resume.txt with your own CV and ask domain‑specific questions.

6. Implement a simple truncation – modify main.py to keep only the last 8 messages in history before each API call.

Happy coding! 🎉

Why This Matters

In real‑world projects you’ll often need to build a knowledge‑base chatbot that answers questions from a static document (e.g., a résumé, policy, or FAQ). Doing this correctly teaches you:

• How to craft system prompts that constrain a LLM to a single source of truth.
• How to handle “unknown” answers gracefully instead of hallucinating.
• How to batch‑process many queries with a clean Python loop.
• How to securely use the OpenAI API (environment variables, error handling).

What You’ll Build

A stand‑alone CLI tool (resume_qa.py) that:

1. Loads a résumé string (hard‑coded for the demo).
2. Accepts a list of user‑provided questions.
3. Sends each question to the OpenAI Chat Completion endpoint with a system prompt that forces the model to answer only from the résumé.
4. Prints the answer or a polite “I don’t have that information.” message.

You can later replace the hard‑coded résumé with a file read or a database query – the core logic stays the same.

Content

1️⃣ Set up the environment

# Install the official OpenAI Python client
pip install --upgrade openai

2️⃣ Create the Python script

# Save as: resume_qa.py
import os
import json
import openai
from typing import List

# -------------------------------------------------
# 📌 Configuration
# -------------------------------------------------
# The OpenAI API key **must** be stored in an environment variable.
# This keeps secrets out of source control.
# Example (Linux/macOS): export OPENAI_API_KEY="sk-."
# Example (Windows PowerShell): $env:OPENAI_API_KEY="sk-."
openai.api_key = os.getenv("OPENAI_API_KEY")
if not openai.api_key:
 raise RuntimeError("❗ OPENAI_API_KEY environment variable not set.")

# -------------------------------------------------
# 📄 The résumé (static for this demo)
# -------------------------------------------------
RESUME = """
John Doe
Software Engineer with 5+ years of experience in Python, REST APIs, and cloud deployments.
Key Skills:
- Python (advanced)
- FastAPI, Flask
- Docker & Kubernetes
- CI/CD (GitHub Actions)
- AWS (Lambda, S3, DynamoDB)

Projects:
1. **Agent‑Tool Demo** – Built a CLI tool that uses OpenAI’s function‑calling API to act as a personal assistant. Integrated with a simple SQLite DB for note‑taking.
2. **Streamlit Dashboard** – Developed an interactive dashboard for visualising sales data; deployed on Heroku.
3. **API Gateway** – Designed a FastAPI microservice that aggregates data from three third‑party APIs and exposes a unified endpoint.

Education:
- B.Sc. Computer Science, XYZ University (2015‑2019)

Certifications:
- AWS Certified Solutions Architect – Associate
"""

# -------------------------------------------------
# 🛠️ System prompt that forces “resume‑only” answers
# -------------------------------------------------
SYSTEM_PROMPT = """
You are a helpful assistant. Answer the user's question **using ONLY the information provided in the résumé below**.
If the answer cannot be found in the résumé, respond with exactly:
"I don't have that information."
Do NOT fabricate details or make assumptions.
Resume:
{resume}
"""

# -------------------------------------------------
# 🤖 Function to query the model
# -------------------------------------------------
def ask_question(question: str) -> str:
 """Send a single question to OpenAI and return the model's answer."""
 # Build the full system prompt with the résumé injected
 system_message = SYSTEM_PROMPT.format(resume=RESUME.strip())

 try:
 response = openai.ChatCompletion.create(
 model="gpt-3.5-turbo", # Change to a newer model if you have access
 messages=[
 {"role": "system", "content": system_message},
 {"role": "user", "content": question}
 ],
 temperature=0.0, # Deterministic answers
 max_tokens=250,
 )
 answer = response.choices[0].message["content"].strip()
 return answer
 except openai.error.OpenAIError as e:
 # Graceful fallback for API errors
 return f"⚠️ API error: {e}"

# -------------------------------------------------
# 📋 Main driver – loop over a list of questions
# -------------------------------------------------
def main(questions: List[str]) -> None:
 for idx, q in enumerate(questions, start=1):
 print(f"\n🔹 Question {idx}: {q}")
 answer = ask_question(q)
 print(f"💬 Answer: {answer}")

if __name__ == "__main__":
 # Example question list – replace or extend as needed
 sample_questions = [
 "What are John Doe's strongest technical skills?",
 "Which projects involve building an agent?",
 "Does John have a PhD?",
 "What cloud platforms does John know?",
 "Tell me about John’s experience with Docker."
 ]
 main(sample_questions)

Expected output (when run with a valid API key)

🔹 Question 1: What are John Doe's strongest technical skills?
💬 Answer: Python (advanced), FastAPI, Flask, Docker & Kubernetes, CI/CD (GitHub Actions), AWS (Lambda, S3, DynamoDB)

🔹 Question 2: Which projects involve building an agent?
💬 Answer: Agent‑Tool Demo – Built a CLI tool that uses OpenAI’s function‑calling API to act as a personal assistant. Integrated with a simple SQLite DB for note‑taking.

🔹 Question 3: Does John have a PhD?
💬 Answer: I don't have that information.

🔹 Question 4: What cloud platforms does John know?
💬 Answer: AWS (Lambda, S3, DynamoDB)

🔹 Question 5: Tell me about John’s experience with Docker.
💬 Answer: Docker & Kubernetes are listed under John’s key skills, indicating hands‑on experience.

✅ Verify: Run python resume_qa.py after setting OPENAI_API_KEY. The output should match the example above (answers may vary slightly in phrasing but must never invent information).

📁 Project Files

🚀 What You Just Built

You now have a reliable résumé‑aware chatbot that:

• Never hallucinates – it either pulls a fact from the résumé or admits ignorance.
• Scales – you can feed it any number of questions via a loop, a file, or even a web UI.
• Is secure – API keys are read from the environment, not hard‑coded.

You can extend this pattern to:

• Load the résumé from a Markdown or PDF file.
• Cache responses to avoid duplicate API calls.
• Deploy as a FastAPI endpoint for remote consumption.

Common Mistakes

⚠️ Token limit warning – gpt-3.5-turbo has a ~4 k token context window. If your résumé grows beyond ~3 k tokens, you’ll need to implement chunking (out of scope for this chapter but worth exploring).

Troubleshooting

💡 Tip: Print response.usage to see token consumption; this helps you stay within limits.

Key Takeaways

• System prompts are the gatekeeper – they dictate what the model can or cannot say.
• Explicit “I don’t have that information.” phrasing prevents hallucination.
• Zero‑hallucination pipelines are achievable with a simple prompt and deterministic settings.
• Environment‑based secrets keep your code production‑ready.

🧪 Try It Yourself

1. Add a new question to sample_questions that asks about a skill not listed (e.g., “Does John know Rust?”). Verify the model replies with “I don't have that information.”
2. Replace the hard‑coded résumé with a resume.txt file and modify the script to read it at runtime.
3. Create a CSV of 50 interview questions, read them into a list, and batch‑process them with the same script.

Happy coding! 🎉

What's Next

Continue to the next chapter to keep building.

Chapter 9

Building Agents with the OpenAI Agents SDK

Why This Matters

Before You Start This Chapter

• Your venv is active (you see `(.

  What is a virtual environment (venv)? It is a separate, isolated Python world for your project. Without it, packages from different projects can conflict. With a venv, each project gets its own clean set of packages. Think of it like a separate browser profile for each website.

venv)in your prompt) - Previous chapter's project is working - Your.env` file has your API key

What is an API? An API (Application Programming Interface) is how one program talks to another. Think of it like a waiter in a restaurant — you (your code) tell the waiter (API) what you want, the waiter goes to the kitchen (the server), and brings back your food (the response). You never talk to the kitchen directly.

• You are in the correct folder (run pwd to check)

Get Your OpenAI API Key

1. Go to https://platform.openai.com/api-keys
2. Log in (free account)
3. Click "Create new secret key"
4. Name it (e.g., "adhikk")
5. Click "Create"
6. Copy the key (starts with sk-) — you will not see it again
7. Paste into your .env file

New accounts get $5 free credit — enough for this entire book.

Create & Activate Virtual Environment

uv venv

Activate (Windows PowerShell):

.venv\Scripts\Activate

Activate (Mac/Linux):

source .venv/bin/activate

How you'll know it worked: Your prompt shows (.venv) at the start.

Install uv (if not already installed)

Windows (PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

If you get an execution policy error, run first:

Set-ExecutionPolicy RemoteSigned -scope CurrentUser

Mac/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Verify (close and reopen terminal first):

uv --version

AI agents are the next evolution of chatbots. A chatbot simply answers a question, while an AI agent can think, decide, and act—calling tools, fetching data, or even triggering other services before replying. Building a reusable, production‑ready agent framework now means you can:

• Plug the same code into any project (automation, support, data pipelines).
• Keep your dependencies deterministic and isolated.
• Leverage streaming responses for a snappy user experience.
• Write asynchronous code that never blocks your program while the model is thinking.

What You’ll Build

A minimal, zero‑research Python project that:

1. Sets up a reproducible virtual environment with uv.
2. Loads secrets from a .env file.
3. Provides a run_agent function that:
4. Sends a prompt to OpenAI’s gpt‑4o-mini (or any model you configure).

5. Streams the answer token‑by‑token.

   What is a token? A token is how AI models count text. Think of it as a "word piece" — roughly 3-4 characters. "Hello" = 1 token. "Hello world" = 2 tokens. Models have a limit on how many tokens they can process at once (called the "context window").

6. Returns the final text.

7. Demonstrates the difference between a chatbot and an AI agent with a simple “decide‑and‑act” loop.

You’ll end the chapter with a runnable script that prints a streamed answer to the console.

Content

1️⃣ Project Layout

ai-agent/
├─.env # Your OpenAI API key (never commit!)
├─ pyproject.toml # uv‑managed dependencies
├─ uv.lock # Locked versions (auto‑generated)
├─ agent.py # Core agent implementation
└─ main.py # Demo script

2️⃣ Step‑by‑Step Walkthrough

📁 Project Files

1️⃣ pyproject.toml

# Save as: pyproject.toml
[project]
name = "ai-agent"
version = "0.1.0"
description = "A minimal framework for OpenAI‑powered AI agents with streaming."
requires-python = ">=3.10"

[dependency-groups]
default = [
 "openai>=1.30.0",
 "python-dotenv>=1.0.1",
 "rich>=13.7.0",
]

[tool.uv]
# uv will generate uv.lock automatically.

✅ Verify: Run uv lock – it should create uv.lock without errors.

2️⃣ .env.example

# Save as:.env.example
# Copy this file to.env and replace with your own key.
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

⚠️ Never commit the real .env file to version control.

✅ Verify: After copying to .env, run python -c "import os; print(os.getenv('OPENAI_API_KEY'))" – it should print your key (or None if you forgot to set it).

3️⃣ agent.py

# Save as: agent.py
import os
import asyncio
from typing import AsyncGenerator, Optional

import openai
from dotenv import load_dotenv
from rich.console import Console
from rich.live import Live
from rich.text import Text

# ----------------------------------------------------------------------
# Load environment variables once at import time.
# ----------------------------------------------------------------------
load_dotenv() # reads.env in the current working directory

API_KEY = os.getenv("OPENAI_API_KEY")
if not API_KEY:
 raise RuntimeError(
 "OPENAI_API_KEY not found in environment. "
 "Create a.env file (see.env.example) and restart."
 )
openai.api_key = API_KEY

console = Console()


class StreamingAgent:
 """
 Minimal AI agent that streams responses from an OpenAI model.
 """

 def __init__(
 self,
 model: str = "gpt-4o-mini",
 temperature: float = 0.7,
 streaming: bool = True,
 ):
 self.model = model
 self.temperature = temperature
 self.streaming = streaming

 async def _stream_response(
 self, prompt: str
 ) -> AsyncGenerator[str, None]:
 """
 Internal async generator that yields tokens from the model.
 """
 # The `stream=True` flag makes OpenAI return a generator of chunks.
 async for chunk in await openai.ChatCompletion.acreate(
 model=self.model,
 messages=[{"role": "user", "content": prompt}],
 temperature=self.temperature,
 stream=True,
 ):
 # Each `chunk` contains a list of `choices`; we only care about the first.
 delta = chunk.choices[0].delta
 if "content" in delta:
 yield delta["content"]

 async def run(self, prompt: str) -> str:
 """
 Public method that returns the full answer.
 If `self.streaming` is True, it also prints tokens live.
 """
 if not self.streaming:
 # Synchronous fallback – get the whole answer at once.
 response = await openai.ChatCompletion.acreate(
 model=self.model,
 messages=[{"role": "user", "content": prompt}],
 temperature=self.temperature,
 stream=False,
 )
 return response.choices[0].message.content

 # Streaming path – render live output with Rich.
> **What is PATH?** PATH is a list of folders your computer checks when you type a command. If you type `python`, your computer looks in each PATH folder for a file called `python.exe`. If it finds it, it runs it. If not, you get "command not found." Installing Python with "Add to PATH" checked adds Python's folder to this list.


 answer_parts = []
 with Live(console=console, refresh_per_second=10) as live:
 async for token in self._stream_response(prompt):
 answer_parts.append(token)
 live.update(Text("".join(answer_parts)))
 return "".join(answer_parts)


# ----------------------------------------------------------------------
# Helper function for the demo script.
# ----------------------------------------------------------------------
async def run_agent(prompt: str, *, streaming: bool = True) -> str:
 """
 Convenience wrapper that creates an agent and runs it.
 """
 agent = StreamingAgent(streaming=streaming)
 return await agent.run(prompt)

Expected output (when streaming is on): The console will show the answer appearing token‑by‑token, e.g.:

AI agents can think, decide, and act.

✅ Verify: In a Python REPL, run:

import asyncio
from agent import run_agent

asyncio.run(run_agent("Explain the difference between a chatbot and an AI agent."))

You should see a live‑streamed answer.

4️⃣ main.py

# Save as: main.py
import asyncio
from agent import run_agent

PROMPT = """
Explain, in plain English, the difference between a chatbot and an AI agent.
Give a short example of each.
"""

async def main() -> None:
 print("\n=== AI Agent Demo ===\n")
 answer = await run_agent(PROMPT, streaming=True)
 print("\n\n--- Final Answer ---")
 print(answer)

if __name__ == "__main__":
 asyncio.run(main())

Sample console output (your exact wording may vary):

=== AI Agent Demo ===

AI agents can think, decide, and act. (tokens stream)

--- Final Answer ---
A chatbot simply replies to a user’s question. 
Example: “What’s the weather?” → “It’s sunny.”
An AI agent, on the other hand, can decide to call tools, fetch data, or perform actions before answering.
Example: “Book a flight to Paris next Monday.” → The agent checks a calendar, searches flights, books a ticket, then replies with the confirmation.

✅ Verify: From the project root run:

uv run python main.py

You should see the streamed answer followed by the final block.

🚀 What You Just Built

You now have a plug‑and‑play AI agent that you can embed in scripts, web back‑ends, or automation pipelines.

Common Mistakes

Troubleshooting

1. uv not installed – Install it with pip install uv or follow the official docs.
2. Network errors – Verify you have internet access and that your API key is still valid.
3. Rate‑limit errors – Respect OpenAI’s usage limits; add exponential back‑off if you plan heavy traffic.
4. Unicode garble in streaming – Ensure your terminal uses UTF‑8 encoding (export LANG=en_US.UTF-8).

💡 Tip: Wrap the run_agent call in a try/except block to surface openai.APIError messages cleanly.

try:
 answer = await run_agent(prompt)
except openai.APIError as exc:
 console.print(f"[red]OpenAI error:[/red] {exc}")

Key Takeaways

• Virtual environments keep your project reproducible.
• .env files protect secrets and make local testing painless.
• Streaming dramatically improves perceived performance.
• An AI agent is more than a chatbot—it decides, calls tools, and iterates until the task is done.
• Async code lets your program stay responsive while waiting for the model.

🧪 Try It Yourself

1. Add a tool call – Extend agent.py to recognize a special command like "/time" and return the current system time before answering.
2. Swap models – Change self.model to gpt-4o and observe any quality differences.
3. Parallel agents – Spawn two StreamingAgent instances with asyncio.gather to answer two prompts concurrently.

Happy coding! 🎉

Why This Matters

Modern AI agents are only as useful as the tools they can reach. A pure language model can answer questions, but it cannot fetch the latest price of a course, read a live spreadsheet, or trigger a payment gateway. By attaching trusted tools (functions you control) to an LLM, you give the agent real power while keeping the model’s reasoning intact. This chapter shows you how to:

• Turn a plain Python function into a tool the agent can call.
• Register that tool with a simple decorator.
• Stream the agent’s thoughts so you see when and why a tool is invoked.

You’ll finish with a Study Coach that can answer course‑related questions and look up the current fee from a simulated database.

What You’ll Build

A runnable Python project that:

1. Defines a @tool decorator to expose functions to the LLM.
2. Implements a lightweight Agent class that:
3. Sends a user prompt to OpenAI’s ChatCompletion API.
4. Streams the response, printing each event.
5. Detects a function‑call request, executes the registered tool, and feeds the result back.
6. Instantiates a Study Coach agent with a single tool get_course_info.
7. Queries the coach for course details and watches the live streaming output.

All code is self‑contained—just install the dependencies and run python main.py.

Content

1️⃣ Set Up the Project Structure

study_coach/
├─ tools.py # Decorator & registry
├─ agent.py # Agent implementation
└─ main.py # Demo script

2️⃣ Install Required Packages

pip install openai==1.30.0 tqdm

💡 Tip: Keep your OpenAI API key in an environment variable OPENAI_API_KEY for safety.

3️⃣ tools.py – Registering Functions as Tools

# Save as: tools.py
import json
from typing import Callable, Dict, List

# Global registry that the Agent will read
_TOOL_REGISTRY: Dict[str, Callable] = {}

def tool(name: str, description: str, parameters: Dict) -> Callable:
 """
 Decorator to register a Python function as an OpenAI function tool.

 Args:
 name: The name exposed to the LLM.
 description: Human‑readable description of what the tool does.
 parameters: JSON‑Schema describing the function arguments.
 """
 def decorator(func: Callable) -> Callable:
 _TOOL_REGISTRY[name] = {
 "func": func,
 "description": description,
 "parameters": parameters,
 }
 return func
 return decorator

def get_registered_tools() -> List[Dict]:
 """
 Returns the list of tool specifications in the format expected by
 OpenAI's `functions` argument.
 """
 tools = []
 for name, meta in _TOOL_REGISTRY.items():
 tools.append({
 "name": name,
 "description": meta["description"],
 "parameters": meta["parameters"],
 })
 return tools

def call_tool(name: str, arguments: str):
 """
 Executes the registered function with the supplied JSON arguments.
 """
 if name not in _TOOL_REGISTRY:
 raise ValueError(f"Tool '{name}' is not registered.")
 func = _TOOL_REGISTRY[name]["func"]
 args = json.loads(arguments)
 return func(**args)

✅ Verify: The decorator stores each function’s metadata in _TOOL_REGISTRY.

4️⃣ agent.py – The Streaming Agent

# Save as: agent.py
import os
import json
import openai
from typing import List, Dict, Any
from tqdm import tqdm
from tools import get_registered_tools, call_tool

# Ensure the API key is available
openai.api_key = os.getenv("OPENAI_API_KEY")

class Agent:
 """
 Simple wrapper around OpenAI's ChatCompletion that supports:
 * Streaming responses.
 * Automatic function calling using the tools registered via `tools.py`.
 """
 def __init__(self, model: str = "gpt-4o-mini", system_prompt: str = ""):
 self.model = model
 self.system_prompt = system_prompt

 def _build_messages(self, user_input: str) -> List[Dict[str, str]]:
 messages = []
 if self.system_prompt:
 messages.append({"role": "system", "content": self.system_prompt})
 messages.append({"role": "user", "content": user_input})
 return messages

 def run_streamed(self, user_input: str):
 """
 Sends `user_input` to the model and streams the response.
 If the model decides to call a function, the function is executed,
 and the result is sent back to the model for a final answer.
 """
 messages = self._build_messages(user_input)
 tools = get_registered_tools()

 # First request – may result in a function call
 response = openai.ChatCompletion.create(
 model=self.model,
 messages=messages,
 functions=tools,
 stream=True,
 )

 # Stream handling
 collected_chunks = []
 for chunk in tqdm(response, desc="LLM →", unit="chunk"):
 if "choices" not in chunk:
 continue
 delta = chunk["choices"][0]["delta"]
 if "content" in delta:
 print(delta["content"], end="", flush=True)
 collected_chunks.append(delta["content"])
 # Detect a function call request
 if "function_call" in delta:
 func_name = delta["function_call"]["name"]
 arguments = delta["function_call"].get("arguments", "{}")
 # The model may send arguments piece‑by‑piece; accumulate them
 while not arguments.strip().endswith("}"):
 # Grab next chunk for the rest of the arguments
 next_chunk = next(response)
 arg_delta = next_chunk["choices"][0]["delta"]["function_call"]["arguments"]
 arguments += arg_delta
 print("\n\n🔧 Tool call detected:", func_name, "with args:", arguments)
 # Execute the tool
 tool_result = call_tool(func_name, arguments)
 print("✅ Tool result:", tool_result)

 # Send the tool result back to the model for a final answer
 follow_up = openai.ChatCompletion.create(
 model=self.model,
 messages=messages + [
 {"role": "assistant", "content": None, "function_call": {"name": func_name, "arguments": arguments}},
 {"role": "function", "name": func_name, "content": json.dumps(tool_result)},
 ],
 stream=True,
 )
 print("\n🧩 Final answer:")
 for follow_chunk in follow_up:
 delta = follow_chunk["choices"][0]["delta"]
 if "content" in delta:
 print(delta["content"], end="", flush=True)
 print("\n") # newline after final answer
 return # Done

 # If no function call was needed, just print the collected response
 print("\n") # newline after normal answer

✅ Verify: The Agent.run_streamed method prints each token as it arrives, shows when a tool is called, and returns the final answer after the tool’s output is fed back.

5️⃣ main.py – Putting It All Together

# Save as: main.py
from agent import Agent
from tools import tool

# -------------------------------------------------
# 1️⃣ Define the “database” – a simple dict
# -------------------------------------------------
COURSE_CATALOG = {
 "python": {"price": 2000, "duration_hours": 8, "level": "beginner"},
 "data science": {"price": 4500, "duration_hours": 18, "level": "intermediate"},
 "machine learning": {"price": 7500, "duration_hours": 25, "level": "advanced"},
}

# -------------------------------------------------
# 2️⃣ Expose a function as a tool
# -------------------------------------------------
@tool(
 name="get_course_info",
 description="Retrieve price, duration and level for a given course name.",
 parameters={
 "type": "object",
 "properties": {
 "course_name": {
 "type": "string",
 "description": "Name of the course (e.g., 'python', 'data science')."
 }
 },
 "required": ["course_name"],
 },
)
def get_course_info(course_name: str):
 """
 Simulates a database lookup. Returns a dict with course details.
 """
 key = course_name.strip().lower()
 info = COURSE_CATALOG.get(key)
 if not info:
 return {"error": f"Course '{course_name}' not found."}
 return {"course": course_name.title(), **info}

# -------------------------------------------------
# 3️⃣ Create the Study Coach agent
# -------------------------------------------------
system_prompt = (
 "You are a friendly Study Coach. Answer questions about our courses. "
 "If the user asks for price, duration, or level, use the `get_course_info` tool."
)

coach = Agent(model="gpt-4o-mini", system_prompt=system_prompt)

# -------------------------------------------------
# 4️⃣ Demo queries
# -------------------------------------------------
queries = [
 "What is the price of the Python course?",
 "How many hours does the Data Science program last?",
 "Tell me about the Machine Learning course.",
 "Do you have a course on quantum computing?",
]

for q in queries:
 print("\n=== User: " + q + " ===")
 coach.run_streamed(q)

Expected output (truncated for brevity):

=== User: What is the price of the Python course? ===
The Python course costs **₹2000** and runs for **8 hours**. 🎉

=== User: How many hours does the Data Science program last? ===
The Data Science course lasts **18 hours** and is priced at **₹4500**. 📚

=== User: Tell me about the Machine Learning course. ===
The Machine Learning course is an **advanced** level program, runs for **25 hours**, and costs **₹7500**. 🚀

=== User: Do you have a course on quantum computing? ===
🔧 Tool call detected: get_course_info with args: {"course_name":"quantum computing"}
✅ Tool result: {'error': "Course 'quantum computing' not found."}
🧩 Final answer:
Sorry, we don't have a course on quantum computing at the moment.

✅ Verify: Run python main.py and you should see the streaming tokens, the tool‑call logs, and the final answers as shown.

📁 Project Files

🚀 What You Just Built

• A reusable @tool decorator – turn any pure Python function into a callable LLM tool with zero boilerplate.
• A streaming agent that prints each token, highlights when a tool is invoked, and shows the tool’s result.
• A practical Study Coach that can answer static knowledge questions and fetch up‑to‑date course data from a simulated database.

All of this is achieved with under 150 lines of code and no external orchestration.

Common Mistakes

Troubleshooting

Key Takeaways

• Tools = Trust. By exposing only the functions you approve, you keep the LLM’s creativity bounded to safe actions.
• Decorator pattern makes tool registration declarative and reusable across projects.
• Streaming gives you visibility into the agent’s reasoning, which is invaluable for debugging and for building interactive UI experiences.
• The same pattern scales: replace the static dictionary with a real SQL/NoSQL query, a web‑scraper, or any micro‑service, and the agent will call it automatically.

🧪 Try It Yourself

1. Add a new course to COURSE_CATALOG (e.g., "react": {"price": 3000, "duration_hours": 10, "level": "beginner"}) and ask the coach about it.
2. Replace the dictionary with a real SQLite database:
3. Create courses.db with a courses table.
4. Modify get_course_info to execute a SQL query instead of a dict lookup.
5. Expose a second tool, such as list_all_courses, that returns the names of every course. Update the system prompt to encourage the coach to suggest alternatives when a user asks “What should I learn?”.

Happy building! 🎉

Why This Matters

Large‑language‑model (LLM) agents become truly useful when they can call external tools (functions, APIs, or even other agents) and explain why they made each call. In production you’ll often have:

• Multiple tools – a course‑catalog lookup, a payment processor, a sentiment analyzer, etc.
• Agent‑to‑agent collaboration – a “study‑coach” agent may ask a “motivation” agent for a pep‑talk, or a marketing agent may delegate translation to a “translator” agent.

If something goes wrong (e.g., the wrong fee is shown), you need a trace that shows every decision the LLM made, the tool it invoked, the data it sent, and the response it received. This chapter shows you how to:

1. Wrap any function (or another agent) as a tool that the LLM can call.
2. Collect a detailed execution trace automatically.
3. Compose agents so one can call another, while preserving a single, unified trace.

By the end you’ll have a reusable framework you can drop into any Python project and instantly start debugging AI‑driven workflows.

What You’ll Build

A mini‑framework (agent_framework/) that lets you:

✅ Verify: After completing the Project Files section you can run python run_demo.py and see a nicely formatted trace for each query.

Content

1. The Tool Decorator (tool.py)

# Save as: agent_framework/tool.py
import json
from functools import wraps
from typing import Callable, Dict, Any

# Global registry – the Agent will read from here.
TOOL_REGISTRY: Dict[str, Callable] = {}

def tool(name: str, description: str, parameters: Dict[str, Any]):
 """
 Decorator that registers a function as an OpenAI function‑call tool.
 """
 def decorator(func: Callable):
 @wraps(func)
 def wrapper(*args, **kwargs):
 return func(*args, **kwargs)

 # Store OpenAI‑compatible spec + reference
 TOOL_REGISTRY[name] = {
 "func": wrapper,
 "spec": {
 "name": name,
 "description": description,
 "parameters": parameters,
 },
 }
 return wrapper
 return decorator

💡 Tip – Keep the registry in a single module so every Agent instance sees the same set of tools.

2. Trace Collector (trace.py)

# Save as: agent_framework/trace.py
import json
from dataclasses import dataclass, field
from typing import List, Dict, Any

@dataclass
class TraceStep:
 """One step in the execution trace."""
 role: str # "assistant", "tool", "agent"
 content: str # raw text or JSON string
 name: str = "" # tool/agent name (if applicable)
 metadata: Dict[str, Any] = field(default_factory=dict)

 def to_dict(self) -> Dict[str, Any]:
 return {
 "role": self.role,
 "name": self.name,
 "content": self.content,
 "metadata": self.metadata,
 }

@dataclass
class Trace:
 """Full trace for a single `run` call."""
 steps: List[TraceStep] = field(default_factory=list)

 def add(self, step: TraceStep):
 self.steps.append(step)

 def pretty(self) -> str:
 """Human‑readable representation."""
 lines = []
 for i, step in enumerate(self.steps, 1):
 header = f"{i}. [{step.role.upper()}]"
 if step.name:
 header += f" ({step.name})"
 lines.append(header)
 lines.append(step.content)
 lines.append("-" * 40)
 return "\n".join(lines)

 def to_json(self) -> str:
 return json.dumps([s.to_dict() for s in self.steps], indent=2)

✅ Verify: Trace().add(TraceStep(.)) works and pretty() prints a readable log.

3. Base Agent (agent.py)

# Save as: agent_framework/agent.py
import os
import json
import openai
from typing import List, Dict, Any, Optional
from.tool import TOOL_REGISTRY
from.trace import Trace, TraceStep

# Ensure you have set OPENAI_API_KEY in your environment.
openai.api_key = os.getenv("OPENAI_API_KEY")

class Agent:
 """
 Generic LLM agent that can:
 * Load tools from TOOL_REGISTRY.
 * Call the OpenAI ChatCompletion API with function calling enabled.
 * Record a full Trace of the interaction.
 * Optionally treat another Agent as a tool.
 """
 def __init__(self, name: str, system_prompt: str, extra_tools: Optional[List[str]] = None):
 self.name = name
 self.system_prompt = system_prompt
 # Resolve tool specs
 self.tools = [TOOL_REGISTRY[t]["spec"] for t in (extra_tools or []) if t in TOOL_REGISTRY]

 def _call_llm(self, messages: List[Dict[str, str]]) -> Dict[str, Any]:
 response = openai.ChatCompletion.create(
 model="gpt-4o-mini", # Adjust as needed
 messages=messages,
 tools=self.tools or None,
 tool_choice="auto",
 )
 return response["choices"][0]["message"]

 def run(self, user_query: str) -> Trace:
 trace = Trace()
 # 1️⃣ Initial user message
 messages = [
 {"role": "system", "content": self.system_prompt},
 {"role": "user", "content": user_query},
 ]
 trace.add(TraceStep(role="user", content=user_query))

 while True:
 # 2️⃣ LLM turn
 llm_msg = self._call_llm(messages)
 if "function_call" in llm_msg:
 # The model wants to call a tool
 fc = llm_msg["function_call"]
 tool_name = fc["name"]
 arguments = json.loads(fc.get("arguments", "{}"))
 trace.add(TraceStep(role="assistant", content=llm_msg["content"] or "", name=tool_name,
 metadata={"function_call": fc}))

 # 3️⃣ Resolve the tool (could be a plain function or another Agent)
 tool_entry = TOOL_REGISTRY.get(tool_name)
 if not tool_entry:
 raise ValueError(f"Tool '{tool_name}' not registered.")
 result = tool_entry["func"](**arguments)

 # 4️⃣ Record tool response
 tool_content = json.dumps(result, ensure_ascii=False)
 trace.add(TraceStep(role="tool", content=tool_content, name=tool_name))

 # 5️⃣ Feed tool result back to LLM
 messages.append({
 "role": "assistant",
 "content": llm_msg.get("content", ""),
 "function_call": fc,
 })
 messages.append({
 "role": "function",
 "name": tool_name,
 "content": tool_content,
 })
 continue # Loop back for another LLM turn

 # No function call → final answer
 final_answer = llm_msg.get("content", "")
 trace.add(TraceStep(role="assistant", content=final_answer))
 break

 return trace

⚠️ Warning – The run loop will continue until the model stops requesting a function. If you accidentally create a circular tool call, the loop will never exit. Keep your tool set small and well‑named.

4. Course Information Tool (course_tools.py)

# Save as: agent_framework/course_tools.py
from.tool import tool

# Simulated static catalog – replace with a DB call in real projects.
COURSE_CATALOG = {
 "AI agents": {"price": 3500, "duration": "12h", "level": "beginner"},
 "Data Science": {"price": 4200, "duration": "16h", "level": "intermediate"},
 "Full Stack": {"price": 5000, "duration": "20h", "level": "advanced"},
}

@tool(
 name="get_course_info",
 description="Retrieve price, duration and difficulty level for a given course name.",
 parameters={
 "type": "object",
 "properties": {
 "course_name": {"type": "string", "description": "Exact name of the course"},
 },
 "required": ["course_name"],
 },
)
def get_course_info(course_name: str) -> dict:
 # In a real system this would query a database or external API.
 info = COURSE_CATALOG.get(course_name, {})
 return {"course_name": course_name, **info}

✅ Verify: get_course_info("AI agents") returns the expected dict.

5. Motivation Agent (Agent‑as‑Tool)

# Save as: agent_framework/motivation_agent.py
import random
from.agent import Agent
from.trace import TraceStep

MOTIVATIONAL_QUOTES = [
 "Keep pushing forward – every step counts!",
 "Your effort today builds tomorrow's success.",
 "Believe in yourself; you have what it takes.",
]

class MotivationAgent(Agent):
 def __init__(self):
 super().__init__(
 name="MotivationAgent",
 system_prompt="You are a friendly motivation coach. Return a short pep‑talk.",
 )

 def run(self, user_query: str):
 # Override to return plain text (no trace needed for demo)
 trace = super().run(user_query)
 # The final assistant message already contains the quote.
 return trace

💡 Tip – Because MotivationAgent inherits Agent, it can be registered as a tool just like any function.

6. Registering an Agent as a Tool

# Save as: agent_framework/agent_registry.py
from.tool import TOOL_REGISTRY
from.motivation_agent import MotivationAgent

# Instantiate the sub‑agent once (stateless for this demo)
motivation_agent = MotivationAgent()

def _motivation_wrapper(prompt: str) -> dict:
 """
 Wrapper that makes the MotivationAgent look like a function.
 Returns a dict so the parent trace can store JSON.
 """
 trace = motivation_agent.run(prompt)
 # The last step is the assistant's answer.
 answer = trace.steps[-1].content
 return {"quote": answer}

# Register the wrapper as a tool
TOOL_REGISTRY["motivate_user"] = {
 "func": _motivation_wrapper,
 "spec": {
 "name": "motivate_user",
 "description": "Give a short motivational quote based on the user's mood.",
 "parameters": {
 "type": "object",
 "properties": {
 "prompt": {"type": "string", "description": "User's request for motivation"},
 },
 "required": ["prompt"],
 },
 },
}

✅ Verify: TOOL_REGISTRY["motivate_user"]["func"]("I feel stuck.") returns a dict with a quote.

7. Course Agent (uses get_course_info)

# Save as: agent_framework/course_agent.py
from.agent import Agent

class CourseAgent(Agent):
 def __init__(self):
 super().__init__(
 name="CourseAgent",
 system_prompt=(
 "You are a helpful study‑coach. Answer questions about courses. "
 "If the user asks about price, duration, or level, call the "
 "`get_course_info` tool."
 ),
 extra_tools=["get_course_info"],
 )

8. Translation Agent (Hindi)