CIT Course Tools

cit-course-tools gives students one small command-line interface for preparing a course workspace, exploring deterministic model scenarios, testing cumulative Python harnesses, and producing consistent lab evidence. It is course-agnostic: the installed package provides the machinery, while the instructor-provided YAML file defines what a particular lab teaches and tests.

The goal is a simple student experience with rigorous behavior underneath. The package manages ports, simulator sessions, graph traversal, evidence, fractional scoring, and current-result reports. It does not download course scenario files, AI models, llama.cpp, or other external software.

Install

Python 3.10 or newer is required.

python -m pip install cit-course-tools

To update later in the semester:

python -m pip install --upgrade cit-course-tools

Start a course workspace

Navigate to the directory you want to use and initialize it once:

cit-course init .

The command creates labs/lab01 through labs/lab12, along with predictable logs, prompts, and results directories for each lab. It preserves existing student files and populated guidance files.

Download each lab's YAML file from the course site and place it in the matching lab directory. cit-course deliberately does not generate or download course YAML files. The package includes only a generic interaction guide and internal regression fixtures; it does not include any course's lab test suites.

Learn the simulator

Start the Model Simulator with the packaged interaction guide in one terminal:

cit-course serve

Leave it running, then start the User Simulator in a second terminal:

cit-course run

The guide introduces the package and its simulator workflow without requiring a downloaded lab file.

Explore a lab scenario

To explore an instructor-supplied lab instead, start its YAML file explicitly:

cit-course serve labs/lab01/lab01.yaml

Then run the User Simulator in a second terminal anywhere inside the same initialized workspace:

cit-course run

The package discovers the active lab automatically. The serve terminal shows model-service activity; the run terminal stays focused on predefined user prompts and Model Simulator responses. The Model Simulator uses port 8081 and the User Simulator uses port 8082 by default.

Run a lab test suite

For an early lab that does not require a student harness:

cit-course test labs/lab01/lab01.yaml

For a cumulative lab implementation in an arbitrarily named Python file:

cit-course test labs/lab03/lab03.yaml --harness labs/lab03/my_lab03.py

The Python file must export one function:

def run_harness(context):
    """Run one complete test-owned interaction session."""

The full suite runs by default. During implementation, rerun only failed, errored, and incomplete steps with:

cit-course test labs/lab03/lab03.yaml \
  --harness labs/lab03/my_lab03.py \
  --continue

Each selectable prompt-response step is worth no more than one point. If three of five required checks pass, that step earns 0.60 / 1.00. Infrastructure errors are reported clearly and excluded from grading.

Every run replaces that lab's current generated files without touching another lab:

labs/lab03/
├── evaluation.md
├── logs/
│   └── evidence.jsonl
└── results/
    └── test-summary.md

evaluation.md is created once and never overwritten. Students complete it in their own words. The evidence trace and test summary are regenerated by the package and are ready to include in the lab submission.

Hardware report

Create or refresh the optional, privacy-conscious hardware report from anywhere inside the workspace:

cit-course specs

It is written to specs/hardware_specs.txt. Review it before sharing it.

Commands

cit-course init     Create or repair the course workspace
cit-course specs    Generate the optional hardware report
cit-course serve    Start the Model Simulator with the guide or a lab YAML file
cit-course run      Start the User Simulator for the active lab
cit-course test     Run the lab suite and replace its current report

Run cit-course --help or cit-course COMMAND --help for options.

Instructor and developer references

• SCENARIO_AUTHORING.md documents the YAML authoring and scoring contract.
• TECHNICAL_SPECIFICATION.md documents components, isolation, evidence, and runtime behavior.
• PUBLISHING.md contains the release checklist.

Run the complete regression suite with:

python -m unittest discover -s tests -v