# mk-python-plus-openai-basics-tutorial

Below is a sample Markdown tutorial you can use in Google Colab. You can copy this content into a new Colab notebook (or a Markdown file) and follow along. The tutorial covers:

1. Python basics and setup in Colab
2. Making a simple text-based call to the OpenAI Responses API
3. Inspecting and exploring the API response object
4. Handling image inputs (via URL and Base64 encoding)
5. Using Structured Outputs to enforce JSON schemas
6. Converting unstructured text (e.g. an academic article) into a structured record (ready for uploading to Airtable)

---

# Python Tutorial for Building with the OpenAI Responses API in Google Colab

Welcome to this step-by-step tutorial where you will learn how to use Python in Google Colab to interact with the OpenAI Responses API. In this tutorial, you’ll start with text generation, explore the response structure, work with image inputs, and finally, structure unstructured text into a record suitable for applications like Airtable.

---

# Python Basics for Complete Beginners

Before diving into the OpenAI API, let's understand some Python fundamentals that will help you make sense of the code examples.

## Python Data Types

Python has several built-in data types that we'll use throughout this tutorial:

### 1. Strings
Strings are text enclosed in quotes (single or double). They represent textual data.

# This is a string
my_name = "Alex"
api_key = "sk-abcd1234"  # Your API key will be a string

### 2. Numbers
Python has integers (whole numbers) and floats (decimal numbers).

# Integer
age = 30

# Float
temperature = 98.6

### 3. Booleans
Boolean values can only be `True` or `False`. They're used for logical operations.

is_beginner = True
has_api_key = False

### 4. Lists
Lists are ordered collections of items, enclosed in square brackets. In JavaScript, these would be called arrays.

# A list of strings
fruits = ["apple", "banana", "cherry"]

# A list of numbers
scores = [85, 92, 78, 90]

# Lists can contain mixed data types
mixed_list = ["hello", 42, True, 3.14]

# Accessing list items (Python uses 0-based indexing)
first_fruit = fruits[0]  # "apple"

### 5. Dictionaries
Dictionaries store key-value pairs, enclosed in curly braces. In JavaScript, these would be called objects.

# A dictionary with string keys and various value types
person = {
    "name": "Alex",
    "age": 30,
    "is_student": False,
    "favorite_colors": ["blue", "green"]
}

# Accessing dictionary values
person_name = person["name"]  # "Alex"

## Variables

Variables are containers for storing data values. In Python, you don't need to declare variable types explicitly:

# Creating variables
name = "Alex"  # String
age = 30       # Integer
height = 5.9   # Float

# You can change a variable's value
name = "Sam"

# You can change a variable's type
age = "thirty"  # Now age is a string, not an integer

## Functions

Functions are blocks of code that perform specific tasks. They help organize code and make it reusable.

### Defining a Function:

def greet(name):
    """This function prints a greeting message."""
    message = f"Hello, {name}!"
    return message

### Calling a Function:

# Call the function and store the result
greeting = greet("Alex")
print(greeting)  # Outputs: Hello, Alex!

# Call the function directly in a print statement
print(greet("Sam"))  # Outputs: Hello, Sam!

## Classes and Methods

Classes are blueprints for creating objects. Objects can have attributes (variables) and methods (functions that belong to the object).

class Person:
    def __init__(self, name, age):  # Constructor method
        self.name = name
        self.age = age
    
    def greet(self):  # Method belonging to the Person class
        return f"Hello, my name is {self.name}!"

# Creating an object from the Person class
alex = Person("Alex", 30)

# Calling a method on the object
greeting = alex.greet()  # "Hello, my name is Alex!"

### Libraries, Modules, and Methods

When you import a library or module in Python, you can use its classes, functions, and methods:

# Importing a library
import math

# Using a function from the library
radius = 5
area = math.pi * math.pow(radius, 2)  # Using math.pi (attribute) and math.pow (method)

When you see code like `client.responses.create()`, this is calling a method named `create` that belongs to the `responses` attribute of the `client` object. Understanding this structure will help when working with the OpenAI API.

## Google Colab-Specific Features

### Mounting Google Drive

In Google Colab, you can access your Google Drive files by mounting your drive. This allows you to save outputs and load files directly:

# Mount your Google Drive to access and save files
from google.colab import drive
drive.mount('/content/drive')

