Metadata-Version: 2.4
Name: cit-ai-model-simulator
Version: 0.1.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.

This initial `0.1.0` implementation targets the specification's M0/M1 Week 1 baseline. Later-lab capabilities such as structured-output faults, tool orchestration, context shifting, compaction, protected validation, and evaluation reports remain deliberately deferred.

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

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

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

## 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}`
- `POST /sim/v1/sessions/{id}/reset`
- `GET /sim/v1/sessions/{id}/evidence`

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 `lab01-baseline` scenario is YAML data packaged separately from the HTTP adapter and engine. Supply another scenario with:

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

Validate it before use:

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

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

