pretext-sim 0.3.2__tar.gz

pretext_sim-0.3.2/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,json}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

pretext_sim-0.3.2/.env.example

@@ -0,0 +1,9 @@
+# Copy to .env. Flags override these; these override the built-in defaults.
+PRETEXT_BASE_URL=https://api.openai.com/v1
+PRETEXT_MODEL=gpt-4o-mini
+PRETEXT_API_KEY=sk-replace-me
+# PRETEXT_TEMPERATURE=0.7
+# PRETEXT_TIMEOUT=60
+# PRETEXT_RETRIES=3
+# PRETEXT_MAX_TOKENS=2400
+# PRETEXT_SEED=7

pretext_sim-0.3.2/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,38 @@
+name: Bug report
+description: Something in pretext broke or returned the wrong thing
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please redact your API key and anything confidential in pasted output.
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+      description: Include the command, the exit code, and the full error.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: Output of `pretext --version`.
+    validations:
+      required: true
+  - type: input
+    id: endpoint
+    attributes:
+      label: Endpoint and model
+      description: Which provider or proxy, and which model name. No keys.
+  - type: textarea
+    id: profile
+    attributes:
+      label: Profile
+      description: The YAML profile, if the bug depends on it.

pretext_sim-0.3.2/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

pretext_sim-0.3.2/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,22 @@
+name: Feature request
+description: Propose a capability, output format, or prompt change
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What training scenario cannot be run today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposal
+      description: What should pretext do instead? Note the schema or CLI surface if relevant.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered

pretext_sim-0.3.2/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      python:
+        patterns: ["*"]
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly

pretext_sim-0.3.2/.github/pull_request_template.md

@@ -0,0 +1,11 @@
+## What and why
+
+<!-- The problem this solves, not a file list. -->
+
+## Checks
+
+- [ ] `pytest` passes
+- [ ] `ruff check src tests` passes
+- [ ] New behaviour has a test, including the failure path where relevant
+- [ ] No API key, real company name, or personal data leaked into fixtures
+- [ ] Prompt/output changes verified with `--dry-run` or a real endpoint

pretext_sim-0.3.2/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python }}
+          enable-cache: true
+      - run: uv sync --extra dev --locked
+      - run: uv run ruff check src tests
+      - run: uv run ruff format --check src tests
+      - run: uv run mypy
+      - run: uv run pytest --cov=pretext --cov-fail-under=97
+      - run: uv run pretext example -o /tmp/persona.yaml && uv run pretext validate /tmp/persona.yaml
+      - run: uv run pretext generate /tmp/persona.yaml --api-key x --dry-run > /dev/null

pretext_sim-0.3.2/.github/workflows/release.yml

