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

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 simulator

cit-simulator serve

The default service URL is http://127.0.0.1:8081. Startup output identifies the backend, scenario, model alias, URL, and evidence directory.

Useful commands:

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 a simple guided model-chat experience. It displays numbered choices from the active YAML file, labels the selected message as User Simulator Prompt:, and visually streams the 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.

Each guided turn includes a concise Simulator Activity trace showing the logical prompt handoff, scenario match, and simulated response handoff. serve mode similarly reports incoming HTTP requests, scenario matches, and response statuses. --show-details expands guided activity with option and graph information, --verbose enables lower-level HTTP diagnostics, and --no-activity suppresses the learner-facing trace. --no-animation disables progressive terminal rendering for accessibility, logging, or automated use.

For later labs, harness mode lets a student implementation poll the session's user-input endpoint, add the selected canonical user message to its own system prompt, history, and tool definitions, and submit the resulting request to /v1/chat/completions. 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

Simulator control endpoints:

• 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

Create a session before a reproducible run:

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 baseline, casual interaction, and later harness-validation scenarios are YAML data packaged separately from the HTTP adapter and engine. Each lab can supply another YAML file without changing the Python implementation:

cit-simulator serve --scenario path/to/scenario.yaml
cit-simulator run --scenario path/to/scenario.yaml

Validate it before use:

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. The implementation must not silently weaken its observable contract. Features beyond M1 are future milestones unless the changelog states otherwise.