# Create a path to save outputs
output_folder = "/content/drive/My Drive/Colab Notebooks/OpenAI_Tutorial/outputs"  # This is a string variable

### Storing API Keys Securely

Google Colab provides a secure way to handle sensitive information like API keys using `userdata`:

# Securely get your API key without hardcoding it
from google.colab import userdata
OPENAI_API_KEY = userdata.get('OPENAI_API_KEY')  # Gets your API key from userdata storage

To add an API key to userdata:
1. Click on the "🔑" icon in the left sidebar
2. Click "Add new secret"
3. Enter "OPENAI_API_KEY" as the name and your actual key as the value

## Understanding API Calls

When we use the OpenAI API, we're sending a request to OpenAI's servers and getting a response back. This typically involves:

1. Setting up a connection with your API key (a string that identifies you)
2. Creating a structured request (using dictionaries and lists)
3. Receiving and processing the response

Here's a simple example with secure API handling in Colab:

# Import the OpenAI library
from openai import OpenAI
from google.colab import userdata

# Create a client object with your API key (securely stored)
OPENAI_API_KEY = userdata.get('OPENAI_API_KEY')  # Getting API key from userdata
client = OpenAI(api_key=OPENAI_API_KEY)  # Creating an object using the OpenAI class

# Make a request to the API using a method from the client object
# This request is a dictionary with various parameters
response = client.responses.create(
    model="gpt-4o",  # This is a string parameter
    input="Write a one-sentence bedtime story about a unicorn."  # Another string parameter
)

# Access the response data
print(response.output_text)  # Accessing the 'output_text' property of the response object

# Save the response to a file in your Google Drive
with open("/content/drive/My Drive/Colab Notebooks/OpenAI_Tutorial/outputs/story.txt", "w") as f:
    f.write(response.output_text)

The key thing to understand is that when you see something like `client.responses.create()`, you're calling a method named `create` that belongs to the `responses` attribute of the `client` object.

In the next sections, we'll build on these basics as we explore more complex interactions with the OpenAI API.

## 1. Setting Up Your Environment

### Prerequisites

- **Google Colab:** Open [Google Colab](https://colab.research.google.com/) in your browser.
- **Python & pip:** Colab comes with Python pre-installed.
- **API Key:** Obtain your API key from OpenAI.
- **Install the OpenAI SDK:**
Run the following cell in Colab to install the OpenAI Python package (if not already installed):

!pip install openai

### Importing the Library and Setting Your API Key

Create a new cell and add:

from openai import OpenAI

# Replace with your actual API key
OPENAI_API_KEY = "your-api-key-here"
client = OpenAI(api_key=OPENAI_API_KEY)

---

## 2. Making a Basic Text Generation Call

Let’s start by generating a simple text output using the Responses API. We’ll ask the model to write a one-sentence bedtime story about a unicorn.

response = client.responses.create(
    model="gpt-4o",
    input="Write a one-sentence bedtime story about a unicorn."
)

print("Generated Text:")
print(response.output_text)

Run the cell to see the generated output.

---

## 3. Exploring the Response Object

The response object contains more than just the text output. You can inspect its full structure using:

# Print the full JSON structure of the response
print(response.model_dump_json(indent=2))

# Use help() to explore available attributes and methods
help(response)

> **Tip:** The `help(response)` command will show you details about methods like `.output_text` and any other convenience properties.

---

## 4. Handling Image Inputs

The API isn’t limited to text! You can also pass images as inputs. There are two common methods: using a direct image URL and using a Base64-encoded image.

### 4.1 Using an Image URL

response = client.responses.create(
    model="gpt-4o-mini",
    input=[{
        "role": "user",
        "content": [
            {"type": "input_text", "text": "Describe what is in this image."},
            {"type": "input_image", "image_url": "https://example.com/path_to_image.jpg"}
        ]
    }]
)
print("Image Description:")
print(response.output_text)

### 4.2 Using a Base64-Encoded Image

First, define a helper function to encode an image file:

import base64

def encode_image(image_path):
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode("utf-8")

# Example: Replace 'path_to_your_image.jpg' with your image file path in Colab
base64_image = encode_image("path_to_your_image.jpg")

response = client.responses.create(
    model="gpt-4o",
    input=[{
        "role": "user",
        "content": [
            {"type": "input_text", "text": "What is happening in this image?"},
            {"type": "input_image", "image_url": f"data:image/jpeg;base64,{base64_image}"}
        ]
    }]
)
print("Base64 Image Description:")
print(response.output_text)

*Note: For testing in Colab, you can upload an image using the file upload interface.*

---

## 5. Structured Outputs: Enforcing JSON Schemas

Structured Outputs let you instruct the model to return data that adheres to a specific JSON schema. This is especially useful when you want consistent, machine-readable results.

### 5.1 Example: Math Problem as a Step-by-Step JSON

In this example, we ask the model to solve a math problem and return its reasoning as structured JSON.

import json

response = client.responses.create(
    model="gpt-4o-2024-08-06",
    input=[
        {"role": "system", "content": "You are a helpful math tutor. Guide the user through the solution step by step."},
        {"role": "user", "content": "Solve 8x + 7 = -23"}
    ],
    text={
        "format": {
            "type": "json_schema",
            "name": "math_reasoning",
            "schema": {
                "type": "object",
                "properties": {
                    "steps": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "explanation": {"type": "string"},
                                "output": {"type": "string"}
                            },
                            "required": ["explanation", "output"],
                            "additionalProperties": False
                        }
                    },
                    "final_answer": {"type": "string"}
                },
                "required": ["steps", "final_answer"],
                "additionalProperties": False
            },
            "strict": True
        }
    }
)

