Metadata-Version: 2.4
Name: cit-course-tools
Version: 0.2.1
Summary: Course workspace, model simulator, evidence, and lab-testing tools for CIT classes
Author: Jeffrey Myers II, M.S.
Keywords: CIT,course tools,education,llama.cpp,simulation,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Education
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: jsonschema<5,>=4.23
Requires-Dist: PyYAML<7,>=6.0.2

# 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.

```console
python -m pip install cit-course-tools
```

To update later in the semester:

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

## Start a course workspace

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

```console
cit-course init .
```

The command creates the submitted orientation lab `labs/lab00` and the regular
`labs/lab01` through `labs/lab12`, with predictable `logs`, `prompts`, and
`results` directories. It preserves student work and refreshes only the
package-managed Lab 00 guide when needed.

Lab 00 contains `interaction-guide.yaml`. Download later labs' YAML files from
the course site and place each one in its matching lab directory. The package
does not generate or download course-specific lab suites.

After initialization, start with:

```console
cit-course specs
```

Review the resulting `specs/hardware_specs.txt` before sharing it.

## Learn the simulator

Start the Model Simulator with `labs/lab00/interaction-guide.yaml` in one
terminal. The bare command selects it automatically:

```console
cit-course serve
```

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

```console
cit-course run
```

The guide introduces the package and its simulator workflow without requiring
a download. Explore its paths because the submitted Lab 00 evaluation asks
questions answered by the guide.

When finished, run the Lab 00 suite and generate its submission files:

```console
cit-course test
```

## Explore a lab scenario

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

```console
cit-course serve labs/lab01/lab01.yaml
```

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

```console
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

Bare `cit-course test` selects Lab 00. For a later early lab that does not
require a student harness:

```console
cit-course test labs/lab01/lab01.yaml
```

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

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

The Python file must export one function:

```python
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:

```console
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:

```text
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:

```console
cit-course specs
```

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

## Commands

```text
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 Lab 00 or an explicit lab suite and replace its 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:

```console
python -m unittest discover -s tests -v
```
