Metadata-Version: 2.5
Name: zettcode-monitor
Version: 0.1.0
Summary: A ZettCode plugin: /monitor on|off|export records every model call and exports it as an HTML report
Project-URL: Repository, https://github.com/Chang-LeHung/zettcode/tree/main/plugins/zettcode-monitor
Project-URL: Issues, https://github.com/Chang-LeHung/zettcode/issues
Author: Chang-LeHung
License-Expression: MIT
License-File: LICENSE
Keywords: debugging,llm,monitor,plugin,zettcode
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Software Development :: Debuggers
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: zett-agent<0.3,>=0.2.0
Requires-Dist: zettcode<0.2,>=0.1.11
Description-Content-Type: text/markdown

# zettcode-monitor

A ZettCode plugin. It adds `/monitor`.

- `/monitor` opens a panel in the style of `/statusline`: a **Recording** switch, an **Images** switch and an
  **Export** row. `↑ ↓` moves, `← → space` flips a switch (it applies at once and is remembered), `enter` or `e`
  exports, `esc` closes. The command takes no arguments and has no subcommands.
- Every session starts with recording off.
- Export writes an HTML report to `zettcode-monitor-<id8>.html` in the workspace.
- Images are off by default: a record keeps only an `[image]` marker. Turn **Images** on and the data of images is
  stored and shown in the report (it makes the records much larger, since every turn repeats the whole request).

Each model call stores the full request (system prompt, messages, tools, parameters) and the full response
(text, tool calls, usage), plus its duration and any error. Every turn stores the whole request again, so
messages repeat between calls. Nothing is redacted.

Data lives in `~/.zettcode/monitor/<session-id>/`. `state.json` holds the switches and `calls.jsonl` holds
the calls. The switches are read back when a session is resumed. `ZETTCODE_MONITOR_DIR` changes the root.

## Install

    pip install zettcode-monitor

Install it into the same environment as ZettCode, then restart. With a `uv tool` install:

    uv tool install --force --with zettcode-monitor zettcode

From a checkout of this repository:

    uv tool install --force --with ./plugins/zettcode-monitor zettcode

## Releasing

The version is `__version__` in `src/zettcode_monitor/__init__.py`. Set it, commit, then tag and push:

    git tag monitor-v0.1.0
    git push origin monitor-v0.1.0

`.github/workflows/release-monitor.yml` checks the tag against the version, runs the tests, builds, and publishes with
the same `PYPI_API_TOKEN` secret as zettcode. The `monitor-v*` tag is separate from zettcode's `v*` tag. The first
publish needs the `zettcode-monitor` project name to be free on PyPI.

## Test

Run this from `plugins/zettcode-monitor`:

    PYTHONPATH=src <zettcode-venv>/bin/python -m pytest tests

This package is not a member of the root uv workspace, so `make check` does not cover it.
