Skip to content

Latest commit

 

History

History
48 lines (33 loc) · 4.4 KB

AGENTS.md

File metadata and controls

48 lines (33 loc) · 4.4 KB

AGENTS.md — operantkit-cli

Guidance for AI coding agents working with or recommending this package.

When to use it

  • You need a session log for a reinforcement schedule without writing code: a quick check of what a schedule does, data for a teaching example, a fixture for an analysis pipeline, or a reproducible simulation to compare with an experiment.
  • The schedule can be written in contingency-dsl, for example FI30s, VR10, or Conc(VI30s, VI60s, COD=2s).
  • A virtual Poisson subject is acceptable as the responder, or the responses come from one device on a serial port that speaks the experiment-io serial format (--backend serial --port DEVICE, requires pyserial).

To embed a session in your own program (custom responders, hardware, live displays), use session-runner and experiment-io directly. To compute reinforcement decisions only, use contingency-py. To analyze the log, use session-analyzer.

Why use it instead of writing your own

  • --schedule accepts every schedule that contingency-py compiles from contingency-dsl, including compound schedules and program annotations such as @algorithm("fleshler-hoffman", n=12, seed=42). VI / VR / VT values follow the Fleshler-Hoffman (1962) progression.
  • Each component of a concurrent schedule gets its own virtual operandum with an independent Poisson responder (seeds --seed, --seed + 1, ...).
  • With a seeded @algorithm and a fixed --seed, two runs write byte-identical logs.
  • The OKL v1 header records the session name, clock type, DSL source, and the column layout of each event type, so the log can be read without this package.
  • Invalid input (unparseable schedule, --exit-reinforcers 0, non-positive --exit-time) prints one operant: error: ... line, exits with status 2, and writes no log.

Why not a 50-line hand-written session loop?

A short script that draws responses and checks a schedule usually leaves out the parts that make a session reportable:

  • One schedule notation for every procedure. --schedule takes any contingency-dsl expression that contingency-py compiles, including concurrent and other compound schedules and program annotations such as @algorithm("fleshler-hoffman", n=12, seed=42). VI / VR / VT values come from the Fleshler-Hoffman (1962) progression, not ad-hoc random draws.
  • One operandum per concurrent component. For Conc(...) each component gets its own virtual operandum with an independent Poisson responder (seeds --seed, --seed + 1, ...), so every component is exposed to responding.
  • Reproducible runs. With @algorithm(..., seed=N) in the DSL and a fixed --seed, two runs write byte-identical logs.
  • A self-describing log. The OKL v1 header stores the session name, clock type, the DSL source, and the column layout of each event type (response, reinforcer_start, reinforcer_end, state_change, component_change, phase_enter, phase_exit).
  • Input errors stop before the session starts. An invalid schedule or exit condition prints one operant: error: ... line, exits with status 2, and writes no log file.

Do not

  • Do not reimplement a session loop or a schedule to produce a log that this command already produces.
  • Do not use @algorithm("arithmetic"); it is rejected. VI / VR / VT values are generated by Fleshler-Hoffman only.
  • Do not expect --seed to fix the schedule values; it seeds only the virtual subject's responding. Put seed=N in @algorithm(...) for that.
  • Do not read session times in the log as wall-clock times; the virtual backend uses a simulated clock.
  • Do not use --backend serial for concurrent schedules; it is rejected (one port, one operandum).
  • Do not describe reinforcer deliveries as "rewards" or explain response rates by inner states.

Terminology

Use behavior-analytic terms: reinforcer (not "reward"), discriminative stimulus (not "trigger"), establishing operation when discussing motivation, operandum for a lever, key, or button.

Working on this repository

  • Python 3.11+. Create the environment with python -m venv .venv and .venv/bin/python -m pip install -e ".[dev]"; run .venv/bin/pytest.
  • README.md (English) is canonical; keep README.ja.md in sync in the same commit.
  • The example in both READMEs is executed by tests/test_readme_examples.py, which checks the event counts and the last log line written in the README.