Skip to main content

Build a Lab Onboarding Assistant CLI

Level: Beginner · Time: 35–45 min · Category: API app

Tags: Python · LLM API · CLI

Use the RC OpenAI-compatible API inside a small Python CLI that answers questions from local lab notes.

This tutorial is about using the API from inside an application. You will build a local CLI that loads a markdown knowledge file, sends it to the chat completions endpoint, and prints a grounded answer.

Prerequisites​

  • LLM API Guide — create an API key, choose a model ID, and test the endpoint.
  • Python SDK setup — review the OpenAI SDK and base URL pattern.
  • Sample lab notes — download a small markdown knowledge file for the assistant.

Confirm Python 3 and pip are available before you start:

python3 --version      # expect 3.9 or newer
python3 -m pip --version

If Python is not found, install it from python.org. On the supercomputer, load a Python module instead (for example module load python), then run the checks again.

What you will do​

  • Create a Python CLI workspace with the OpenAI SDK.
  • Load a local markdown file as application context.
  • Call the RC OpenAI-compatible chat completions endpoint from the app.
  • Test grounded answers and improve the CLI with one focused feature.

Build it step by step​

1. Create the CLI workspace​

Install the SDK, environment loader, and terminal formatting package. The app stays local and uses your API key from environment variables.

mkdir lab-onboarding-assistant
cd lab-onboarding-assistant
python3 -m venv .venv
source .venv/bin/activate
pip install openai python-dotenv rich
Keep this out of Git

If you track this project with Git, do not commit your virtual environment or any secrets. Create a .gitignore file in the project folder with at least these lines:

.gitignore
.venv/
.env
__pycache__/

.venv/ is large and specific to your machine, and .env holds your API key — neither belongs in a shared repository. New to Git? See Track a New Project with Git.

2. Add API connection values​

Your program needs three values to reach the API: your API key, the gateway URL, and a model ID. You keep them in a small text file named .env so they stay out of your code — and out of Git.

What is a .env file, and where does it go?

A .env ("dot-env") file is a plain text file that stores settings as NAME=value lines, one per line. Programs read it at startup so you never have to paste secrets like API keys directly into your code.

  • The filename is literally .env — a leading dot with nothing before it (not config.env or .env.txt).
  • It goes in your project folder: the same directory you just created, where the .venv lives and where you run your commands.
  • The python-dotenv package loads it with load_dotenv(), which looks for .env in the folder you run the program from.
  • Because it holds a secret, never commit it to Git (see the note below).

Create a new file named .env in your project folder — in VS Code use File → New File, or run code .env in the terminal — then paste these three lines and replace the placeholders:

.env
OPENAI_API_KEY="paste-your-key-here"
OPENAI_BASE_URL="https://openai.rc.asu.edu/v1"
RC_LLM_MODEL="paste-model-id-here"
Where do the values come from?

Get your API key and a valid model ID from the LLM API guide. The OPENAI_BASE_URL above is already correct for the Research Computing gateway.

  • Use the /v1 base URL, not the full /chat/completions URL, for the Python SDK.
  • Use a model ID that appears in the portal model list for your account.
  • Keep .env out of Git: add a line containing .env to your .gitignore (see Track a New Project with Git).

3. Download the sample lab notes​

The first version uses a small markdown file as its knowledge source. This keeps the API pattern clear before adding search, embeddings, or a database.

curl -L -o lab-onboarding-notes.md https://docs.rc.asu.edu/tutorials/lab-onboarding-notes.md

4. Ask for the first assistant​

A strong API-app prompt names the SDK, environment variables, input file, CLI behavior, and the boundaries around grounded answers.

You are helping me build a beginner Python CLI that uses an OpenAI-compatible chat API.

Project goal:
- Build a local command-line assistant named lab_assistant.py.
- It should read lab-onboarding-notes.md from the current folder.
- It should answer a user's question using the notes as context.
- It should call the chat completions API through the OpenAI Python SDK.
- It should read OPENAI_API_KEY, OPENAI_BASE_URL, and RC_LLM_MODEL from a .env file or shell environment.

Behavior:
- Command: python lab_assistant.py "How do I get help with a failed job?"
- The assistant should answer only from the provided notes.
- If the notes do not contain the answer, say that the notes do not cover it.
- Include a short "Sources checked" line with the headings that seemed relevant.
- Add friendly errors for missing API key, missing model, missing notes file, or API request failure.

Constraints:
- Use openai, python-dotenv, argparse, pathlib, and rich.
- Keep the first version in one file named lab_assistant.py.
- Do not add a database, web server, or embeddings yet.

Please:
1. Create lab_assistant.py.
2. Explain how the API request is assembled.
3. Show the commands to run three test questions.

5. Run API-backed test questions​

Run a few questions that should be answerable from the notes. If the model answers a question that is not in the notes, tighten the system prompt before adding features.

python lab_assistant.py "How do I get help with a failed job?"
python lab_assistant.py "Where should I put temporary analysis output?"
python lab_assistant.py "Who approves a new group member?"

6. Add one useful product feature​

Once the API call works, ask for a narrow improvement that makes the tool more useful without changing the architecture.

Please add one focused feature to the lab assistant CLI:

Feature:
- Add a --save answer.md option that writes the question, answer, model name, and timestamp to a markdown file.

Constraints:
- Keep the default terminal output unchanged when --save is not provided.
- Do not store the API key in the saved file.
- Keep the code beginner-readable.
- Explain how to test the new option.

More prompts to try​

  • Add a --show-prompt flag that prints the system and user messages without sending an API request.
  • Add a --model option that overrides RC_LLM_MODEL for a single run.
  • Review this CLI for places where it could accidentally leak the API key in logs or saved output.

Troubleshooting​

  • If python-dotenv is missing, activate the virtual environment and run pip install openai python-dotenv rich.
  • If the API returns 401, test the same key with the LLM API guide before changing the CLI.
  • If the model name fails, copy a model ID from the AI LLM model list and update RC_LLM_MODEL.
  • If answers invent details, ask the assistant to strengthen the system message and return "not covered in the notes" when context is missing.
  • If the notes become too long, ask for heading-based chunking before adding embeddings or a database.

Next steps​