# Parse and pretty-print the JSON response
math_reasoning = json.loads(response.output_text)
print("Math Reasoning (Structured Output):")
print(json.dumps(math_reasoning, indent=2))

---

## 6. Structuring Unstructured Text for Airtable

Often, you might have unstructured text (e.g., an academic article or website content) that you want to convert into a structured record. This record can then be uploaded to systems like Airtable.

### 6.1 Example: Extracting an Article Record

Imagine you have an academic article with details like title, author, date, and a summary. We can prompt the API to convert unstructured text into a structured JSON record.

article_text = """
Title: The Future of Artificial Intelligence  
Author: Jane Doe  
Date: 2025-03-15  
Content: In this article, we explore the recent advancements in artificial intelligence, examining new techniques in machine learning, the ethics of AI, and its impact on modern society.
"""

response = client.responses.create(
    model="gpt-4o",
    input=[
        {"role": "system", "content": "Extract the key details of the article into a structured record."},
        {"role": "user", "content": article_text}
    ],
    text={
        "format": {
            "type": "json_schema",
            "name": "article_record",
            "schema": {
                "type": "object",
                "properties": {
                    "title": {"type": "string"},
                    "author": {"type": "string"},
                    "date": {"type": "string"},
                    "summary": {"type": "string"}
                },
                "required": ["title", "author", "date", "summary"],
                "additionalProperties": False
            },
            "strict": True
        }
    }
)

article_record = json.loads(response.output_text)
print("Extracted Article Record:")
print(json.dumps(article_record, indent=2))

> **Next Steps:**
> The JSON record output (with keys like `"title"`, `"author"`, `"date"`, and `"summary"`) is now in a structured format. You can use this JSON with Airtable’s API (or any other database) to create or update records.

---

Below is an additional section you can append to your tutorial. This section explains how to use the web search tool, complete with code examples, customization options, and notes on output and limitations.

---

## 7. Using the Web Search Tool

The OpenAI Responses API can be enhanced with a web search tool that lets the model retrieve the latest information from the web before generating its final answer. You can enable this feature by adding the web search tool to the `tools` array in your API request.

### 7.1 Enabling Web Search

To activate web search, simply include a tool object with `"type": "web_search_preview"` in your request. The model will then decide whether to search the web based on your input prompt.

#### Python Example

from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="gpt-4o",
    tools=[{"type": "web_search_preview"}],
    input="What was a positive news story from today?"
)

print("Web Search Output:")
print(response.output_text)

#### JavaScript Example

import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
    model: "gpt-4o",
    tools: [{ type: "web_search_preview" }],
    input: "What was a positive news story from today?"
});

console.log("Web Search Output:");
console.log(response.output_text);

#### cURL Example

curl "https://api.openai.com/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "gpt-4o",
        "tools": [{"type": "web_search_preview"}],
        "input": "what was a positive news story from today?"
    }'

