Setup: Python, keys, Colab

Setup: Python, keys, Colab#

You need three things. None of them require installing anything on your laptop.

1. A browser that can run the in-page cells#

Every chapter has cells marked ▶ Run. They execute Python in your browser using Pyodide. The first run downloads the runtime (about ten seconds); after that cells run instantly. Chrome, Edge, Firefox, and Safari all work.

Try it now:

import sys
print("Python", sys.version.split()[0], "is running in your browser.")
print(sum(range(1, 101)))

2. A Google account for Colab#

Each chapter has an Open in Colab button. Colab is a free hosted Jupyter notebook. The notebooks call a real model through Lumen, which the in-page cells cannot do without exposing your key.

This walkthrough opens the chapter 1 notebook and adds your Lumen key to Colab’s Secrets panel (step 4 below):

Setting up the Colab notebook · 44 s · captions on · Download the video

3. A Lumen API key#

Lumen is the University of Illinois campus LLM service, run by NCSA. It is free with your Illinois account, so there is nothing to pay for.

Watch it once, then follow the steps. The key in the video is hidden on purpose; yours will be a long string starting with sk_.

Creating a Lumen API key and consenting to glm-5.3-flash · 54 s · captions on · Download the video

Sign in at lumen.ncsa.illinois.edu/chat with your Illinois account.
Open your profile page, scroll down to API key, and create one. Copy it now; it is shown once.
On Lumen’s Models page, open glm-5.3-flash. If it asks you to consent to the model’s use, accept; the key will not work with it until you do.
In Colab, open the Secrets panel (the key icon in the left sidebar), add a secret named LUMEN_API_KEY, paste the key, and enable notebook access.

The chapter 1 notebook reads the key and opens a client with:

import os
from google.colab import userdata
from openai import OpenAI

os.environ["LUMEN_API_KEY"] = userdata.get("LUMEN_API_KEY")
client = OpenAI(
    base_url="https://lumen.ncsa.illinois.edu/v1",
    api_key=os.environ["LUMEN_API_KEY"],
)

Lumen speaks the OpenAI API format, which is why the openai package is used (the next section explains why). The chapter 2 notebooks use LangChain’s ChatOpenAI with the same base_url and key. The model for this workshop is glm-5.3-flash: it is fast, handles tool calls well, and is the one every notebook is tested against. Use it unless a section says otherwise.

Never paste a key into a cell. Never commit one to a repository.

Why the OpenAI SDK#

An SDK (software development kit) is a package of ready-made code for talking to a service. Without one, every model call means writing the web request by hand: the address, the headers, the JSON body, and parsing the reply. With the openai package it is one line, client.chat.completions.create(...), and the reply comes back as a Python object.

/// Before and after · the same Lumen call

Before: without an SDKYou write the web request yourself

5 steps, all yours

Your question"Deere's revenue growth last quarter?"

You write each step

1Type Lumen's full web address

2Put your key in a request header

3Write the request out as JSON text

4Check the reply for errors

5Dig the answer out of nested JSON

Lumenglm-5.3-flash

After: with the OpenAI SDKYou call one function; the package does the rest

1 call, 5 steps done for you

Your question"Deere's revenue growth last quarter?"

One function callThe openai package writes the request

1Web address, set once✓ done for you

2Key, set once✓ done for you

3Request built from Python✓ done for you

4Errors raised, some retried✓ done for you

5Answer as a Python object✓ done for you

Lumenglm-5.3-flash

Before: without an SDKWrite the web request yourself

5 things to get right

import os, requests
LUMEN = "https://lumen.ncsa.illinois.edu/v1"
KEY = os.environ["LUMEN_API_KEY"]

r = requests.post(
    LUMEN + "/chat/completions",1
    headers={"Authorization": f"Bearer {KEY}"},2
    json={"model": "glm-5.3-flash",3
          "messages": [{"role": "user",
              "content": "Deere's growth?"}]},
)
if r.status_code != 200:4
    raise RuntimeError(r.text)
answer = (r.json()["choices"][0]5
          ["message"]["content"])

After: with the OpenAI SDKCall a function; the package writes the request

1 function call

import os
from openai import OpenAI
LUMEN = "https://lumen.ncsa.illinois.edu/v1"
KEY = os.environ["LUMEN_API_KEY"]

client = OpenAI(base_url=LUMEN,1
                api_key=KEY)2
reply = client.chat.completions.create(34
    model="glm-5.3-flash",
    messages=[{"role": "user",
               "content": "Deere's growth?"}],
)
answer = reply.choices[0].message.content5

1The address. Before: the full path to the chat endpoint. After: the base address, set once.
2The key. Before: formatted into a header by hand. After: passed once, as api_key.
3The request. Before: shaped as JSON yourself. After: ordinary Python arguments.
4Errors. Before: you check the status code. After: the SDK raises a clear error, and retries some failures for you.
5The answer. Before: dug out of nested JSON by key names. After: a Python object with named fields.

Both sides send the same request to Lumen and get the same answer back. The SDK writes the request for you. To use a different service, change the address and the key; the rest of the code stays the same.

The package is from OpenAI because OpenAI’s API format became the common standard. Many other providers accept the same requests: open-model servers such as vLLM, cloud platforms such as Azure, and campus services. NCSA’s Lumen is one of them. So the openai package is not tied to OpenAI’s models. Point base_url at Lumen and the same code calls the models NCSA serves; point it somewhere else and nothing else changes. That is why this workshop uses it, and why LangChain’s ChatOpenAI works with Lumen too.

OpenAI also publishes the OpenAI Agents SDK, a separate package built on top of openai for agents that call tools over many steps: the loop chapter 1 writes by hand. This workshop writes that loop itself so you can see every step, but the Agents SDK is worth knowing once you build agents for real.

What an open-source model is, how it differs from a closed one, and how to run one on NCSA’s GPUs are on page 0D.

Logistics#


When	Fridays, 1:30–3:30 pm (session 1 ran 1–3 pm)
Where	Business Instructional Facility (BIF); the room changes, see the schedule
Bring	A laptop, a charger, and the Colab from the previous chapter

Getting help#

Open an issue on the course repository or ask in session.