cit-ai-model-simulator 0.1.0__tar.gz

cit_ai_model_simulator-0.1.0/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 - Unreleased
+
+- Implement the M0/M1 CIT 495 simulator baseline.
+- Add deterministic health, model discovery, synchronous chat, and SSE streaming.
+- Add session creation, reset, approximate token accounting, simulated timing, and JSONL evidence.
+- Add scenario validation, preview, self-test, reset, and evidence CLI operations.
+

cit_ai_model_simulator-0.1.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md
+include CHANGELOG.md
+include TECHNICAL_SPECIFICATION.md
+recursive-include src/cit_ai_model_simulator/scenarios *.yaml
+recursive-include src/cit_ai_model_simulator/schemas *.json
+recursive-include tests *.py
+global-exclude __pycache__ *.py[cod]
+

cit_ai_model_simulator-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+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.
+

cit_ai_model_simulator-0.1.0/README.md

@@ -0,0 +1,87 @@
+# 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.
+