> **Note:** The default tool version is `web_search_preview` (which points to a dated snapshot like `web_search_preview_2025_03_11`). You can force the use of this version via the `tool_choice` parameter for more consistent results.

---

### 7.2 Output and Citations

When web search is used, the API response contains two parts:

1. **Web Search Call:** An output item (with type `web_search_call`) that provides the ID and status of the search.
2. **Message Output:** An output item (with type `message`) that contains:
- The generated text in `message.content[0].text`
- Inline citation annotations in `message.content[0].annotations` (including the URL, title, and location of each cited source).

Example JSON structure:

[
  {
    "type": "web_search_call",
    "id": "ws_67c9fa0502748190b7dd390736892e100be649c1a5ff9609",
    "status": "completed"
  },
  {
    "id": "msg_67c9fa077e288190af08fdffda2e34f20be649c1a5ff9609",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "output_text",
        "text": "On March 6, 2025, several news...",
        "annotations": [
          {
            "type": "url_citation",
            "start_index": 2606,
            "end_index": 2758,
            "url": "https://...",
            "title": "Title..."
          }
        ]
      }
    ]
  }
]

When displaying these results to users, be sure to make inline citations clearly visible and clickable.

---

### 7.3 Customizing User Location

To improve the relevance of search results based on geography, you can provide an approximate user location using fields like `country`, `city`, `region`, and `timezone`.

#### Python Example

from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="gpt-4o",
    tools=[{
        "type": "web_search_preview",
        "user_location": {
            "type": "approximate",
            "country": "GB",
            "city": "London",
            "region": "London"
        }
    }],
    input="What are the best restaurants around Granary Square?"
)

print("Localized Web Search Output:")
print(response.output_text)

#### JavaScript Example

import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
    model: "gpt-4o",
    tools: [{
        type: "web_search_preview",
        user_location: {
            type: "approximate",
            country: "GB",
            city: "London",
            region: "London"
        }
    }],
    input: "What are the best restaurants around Granary Square?"
});
console.log(response.output_text);

---

### 7.4 Customizing Search Context Size

The `search_context_size` parameter lets you control how much context is retrieved during the web search. This setting affects cost, quality, and latency:

- **`high`**: Most comprehensive context (highest cost, slower).
- **`medium`** (default): A balanced approach.
- **`low`**: Minimal context (lowest cost, fastest).

#### Python Example

from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="gpt-4o",
    tools=[{
        "type": "web_search_preview",
        "search_context_size": "low"
    }],
    input="What movie won best picture in 2025?"
)

print("Low Context Web Search Output:")
print(response.output_text)

#### JavaScript Example

import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
    model: "gpt-4o",
    tools: [{
        type: "web_search_preview",
        search_context_size: "low"
    }],
    input: "What movie won best picture in 2025?"
});
console.log(response.output_text);

---

### 7.5 Limitations

Keep the following considerations in mind when using the web search tool:

- **Data Retention:** This tool does not support zero data retention or specific data residency policies.
- **Model Compatibility:** Models like `gpt-4o-search-preview` and `gpt-4o-mini-search-preview` support only a subset of API parameters. Check the model documentation for rate limits and feature details.
- **Token Isolation:** Tokens used by the search tool are independent of the main model’s token usage and are not carried over between turns.
- **Rate Limits:** The web search tool follows tiered rate limits similar to those for the underlying models.

---

By integrating the web search tool, you can empower your application to fetch the latest information—enhancing the responses generated by the model. Use it in combination with text generation, image analysis, and structured outputs to build rich, up-to-date interactive applications.

---

## Conclusion

In this tutorial, you learned how to:

- **Set up a Python environment in Google Colab** and install the OpenAI SDK.
- **Make simple text-based calls** to the OpenAI Responses API.
- **Explore the API response object** to understand its structure.
- **Handle image inputs** using both direct URLs and Base64 encoding.
- **Leverage Structured Outputs** to enforce a JSON schema on model responses.
- **Extract structured records from unstructured text** for integration with external tools (like Airtable).

With these building blocks, you can create sophisticated pipelines that integrate multiple API calls to transform and process data for your applications. Happy coding!

---

Feel free to adjust the examples and expand on each section to match your project’s requirements.