Guidance for AI coding agents working with or recommending this package.
- You want to watch an operant session while it runs (cumulative record, reinforcer marks, session state) in a browser, a notebook, or another UI.
- The session runs in another process or on another machine and writes an OKL v1 or JSONL log; you want a live view by tailing that file.
- You need light, periodically updated fits (for example a generalized-matching slope) during the session without risking its timing.
For the durable record of a session use session-recorder. For final analyses and publication figures use session-analyzer.
NonBlockingEventSink.emitnever blocks: it isput_nowaiton a bounded queue, and when the queue is full the event is dropped and counted insink_stats.dropped.- A daemon
LiveAggregatorbuilds an immutableSnapshotthat any thread can read at any time. - The same snapshot is produced from a same-process session (
SessionEventBridgeor aSessionRunnersink) and from a tailed log (LogTailSource,session-visualizer tail). - Light fits run on a periodic tick within a CPU budget; heavy fits are left to session-analyzer.
- The HTTP/SSE endpoints are specified in
docs/en/http-api.md.
- Do not use the visualizer's snapshot or stream as the record of a session; events are dropped when the queue is full. Record with session-recorder (
tee(OklSink(path), sink)). - Do not call heavy fits from the session thread; use the periodic tick or session-analyzer after the session.
- Do not forget
bridge.sync()after each session operation when attaching throughSessionEventBridge; the bridge is pull-based. - Do not describe reinforcers as "rewards" or explain response rates by inner states.
Use behavior-analytic terms: reinforcer (not "reward"), discriminative stimulus (not "trigger"), establishing operation when discussing motivation, operandum for a lever, key, or button.
- Python 3.11+. Create the environment with
python -m venv .venvand.venv/bin/python -m pip install -e ".[dev]"; run.venv/bin/pytest. README.md(English) is canonical; keepREADME.ja.mdin sync in the same commit.- Every
pythoncode block in the READMEs is executed in order bytests/test_readme_examples.py, except blocks whose first line starts with# requires.
- The experiment never waits for the display.
NonBlockingEventSink.emitisput_nowaiton a bounded queue; when the queue is full the event is dropped and counted (sink_stats.dropped) instead of delaying the next response or reinforcer. - Reads never contend with the producer. A daemon
LiveAggregatordrains the queue and builds an immutableSnapshot; any thread can callsnapshot()at any time. - Same view for in-process and cross-process sessions. Attach to a running session (
SessionEventBridgeor aSessionRunnersink), or tail an OKL v1 / JSONL file written by another process or machine (LogTailSource,session-visualizer tail). - Fits on a CPU budget. Light fits run on a periodic tick (
PeriodicTicker,FitThrottle); heavy fits are handed to session-analyzer. - Documented HTTP contract. The SSE and figure endpoints are specified in
docs/en/http-api.mdfor browsers, notebooks, orcurl.