mlscribe
A CLI tool for creating and managing ML/DS demo documents, with metrics tracking, gate decisions, and JSON artifact emission compatible with the agentic-ml-plugin schema.
Installation
You can run it without installing it first using uvx:
uvx mlscribe --help
Or install it like this, then run mlscribe --help:
uv tool install mlscribe
# or
uv pip install mlscribe
You can also install the Go binary directly:
go install github.com/lawwu/mlscribe@latest
Or run it without installation like this:
go run github.com/lawwu/mlscribe@latest --help
Usage
mlscribe <command> [options]
Core Commands
| Command | Description |
|---|---|
init <file> <title> |
Create a new document |
note <file> [text] |
Append commentary (reads from stdin if no text arg) |
exec <file> <lang> [code] |
Run code, capture output, append both to document |
image <file> <image-path> |
Copy image into doc dir and embed a reference |
pop <file> |
Remove the last block |
verify <file> |
Re-run all code blocks and compare output (exits 1 on mismatch) |
extract <file> |
Emit CLI commands to recreate the document |
ML/DS Commands
| Command | Description |
|---|---|
metrics <file> --json '{...}' |
Append a metrics table block |
gate <file> <name> <PASS|FAIL|SKIPPED> |
Append a gate decision block |
artifact <file> --skill <name> --out-dir <dir> |
Write a JSON artifact file |
Examples
# Create a new document
mlscribe init experiment.md "Model Training Experiment"
# Add a note
mlscribe note experiment.md "Training ResNet-50 on CIFAR-10"
# Run code and capture output
mlscribe exec experiment.md python "print('hello world')"
# Record metrics
mlscribe metrics experiment.md --json '{"accuracy": 0.94, "loss": 0.12}'
# Record metrics with baseline delta
mlscribe metrics experiment.md --json '{"accuracy": 0.94}' --baseline baseline.json
# Record a gate decision
mlscribe gate experiment.md data-quality PASS --decision GO --confidence high
# Emit a JSON artifact compatible with agentic-ml-plugin
mlscribe artifact experiment.md --skill eda --out-dir ./artifacts \
--run-id run-001 --json '{"decision": "GO", "summary": "Data quality good"}'
# Verify all code blocks still produce the same output
mlscribe verify experiment.md
# Extract CLI commands to recreate the document
mlscribe extract experiment.md
Options
exec options:
--workdir <dir>— Working directory for code execution
metrics options:
--json <json>— Metrics as JSON object (or pipe via stdin)--baseline <file>— Baseline metrics file for delta computation
gate options:
--decision GO|NO-GO|CONDITIONAL— Gate decision--confidence high|medium|low— Confidence level--findings <text>— Findings text or JSON
artifact options:
--skill <name>— Skill name (required)--out-dir <dir>— Output directory (required)--run-id <id>— Run ID for artifact correlation--json <json>— Artifact payload JSON (or pipe via stdin)
Supported Languages (exec)
python, python3, bash, sh, zsh, ruby, node, javascript, js, r
Artifact Schema
JSON artifacts match the agentic-ml-plugin base schema (schema_version: "1.0"):
{
"schema_version": "1.0",
"skill_name": "...",
"run_id": "...",
"timestamp": "...",
"decision": "...",
"confidence": "...",
"summary": "...",
"findings": "...",
"next_commands": []
}
Environment
| Variable | Description |
|---|---|
MLSCRIBE_REMOTE_URL |
If set, POST the document to this URL after each write |
Acknowledgements
Inspired by simonw/showboat by Simon Willison.
1 maintainer
Metadata
1 maintainer
Release files for mlscribe 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| mlscribe-0.1.0-py3-none-win_arm64.whl | Python 3 | none | Windows ARM64 | Details |
| mlscribe-0.1.0-py3-none-win_amd64.whl | Python 3 | none | Windows x86-64 | Details |
| mlscribe-0.1.0-py3-none-musllinux_1_2_x86_64.whl | Python 3 | none | Linux musl 1.2+ x86-64 | Details |
| mlscribe-0.1.0-py3-none-musllinux_1_2_aarch64.whl | Python 3 | none | Linux musl 1.2+ ARM64 | Details |
| mlscribe-0.1.0-py3-none-manylinux_2_17_x86_64.whl | Python 3 | none | Linux glibc 2.17+ x86-64 | Details |
| mlscribe-0.1.0-py3-none-manylinux_2_17_aarch64.whl | Python 3 | none | Linux glibc 2.17+ ARM64 | Details |
| mlscribe-0.1.0-py3-none-macosx_11_0_arm64.whl | Python 3 | none | macOS 11.0+ ARM64 | Details |
| mlscribe-0.1.0-py3-none-macosx_10_9_x86_64.whl | Python 3 | none | macOS 10.9+ x86-64 | Details |
Total release size: 27.5 MB
Release files / mlscribe-0.1.0-py3-none-win_arm64.whl
| Download URL | mlscribe-0.1.0-py3-none-win_arm64.whl |
|---|---|
| Size | 3.4 MB |
| Tags | Python 3 Windows ARM64 |
|
SHA-256 checksum How to use checksums |
18c3cb26b82f382f4e4ed5eea253c140302c874ffabbadee3312f9034f09fcdd
|
|
BLAKE2b-256 checksum How to use checksums |
da1ee37cf13a93c05f9f1149ac030248c5ad1b2a74a7d78fcb4662a0eb2eb2fe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 1, 2026.
Transparency logRelease files / mlscribe-0.1.0-py3-none-win_amd64.whl
| Download URL | mlscribe-0.1.0-py3-none-win_amd64.whl |
|---|---|
| Size | 3.6 MB |
| Tags | Python 3 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
7972d90d9e44ce359d05d1262bca2f0239c36699f4006cf68564c8b1bfcf15c7
|
|
BLAKE2b-256 checksum How to use checksums |
f56da04dce451dad8e308089d9ff642404c9b15def28eac47055994285949370
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 1, 2026.
Transparency logRelease files / mlscribe-0.1.0-py3-none-musllinux_1_2_x86_64.whl
| Download URL | mlscribe-0.1.0-py3-none-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 3.4 MB |
| Tags | Linux musl 1.2+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
95d4916318ca0a0d983dae3422fe1ad38dd0d44860e6a616a03193aa745439bb
|
|
BLAKE2b-256 checksum How to use checksums |
105390528a00239283b081c0ba401751c5e6065413ecf1a2162401ad9d368b3d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 1, 2026.
Transparency logRelease files / mlscribe-0.1.0-py3-none-musllinux_1_2_aarch64.whl
| Download URL | mlscribe-0.1.0-py3-none-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 3.3 MB |
| Tags | Linux musl 1.2+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
448d99b58ef59bd51929a472aa4b58598c4c758ffdd6b1c1f976bba05caed7e9
|
|
BLAKE2b-256 checksum How to use checksums |
6a689f9567b85443546c633dc15e3a06c4e51ca63c42bd9a41099731f0b5a499
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 1, 2026.
Transparency logRelease files / mlscribe-0.1.0-py3-none-manylinux_2_17_x86_64.whl
| Download URL | mlscribe-0.1.0-py3-none-manylinux_2_17_x86_64.whl |
|---|---|
| Size | 3.4 MB |
| Tags | Linux glibc 2.17+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
3a03c37e4e1c91246285eddd4cb6c5168aca6208893832fc01647e0d30e7f39f
|
|
BLAKE2b-256 checksum How to use checksums |
16a00e3d58d66dd0eb6b828413223fdf24b90f5fa0a4d7c87bb1e0f26a9e66fc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 1, 2026.
Transparency logRelease files / mlscribe-0.1.0-py3-none-manylinux_2_17_aarch64.whl
| Download URL | mlscribe-0.1.0-py3-none-manylinux_2_17_aarch64.whl |
|---|---|
| Size | 3.3 MB |
| Tags | Linux glibc 2.17+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
ad3455569383c8359b8922a42f9f3209c3dc76c8375711a16f347f657a1d4028
|
|
BLAKE2b-256 checksum How to use checksums |
7aa62132adfe1db963eb6a165f7ddbb00f72838c625acfe8a3d0b8750a8d7338
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 1, 2026.
Transparency logRelease files / mlscribe-0.1.0-py3-none-macosx_11_0_arm64.whl
| Download URL | mlscribe-0.1.0-py3-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 3.4 MB |
| Tags | Python 3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
28aadc1c774818e92d66b5453ccd981584b82f5e8f0d8a279bc9d9f6372a3228
|
|
BLAKE2b-256 checksum How to use checksums |
c80b1c9243abf9282b5e2d7625b403673a88abbd668c3345ba555afc9b59a110
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 1, 2026.
Transparency logRelease files / mlscribe-0.1.0-py3-none-macosx_10_9_x86_64.whl
| Download URL | mlscribe-0.1.0-py3-none-macosx_10_9_x86_64.whl |
|---|---|
| Size | 3.5 MB |
| Tags | Python 3 macOS 10.9+ x86-64 |
|
SHA-256 checksum How to use checksums |
6ae15c12b954b4bf2aac307b08ff02754e838c7899057e779150e1a0315cc60f
|
|
BLAKE2b-256 checksum How to use checksums |
72bca0c6405030dd2f7180fe80a89316003f3cb67dc89a0460985b50a1d42af4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 1, 2026.
Transparency logSecurity for mlscribe 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 8 files in this release have been uploaded with provenance metadata.
Attestation for mlscribe-0.1.0-py3-none-win_arm64.whl
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 1, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
