Metadata-Version: 2.4
Name: cit-ai-model-simulator
Version: 0.5.0
Summary: Deterministic local model-service simulator for CIT courses
Author: Jeffrey Myers II, M.S.
Project-URL: Documentation, https://pypi.org/project/cit-ai-model-simulator/
Keywords: education,simulation,llama.cpp,openai-compatible,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Education
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: jsonschema<5,>=4.23
Requires-Dist: PyYAML<7,>=6.0.2

# CIT AI Model Simulator

The CIT AI Model Simulator is a deterministic local service for CIT courses. It gives students who cannot run an approved local model a hardware-neutral fallback, and it gives students and instructors reproducible conditions for testing model-client behavior. It presents the small OpenAI-compatible HTTP surface used by the course without claiming to be an AI model or a complete `llama.cpp` replacement.

Responses come from versioned scenario state graphs rather than unrestricted text generation. The simulator labels its identity and all simulated timing and token evidence, listens only on the local computer by default, does not execute model-requested tools, and writes append-only evidence logs for debugging and course work.

The current implementation includes the M0/M1 Week 1 server baseline and the first data-driven interaction layer. Later-lab capabilities such as model-emitted tool calls, context shifting, compaction, protected validation, and evaluation reports remain deliberately incremental.

## Install for development

```console
python -m venv .venv-dev
.venv-dev\Scripts\python -m pip install -e .
```

On macOS or Linux, use `.venv-dev/bin/python` instead.

## Start the full simulator experience

The package has three distinct components:

| Component | Invocation or module | Responsibility |
|---|---|---|
| Interaction-graph engine | Internal engine used by `serve` | Load the active YAML scenario, track session state, and select declared transitions and responses |
| Model Simulator | `cit-simulator serve` | Provide the model-compatible and graph-control APIs on port 8081 |
| User Simulator | `cit-simulator run` | Present terminal choices, expose user-input handoff on port 8082, and communicate with the Model Simulator over HTTP |

Start the Model Simulator in the first terminal:

```console
cit-simulator serve
```

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

```console
cit-simulator run
```

The default Model Simulator URL is `http://127.0.0.1:8081`. The default User Simulator URL is `http://127.0.0.1:8082`. `run` does not load a scenario or instantiate a model engine; it creates a session through the Model Simulator's control API and follows the scenario selected by `serve`.

Useful commands:

```console
cit-simulator --help
cit-simulator validate
cit-simulator preview
cit-simulator test
cit-simulator serve --port 8081 --acceleration 20
cit-simulator run
cit-simulator run --harness
```

`cit-simulator run` starts the User Simulator only after it confirms that a compatible Model Simulator is running. It displays numbered choices obtained through the graph-control API, labels the selected message as `User Simulator Prompt:`, sends it to the Model Simulator over HTTP, and visually renders the returned deterministic response beneath `Model Simulator Response:`. Internal session, scenario, option-ID, and graph-state details are hidden unless `--show-details` is used.

The packaged Lab 1 interaction is a guided simulator orientation. Students can explore how predefined prompt choices and simulated responses work, learn the package's principal commands and display options, and finish with a hands-on practice checklist. It does not mention or require system prompts, tools, request packaging, or a student harness.

The two terminals report only their own activity. The `run` terminal reports prompt submission and response receipt as `User Simulator Activity`. The `serve` terminal reports actual model requests, scenario matches, and response statuses as `Model Simulator Activity`. Internal control traffic is omitted from the default Model Simulator log. `--show-details` expands User Simulator information, `--verbose` enables lower-level diagnostics for the invoked component, and `--no-activity` suppresses activity for that component. `--no-animation` disables progressive terminal rendering in the User Simulator.

For later labs, harness mode lets a student implementation poll the User Simulator on port 8082 for the canonical selected prompt, add its own system prompt, history, tools, and response settings, and submit the resulting request to the Model Simulator on port 8081. Later scenarios can reject unexpected packaging with structured, field-level differences.

## Week 1 API

Learner-facing endpoints:

- `GET /health`
- `GET /v1/health`
- `GET /v1/models`
- `POST /v1/chat/completions`
- `POST /v1/chat/completions/input_tokens`

Interaction-engine control endpoints hosted by the Model Simulator:

- `GET /sim/v1/info`
- `POST /sim/v1/sessions`
- `GET /sim/v1/sessions/{id}`
- `GET /sim/v1/sessions/{id}/options`
- `POST /sim/v1/sessions/{id}/select`
- `GET /sim/v1/sessions/{id}/user-input`
- `POST /sim/v1/sessions/{id}/reset`
- `GET /sim/v1/sessions/{id}/evidence`

User Simulator endpoints on port 8082:

- `GET /health`
- `GET /sim/v1/info`
- `GET /sim/v1/sessions/{id}/user-input`

Create a session before a reproducible run:

```console
curl -X POST http://127.0.0.1:8081/sim/v1/sessions \
  -H "Content-Type: application/json" \
  -d "{\"seed\": 49501, \"attempt_number\": 1}"
```

Pass the returned session ID in the `X-CIT-Sim-Session` request header. A chat request without that header receives a newly created session ID in the response header, which is convenient for simple compatibility checks but should not be used for graded multi-request attempts.

## Scenario data

The built-in service baseline, Lab 1 orientation, and later harness-validation scenarios are YAML data packaged separately from both HTTP adapters and the graph engine. `serve` alone selects and loads the scenario; `run` discovers that active scenario through the Model Simulator. Each lab can supply another YAML file without changing the Python implementation:

```console
cit-simulator serve --scenario path/to/scenario.yaml
```

Validate it before use:

```console
cit-simulator validate path/to/scenario.yaml
```

A branching scenario declares its prompt options on transitions. Each option has a short terminal label and one explicit canonical user prompt. The same transition can declare request expectations such as a required system message, minimum history length, required system-prompt phrases, and required tool names. Responses, next states, timing, and context limits remain scenario data as well.

## Evidence and privacy

The server writes one append-only JSON Lines file per session beneath the selected evidence directory. Logs contain structural summaries, counts, identifiers, and hashes rather than raw prompts or credentials. Evidence fields explicitly label the backend as `simulator`, token counts as approximate, and timing as simulated.

Do not treat simulator TTFT, TPS, or token estimates as measurements of a student's hardware or of a real model.

## Specification

The architecture and behavioral authority is [TECHNICAL_SPECIFICATION.md](TECHNICAL_SPECIFICATION.md). The implementation must not silently weaken its observable contract. Features beyond M1 are future milestones unless the changelog states otherwise.
