INFO 5940

Welcome to the INFO 5940 repository. You will complete your work using GitHub Codespaces and save your progress in your own GitHub repository. This guide will walk you through setting up the development environment and running the test notebook.

Getting Started

Step 1: Fork this repository

1. Click the Fork button (top right of this page).
2. This will create a copy of the repo under your own GitHub account.

Forking creates a personal copy of the repo under your GitHub account.

• You can commit, push, and experiment freely.
• Your work stays separate from the official class materials.

Step 2: Set your OpenAI API key

This class uses Cornell's AI API Gateway. See to learn more about the service AI API Gateway.

Your API key will be generated by the teaching staff and shared via Secure File Transfer (SFT). You will receive this in the form of an email. Look for the subject "Secure File Transfer File Received" to find it easily.

Your API key is a secret. Never paste it into a file in this repository — your fork is public, and a committed key is a leaked key.

Instead, store it as a GitHub Codespaces secret. GitHub injects it into the environment automatically, and it never touches the filesystem.

1. Go to github.com/settings/codespaces.
2. Under Codespaces secrets, click New secret.
3. Set:
   • Name: OPENAI_API_KEY
   • Value: the key you received for the class
4. Under Repository access, select your fork of this repository.
5. Click Add secret.

Set the secret before creating your Codespace. If you have already created one, that is fine too. The secret only appears after you rebuild the container, so please make sure to do so by following: Cmd/Ctrl + Shift + P → Codespaces: Rebuild Container.

You do not need to set OPENAI_BASE_URL — the Codespace points it at the Cornell AI API Gateway for you.

Working outside Codespaces? (optional — most students can skip this)

If you run the notebooks on your own machine instead of in a Codespace, there is no Codespaces secret to inject, so use a local .env file:

cp .env.example .env

Then open .env and fill in your key. .env is listed in .gitignore, so it will not be committed.

In a Codespace the secret takes priority — .env is only ever a fallback, so having both is safe.

Step 3: Open your forked repo Codespace

1. Go to your forked repo.
2. Click the green Code button and switch to the Codespaces tab.
3. Select Create Codespace.
4. Wait a few minutes for the environment to finish setting up. The terminal prints ==> Setup complete. when it is done, and warns you if your API key is missing.

Step 4: Verify your environment

Once the Codespace is ready:

1. Open test.ipynb.
2. Click Run All.
3. All four cells should print a ✅, ending with a reply from the model.

The Python 3.11 interpreter is preselected, so you should not need to choose a kernel manually. If VS Code does ask, pick Python 3.11.13.

If a cell fails, its message says what to fix — most often a missing API key (Step 2).

About GitHub Codespaces

Codespaces is a complete software development and execution environment, running in the cloud, with its primary interface being a VSCode instance running in your browser.

Codespaces is not free, but their per-month free quota is generous. Codespaces is free under the GitHub Student Developer Pack.

Codespaces Tips

• Codespaces keep running even when you close your browser (but will time out and stop after a while)
• Unless you're on a free plan, or within your free quota, costs acrue while the codespace is running, whether or not you have it open in your browser or are working on it
• You can control when it's running, and the space it takes up. Check out GitHub's codespaces lifecycle documentation

How the Course Materials Are Organized

Every assignment and in-class notebook lives in its own numbered folder under assignments/, for example assignments/01-chatbot/. Shared data files live in data/.

• Work directly in the files inside the assignment folder. That is where we will look for your work.
• Everything stays on the main branch. You never need to create or switch branches in this course.
• Once we publish an assignment folder we do not change the files in it. If a fix is needed we add a new file or post instructions on Canvas.

Getting Updates from the Class Repository

When we release new material we push it to the class repository. Your fork and your Codespace do not update on their own. Each time we announce an update, follow these steps:

1. Save, commit, and push your work before syncing. Save any files you have edited, then commit and push your changes to your fork. See Saving and Submitting Your Work below. If you have no new work to save or push, continue to the next step.
2. Update your fork on GitHub. Open your fork, click Sync fork near the top of the file list, then Update branch.
3. Pull into your Codespace. In the Codespace, open the Source Control panel in the left sidebar, click the ... menu, and choose Pull. Or run this in the terminal:

   git pull

The new folder appears in your file explorer. That is all that is needed for notebooks, apps, and data files.

When the announcement says "rebuild": we changed the installed packages or the container setup. Pull first, then run Cmd/Ctrl + Shift + P → Codespaces: Rebuild Container. Rebuilding is only needed when we say so.

If git pull refuses because of local changes: you have uncommitted work. Commit and push it first (next section), then pull again.

Saving and Submitting Your Work

Your Codespace is not permanent storage. GitHub deletes a Codespace after 30 days of inactivity, and it can be deleted by accident. The only durable copy of your work is what you push to your fork. Push at the end of every work session.

Your Codespace is already connected to your fork with your GitHub login, so there is nothing to configure. Either of these works:

• Source Control panel (left sidebar): click + next to the changed files to stage them, type a short message, click Commit, then click Sync Changes.
• Terminal:

  git add .
  git commit -m "Finish assignment 1"
  git push

Before your final commit for a notebook assignment, click Run All so the saved outputs show that your notebook ran.

Submitting: follow the instructions posted on Canvas for each assignment. Usually this means pasting the link to your file in your fork on GitHub. Assignments are due at the time listed on Canvas, so push before the deadline.

Your API key is never part of this. It lives in a Codespaces secret, not in a file, and .gitignore blocks .env files. Never paste the key into a notebook or script.

End-of-session checklist

1. Commit and push your work.
2. Stop your Codespace to save your free quota: go to github.com/codespaces, click ... next to your Codespace, and choose Stop codespace.

Running a Streamlit App on Codespaces

1. Open the terminal inside your Codespace.

2. Run the app, giving the path to the file:

   streamlit run assignments/01-chatbot/app.py

   (Replace the path with the actual file for the assignment.)

3. After pressing Enter, Codespaces forwards port 8501 and opens the app in a new browser tab.

   If the tab does not open: go to the Ports tab in the bottom panel, find Streamlit App on port 8501, and click the globe icon to open it.

4. Make changes to your code in the Codespace editor, then click Rerun in the app, or refresh the browser tab.

5. Run one app at a time. Before starting a different app, go back to the terminal and press Ctrl + C to stop the running one. If Streamlit says it is using port 8502, an app is still running on 8501 and the new tab will not open automatically. Stop it and try again.

Troubleshooting

OPENAI_API_KEY is not set The Codespaces secret is missing or was added after this Codespace was created. Check Step 2, then run Codespaces: Rebuild Container from the command palette.

The API call in test.ipynb returns an authentication error The secret exists but the value is wrong or incomplete. Re-enter it at github.com/settings/codespaces, confirm your fork is selected under Repository access, and rebuild.

A package is missing Rerun the setup from the terminal:

bash ./.devcontainer/setup.sh

No Python kernel offered in the notebook Left sidebar → Extensions → confirm Python and Jupyter are installed, then reload the window.

git pull says your local changes would be overwritten You have uncommitted work in a file that was updated. Commit and push your work first, then pull again. If you are stuck, ask a TA before deleting anything.

Streamlit opened on port 8502 instead of 8501 Another Streamlit app is still running. Press Ctrl + C in the terminal running it, then start the new one.

My work disappeared after my Codespace was deleted Anything you pushed is safe in your fork on GitHub. Create a new Codespace from your fork and it will be there. Anything you did not push is gone, which is why you should push at the end of every session.

Never commit your key. .gitignore excludes .env files, but the safest approach is the Codespaces secret above, which never creates a file at all.