@@ -0,0 +1,69 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+
+      - run: uv sync --extra dev --locked
+
+      - name: Check the tag matches the package version
+        run: |
+          version=$(uv run python -c "import pretext; print(pretext.__version__)")
+          tag="${GITHUB_REF_NAME#v}"
+          if [ "$version" != "$tag" ]; then
+            echo "tag $tag does not match version $version" >&2
+            exit 1
+          fi
+
+      - run: uv run ruff check src tests
+      - run: uv run ruff format --check src tests
+      - run: uv run mypy
+      - run: uv run pytest
+
+      - run: uv build
+
+      - name: Publish the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          notes=$(uv run python scripts/changelog_section.py "$version")
+          gh release create "$GITHUB_REF_NAME" \
+            --title "$GITHUB_REF_NAME" \
+            --notes "$notes" \
+            dist/*
+
+  pypi:
+    needs: release
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pretext-sim
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+
+      - run: uv sync --extra dev --locked
+      - run: uv build
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

pretext_sim-0.3.2/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+build/
+dist/
+*.egg-info/
+.env
+.crush/
+.empryo/
+.coverage

pretext_sim-0.3.2/.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.17.3
+    hooks:
+      - id: ruff
+      - id: ruff-format
+        args: [--check]
+
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: uv run mypy
+        language: system
+        pass_filenames: false
+
+      - id: pytest
+        name: pytest
+        entry: uv run pytest
+        language: system
+        pass_filenames: false

pretext_sim-0.3.2/AGENTS.md

@@ -0,0 +1,177 @@
+# AGENTS.md
+
+CLI that turns a YAML persona into a labeled social-engineering simulation
+(pretext, opening message, escalation path, defender red flags) via any
+OpenAI-compatible chat completions endpoint.
+
+## Setup and commands
+
+```sh
+uv sync --extra dev
+uv run pytest                 # suite is offline, httpx.MockTransport only
+uv run ruff check src tests
+uv run mypy
+uv run pretext --help
+```
+
+`uv` is the only supported installer and `uv.lock` is committed; run tooling through
+`uv run` so CI and your machine resolve the same versions.
+There is no build step and no Makefile. `pytest` must pass with no network and no
+API key, keep it that way.
+
+## Layout and data flow
+
+```
+profile.yaml ──load_profile──> Profile ──prompt.build_payload_messages──> messages
+                                              │
+                        client.Client.generate ──httpx──> /chat/completions
+                                              │
+                        extract_json ──> Simulation.model_validate ──> render.*
+                                              │
+                             rich panel / markdown / json / file
+```
+
+| File | Role |
+| ---- | ---- |
+| `models.py` | `Profile`, `Simulation`, `Settings`; error classes; env/flag/`.env` resolution; YAML + JSON loaders |
+| `prompt.py` | System prompt carrying the JSON schema, and the user prompt |
+| `client.py` | httpx POST, retry policy, JSON extraction, response validation |
+| `render.py` | Rich panels (section-gated), markdown/JSON serializers, `DISCLAIMER` |
+| `docs/` | README demo and social preview (generated), plus the runner guide |
+| `cli.py` | Typer commands: `generate`, `batch`, `validate`, `example`, `config` |
+| `data/example-profile.yaml` | Fictional persona used by `pretext example` and the README |
+
+`tests/fixtures/profiles/` holds four personas covering distinct roles; the prompt
+tests run every one and assert the payload carries the profile fields.
+
+`resolve_settings` is the single place precedence lives: flag, then `PRETEXT_*`
+env, then `./.env`, then `OPENAI_API_KEY`, then defaults. Provider presets live in
+`PROVIDERS` and lose to an explicit `--base-url`; local providers (`LOCAL_PROVIDERS`)
+get the placeholder key `local` so no key is needed. Note `_env` takes the full
+variable name, `pick` adds the prefix. Every new option needs a
+row there, an env name, a CLI flag, and a `Settings` field, else it silently never
+resolves.
+
+`doctor` runs its probes through `Client.list_models` and `Client.ping_json` so they
+stay testable via `MockTransport`; `--full` is the only part that calls `generate`.
+`batch` mirrors `generate`'s endpoint flags, skips `_`-prefixed files, isolates
+per-profile failures, and exits 1 if any profile failed. Keep the summary on stderr
+and never abort the run on the first failure.
+
+## Contract rules
+
+- **stdout is payload, stderr is diagnostics.** The `err` console is
+  `Console(stderr=True)`. Warnings, spinner, `wrote …`, and errors go to stderr so
+  `pretext generate -f json | jq` stays parseable. Rendering goes to `out`.
+  Breaking this is the most likely regression: assert on `result.stdout` vs
+  `result.output` deliberately in tests.
+- **Validate before rendering.** Model output goes through `Simulation` and every
+  output format runs off that object. Never print raw model text or a partially
+  filled panel; a schema failure must raise `APIError` with the pydantic details.
+  `Simulation` forbids extra keys and requires `escalation_path` stages to be
+  exactly `1..n`, so a model that invents a `stage 2` gap fails instead of
+  producing a broken table.
+- **Errors are `PretextError` subclasses** (`ConfigError`, `ProfileError`,
+  `APIError`). The CLI catches them, prints to stderr, exits 1. Do not let raw
+  `httpx` or `ValidationError` escape to the user, and do not catch them per
+  command in a new way.
+- **The persona is the target, not the sender.** The prompt says so explicitly
+  because models default to having the attacker introduce themselves as the
+  persona. The opening must name the sending address or number in the body, since
+  `Subject:`/`From:` header lines are stripped by a validator on
+  `opening_message` (`HEADER_PREFIXES`). Keep that validator if you touch the
+  prompt.
+- **The disclaimer travels with the exercise.** `render.DISCLAIMER` appears in the
+  rich footer, the markdown footer, and the JSON `disclaimer` key. A new output
+  format must include it.
+- **Secrets never print.** `Settings.api_key` is `repr=False`; `pretext config`
+  shows `set`/`missing`. Key must never reach `--format json` or a log line.
+
+## Gotchas
+
+- `Settings` is frozen and `HttpUrl`-typed. `non-https` is a warning, not an error,
+  because local proxies are the main dev path.
+- Retries cover only `{408,409,425,429,500,502,503,504}` and transport errors;
+  `_request` re-enters `_decode` on the last attempt so the final 4xx/5xx detail
+  reaches the user. `Retry-After` is honored to 30s. Don't add retries for 400/401.
+- `extract_json` tolerates code fences, prose, and list-shaped `content` parts
+  because proxies vary. Keep the fallback: endpoints may ignore
+  `response_format: json_object`.
+- Empty model content is an error, not an empty simulation. Overlong artifacts are
+  trimmed to 300 chars in a `mode="before"` validator; constraints run before
+  `mode="after"` validators, so trim early or the run fails.
+- `--dry-run` still resolves settings, so it needs a key; it prints the prompt to
+  stdout via `typer.echo` (unwrapped) and exits 0. `validate` needs no key.
+- File output with the default rich format renders into a `Console.capture()`
+  block; the render must happen inside the `with`, not after it.
+- Typer options use `= typer.Option(None, ...)` defaults; resource resolution
+  happens in the command body, never in the signature. `Channel | None` is written
+  as a string annotation. Enum values are the wire values in the prompt schema,
+  so adding a channel means touching `Channel` and `SYSTEM_PROMPT` together.
+- Profile YAML forbids unknown keys on purpose (typo detection), and optional
+  strings are blank-to-`None`. Tests rely on both.
+- Company `Acme`/`example` and non-HTTPS endpoints trigger warnings; both are
+  benign in tests.
+- Everything in the example profile is fictional. Keep real vendor names out of
+  the prompt's sample output.
+
+## Docs media
+
+`docs/demo.png` comes from `docs/demo.svg`, which is a `Console(record=True)` export
+of `render_simulation` with `sections=("pretext", "opening", "escalation")` over the
+Dana fixture. Convert with `rsvg-convert -z 1.2`, then `magick -trim +repage -strip`.
+Regenerate after any render change or the README advertises stale output.
+`docs/social.png` is a hand-written SVG render; GitHub exposes no REST endpoint for
+the social preview (404 on every version), so it is uploaded in Settings → General.
+
+## Repo hygiene
+
+CI (`.github/workflows/ci.yml`) runs ruff, pytest, and a dry-run smoke on Python
+3.10-3.13; the local equivalents are `ruff check src tests` and `pytest`. Test
+files are exempt from E501, source files are not.
+
+Releasing means bumping `__version__` in `__init__.py` and `version` in
+`pyproject.toml`, adding a `CHANGELOG.md` section (the tag must match the version),
+then tagging `vX.Y.Z`, which triggers `release.yml`. PyPI upload is a second job in
+that same file using trusted publishing (environment `pypi`) and stays red until the
+trusted publisher exists on PyPI. It cannot live in its own workflow: a release
+created with `GITHUB_TOKEN` fires no `release` event. `SECURITY.md` and `CONTRIBUTING.md`
+are user-facing; changes to the schema or CLI need a line there when behaviour moves.
+
+## Tests
+
+`conftest.py` chdirs every test into a fresh temp directory, so the developer's
+real `.env` never leaks into resolution; keep that fixture autouse.
+
+`tests/test_client.py` drives the client through `httpx.MockTransport` and
+monkeypatches `time.sleep`; add cases there rather than hitting the network.
+`tests/test_cli.py` swaps `cli.Client` for a stub, so command behaviour is tested
+without HTTP. Cover the failure path (retry exhaustion, schema violation, bad
+key) whenever you touch the client or schema. `tests/test_models.py` owns
+precedence and validation edge cases.
+
+`--from-file` bypasses the API entirely for rendering work. It accepts our own
+export, a bare simulation, or a chat body, and needs no key; the profile is taken
+from the export or must be passed explicitly. `tests/fixtures/responses/dana.json`
+is a real capture used by the replay and render tests. Keep a fixture in sync when
+you change the schema, or those tests are worthless.
+
+Cross-provider smoke: gpt-4o-mini, gemini-2.5-flash, claude-haiku-4.5,
+llama-3.3-70b, venice-uncensored-1-2 and qwen3-235b-a22b all held the JSON contract.
+Re-check one non-OpenAI model after a prompt change; prose quality varies far more
+than schema adherence. Venice accepts `response_format: json_object` like the rest.
+
+`tests/fixtures/corpus/` holds real outputs from several models, captured with
+`uv run python scripts/capture_corpus.py MODEL`. `tests/test_corpus.py` asserts the
+structural promises (distinct non-adjacent channels, an artifact per stage, openings
+that are written not described). Re-capture after a prompt change and read the diff;
+do not treat the prose as golden.
+
+`sample-output.md` is kept as the quality bar. Prompt changes should be compared
+against it; a run costs well under
+a cent, so use `--usage` and a real endpoint instead of guessing.
+
+Manual end-to-end without a key: run any throwaway HTTP server that returns
+`{"choices":[{"message":{"content":"<json>"}}]}` and point
+`--base-url http://127.0.0.1:PORT/v1` at it. `--dry-run` is the fast check for a
+prompt edit.

pretext_sim-0.3.2/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+All notable changes. This project follows semantic versioning.
+
+## Unreleased
+
+- Distribution renamed `pretext-sim` (the `pretext` name belongs to PreTeXt); the
+  command stays `pretext`
+- PyPI publish workflow on release, via trusted publishing
+
+- `docs/running-an-exercise.md`: authorization, delivery, scoring, debrief
+- Model corpus with structural invariant tests, and clear errors when a thinking
+  model runs out of output budget
+- `schema` dumps the JSON Schema for integrators and drift checks
+- `--provider` preset for openai, openrouter, venice, ollama and lmstudio
+- `doctor` probes config, TLS, reachability, model availability and JSON mode,
+  with `--full` to test schema adherence
+- `batch` generates one exercise per profile in a directory, continuing past failures
+- `--dry-run --out` writes the prompt instead of ignoring `--out`
+- Verified against Venice (venice-uncensored-1-2, qwen3-235b-a22b-instruct)
+
+## 0.3.2
+
+- PyPI upload runs inside the release workflow
+
+## 0.3.1
+
+- PyPI packaging under the `pretext-sim` name
+
+## 0.3.0
+
+- `doctor` diagnoses configuration, TLS, reachability, model availability and JSON
+  mode, with `--full` for schema adherence
+- `batch` generates one exercise per profile and reports failures via the exit code
+- `--provider` preset for openai, openrouter, venice, ollama and lmstudio
+- `schema` dumps the JSON Schema of the output contract
+- `--dry-run --out` writes the prompt
+- Thinking models that exhaust their budget now say so instead of returning empty
+- Long objectives trimmed like artifacts
+- mypy, `ruff format`, a 97% coverage gate and a release workflow in CI
+- `docs/running-an-exercise.md`: authorization, delivery, scoring, debrief
+- Model corpus with structural invariant tests
+
+## 0.2.0
+
+- `--from-file` replays a saved export, bare simulation, or chat body with no API
+  call and no key
+- `--sections` renders a subset of the exercise
+- `--usage` reports token counts on stderr
+- Openings must land on the ask and identify the sender; "sent from X, referencing Y"
+  narration rejected in the prompt
+- Opening-message validator strips `Subject:`/`From:` header lines the model repeats
+- Overlong stage artifacts are trimmed instead of failing the whole run
+- Prompt now forbids the attacker impersonating the persona, requires an in-body
+  sending address, distinct non-adjacent channels, and a new prop per stage
+- Fixture personas, prompt invariant tests, and render tests over a captured response
+- Tests pin terminal width; the suite is deterministic across widths
+- OpenRouter-tested across four models; `uv.lock` committed and Dependabot moved to
+  the `uv` ecosystem
+- Coverage gate at 97% (currently 99%) and fuzz coverage for JSON extraction
+
+## 0.1.0
+
+First release.
+
+- `generate`, `validate`, `example`, and `config` commands
+- YAML profile with strict validation and blank-to-null optionals
+- OpenAI-compatible httpx client with retry/backoff on 429/5xx and transport errors
+- pydantic-validated simulation schema with ordered escalation stages
+- Rich terminal, Markdown, and JSON output; `--out` file export
+- `--dry-run` prints resolved config and the exact prompt, sends nothing
+- Config precedence across flags, `PRETEXT_*` env, `.env`, `OPENAI_API_KEY`
+- Diagnostics on stderr so piped JSON stays clean

pretext_sim-0.3.2/CODE_OF_CONDUCT.md

@@ -0,0 +1,25 @@
+# Code of conduct
+
+## Expected
+
+- Assume good faith. Most disagreements here are about prompt wording or schema
+  shape, not competence.
+- Critique the change, not the person.
+- Make room for people newer to Python, Typer, or red-team work. Explain the why.
+- Keep review turnaround reasonable; a stalled PR should get a note, not silence.
+
+## Not allowed
+
+- Harassment, gatekeeping, or dismissiveness in issues and reviews.
+- Pasted output containing secrets, customer names, or personal data.
+- Claiming a generated pretext is verified when it has not been checked.
+
+## Enforcement
+
+Maintainers may edit, label, or close contributions that ignore this document.
+Repeat problems lead to a block. Escalate by opening an issue mentioning a
+maintainer.
+
+## Scope
+
+Applies to the repository, its issues, its pull requests, and any project chat.

pretext_sim-0.3.2/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing
+
+Thanks for helping. Bugs, prompt quality reports, and new output formats are all
+welcome.
+
+## Setup
+
+```sh
+uv sync --extra dev
+uv run pytest --cov=pretext   # CI fails under 97% coverage
+uv run ruff check src tests
+uv run mypy
+```
+
+The suite is offline: `httpx.MockTransport` in `tests/test_client.py` and a stubbed
+`Client` in `tests/test_cli.py`. Do not add tests that need a key or the network.
+`tests/conftest.py` chdirs every test into a temp directory so your own `.env`
+cannot leak in; keep that isolation.
+
+## Ground rules
+
+- Output must stay validated. Model text is rendered only after it passes
+  `Simulation`, never before.
+- stdout carries the payload, stderr carries diagnostics. `-f json` has to remain
+  pipeable.
+- New config options need all four touch points: `Settings` field, `resolve_settings`
+  precedence row, `PRETEXT_*` env name, CLI flag.
+- A new output format must include `render.DISCLAIMER`.
+- Keep fixtures fictional and free of real company names, domains, and keys.
+- Any prompt change: check `--dry-run` output and, if you have an endpoint, one
+  real generation before opening the PR.
+
+## Hooks
+
+```sh
+uv run pre-commit install    # ruff, mypy, pytest before each commit
+```
+
+## Pull requests
+
+One concern per PR. Describe the training scenario that motivated it. Fill in the
+checklist. If a change alters the JSON schema, say so in the PR and update
+`SYSTEM_PROMPT` and `Simulation` together.
+
+## Commit messages
+
+Present tense, imperative, first line under 72 characters, explaining why the
+change exists. Conventional prefixes (`feat:`, `fix:`, `docs:`) are fine but not
+required.
+
+## Reporting security issues
+
+See `SECURITY.md`. Never paste an API key into an issue.

pretext_sim-0.3.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pretext contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.