loopmath 0.0.1__tar.gz → 0.2.0__tar.gz

loopmath-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QKV Labs
+
+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.

loopmath-0.2.0/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: loopmath
+Version: 0.2.0
+Summary: Plan agent workflows, record how they went, and learn from your own Claude Code and Codex logs
+Author: QKV Labs
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/loopmath/loopmath
+Project-URL: Issues, https://github.com/loopmath/loopmath/issues
+Project-URL: Repository, https://github.com/loopmath/loopmath.git
+Keywords: agents,claude code,codex,cost analysis,developer tools,workflow analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Software Development
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jsonschema>=4
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scipy
+Provides-Extra: bayes
+Requires-Dist: pymc>=5; extra == "bayes"
+Requires-Dist: pytensor; extra == "bayes"
+Requires-Dist: arviz; extra == "bayes"
+Requires-Dist: h5netcdf; extra == "bayes"
+Provides-Extra: e0
+Requires-Dist: matplotlib; extra == "e0"
+Dynamic: license-file
+
+# loopmath
+
+loopmath helps an orchestrator agent choose how to run a coding task, and learns from how it went.
+
+Before a task, it predicts how the user's usual agent workflow will do: the chance of an accepted result, and the cost in tokens and dollars. It shows the other workflows on a success-cost curve and offers two exploration picks. Each pick comes with its gain on every future similar run, its one-time price, and the number of runs it takes to pay back. After the task, the orchestrator records what ran and what came of it. loopmath fills in the token costs from the Claude Code and Codex logs, writes a receipt of predicted against actual, and refits.
+
+loopmath never starts or coordinates agents. Claude Code, Codex, herdr or your own tool does that; loopmath is a CLI they call. Everything runs locally. No command opens a network connection, the logs are opened read only, and loopmath writes only to its store (`~/.loopmath`) and to paths you name.
+
+The package installs two commands: `loopmath` and its short alias `loop`. If another `loop` is already on your PATH, use `loopmath`.
+
+## Install
+
+Python 3.11 or newer.
+
+```sh
+pipx install loopmath          # or: uv tool install loopmath, or pip install loopmath in a venv
+loopmath --version
+```
+
+From a clone of this repository:
+
+```sh
+python3 -m venv .venv
+.venv/bin/python -m pip install -e .
+```
+
+## First run
+
+```sh
+loopmath skill install      # teach your coding agents how to use loopmath
+```
+
+Then ask your agent to onboard, for example "onboard loopmath". The agent runs a dry run, asks you one question (which model labels your sessions, with the cost of each option), onboards, fits, and opens the results page.
+
+`skill install` writes six skills, one per job, and a shared `reference.md` with every command and JSON field they use. An agent loads only the skill for the job at hand, and each phrase belongs to one skill:
+
+| Skill | Ask your agent |
+|---|---|
+| `loopmath` | loopmath named without a job: "use loopmath", "what can loopmath do", "what next with loopmath" |
+| `loopmath-onboard` | "onboard", "set up", "start" or "try" loopmath; or loopmath has no runs yet |
+| `loopmath-import-runs` | OCP files (`*.ocp.json`), a folder of finished runs, or the output of an orchestrator or experiment harness that writes OCP |
+| `loopmath-update-fit` | "update", "refresh" or "rerun" the fit; what loopmath learned; runs imported or recorded without a refit |
+| `loopmath-plan-task` | "plan a task with loopmath"; which workflow, model or effort to use; a coding task of more than a few minutes in a repo that uses loopmath |
+| `loopmath-record-run` | a task planned with loopmath is done; "record", "log" or "save" a run; both runs of a pair need a blind judge |
+
+By default the skills go to every agent whose home exists: Claude Code (`~/.claude/skills/<name>/`, or under `$CLAUDE_CONFIG_DIR`) and Codex (`~/.codex/skills/<name>/`, or under `$CODEX_HOME`). `--target claude-code`, `codex` or `both` picks them yourself. If your Codex has no skills folder, the files go to `~/.codex/loopmath/<name>/` instead, with a short marked block in `~/.codex/AGENTS.md` that lists them. Add `--scope project` to install into the current repository (or `--dir PATH` for another one).
+
+It is safe to run again. It records the files it wrote, with their hashes, in `.loopmath-skills.json` beside the skill folders, and it replaces or removes only those. A skill file you changed is kept, with a note. Any other file where a skill goes stops the install before it writes anything, and names the path to move aside. The single skill that 0.1 installed is replaced when it is as 0.1 wrote it. `loopmath skill show NAME` prints one skill, and `loopmath skill uninstall` removes the files it wrote. `loopmath doctor` shows what loopmath can see: logs, agents, store, fit, prices and skills.
+
+To onboard by hand instead:
+
+```sh
+loopmath onboard --dry-run                                  # what it found, and what each labeller costs
+loopmath onboard --labeler claude:claude-haiku-4-5 --yes    # record it and run a first fit
+```
+
+`onboard` reads your recent Claude Code and Codex sessions (the last 90 days unless you pass `--since`). It groups them into runs, labels each group's task type with a model you choose, names your usual workflow per task type and repository, and fits. loopmath never picks the labelling model for you. `--labeler` takes one of:
+
+- `claude:<model>`, through your `claude` CLI;
+- `codex:<model>`, through your `codex` CLI;
+- `command:<cmd>`, any local command such as `command:ollama run <model>`, so nothing leaves the machine;
+- `none`, to skip labelling.
+
+Reading the history uses up to 8 worker processes (one per CPU, at most 8). Set `LOOPMATH_WORKERS=1` to keep everything in one process, or another number to change the count.
+
+loopmath ships with a prior built from our own sweeps and experiments, so `recommend` gives an answer before you have any history. Your own runs then move it.
+
+## The loop
+
+The plan and record skills take an agent through the loop in three commands:
+
+```sh
+loopmath recommend --type bug_fix --repo acme/api --title "Fix the parser crash" --json --brief --html
+loopmath run start --rec REC --choice goal --base-commit SHA --json      # the harness, model and effort per piece
+loopmath run record --run RUN --session UUID --verified tests=pass --json  # costs from the logs, the outcome, the receipt
+```
+
+The same loop step by step, for a tool of your own:
+
+```sh
+# 1. Plan: classify the task, then ask.
+loopmath task-types
+loopmath recommend --type bug_fix --repo acme/api --feature size=s --feature lang=python --json
+#    the usual workflow (without one, your best recorded workflow is the reference), the success-cost curve,
+#    alternatives, two exploration picks, a suggested pair
+
+# 2. Record: one run per workflow you run, one attempt per agent you launch.
+loopmath run start --type bug_fix --repo acme/api --base-commit SHA --config CFG --source usual --rec REC
+loopmath run attempt --run RUN --piece implement --harness claude-code --model claude-opus-5-5 \
+  --effort high --cwd . --session UUID          # launch the agent with: claude --session-id UUID
+loopmath run attempt --run RUN --end ATT --status done
+loopmath run artifact --run RUN --kind commit --path SHA --by ATT
+
+# 3. Outcome: verdicts, scores, and later events.
+loopmath outcome --run RUN --signal tests=pass --kind verdict --tier verified
+loopmath outcome --run RUN --signal runtime_s=182 --kind score --unit s --better lower
+
+# 4. Finish: costs from the logs, a receipt, a refit.
+loopmath run finish --run RUN
+
+# Later: an incident or revert traced back to the run that made the commit.
+loopmath outcome --commit SHA --signal incident=INC-42 --kind event --source tracker
+```
+
+A pair runs the goal workflow and an exploration pick from the same base commit, in separate worktrees. Save the recommendation (`recommend ... --json > rec.json`) and start both runs from it with `run start --task-file rec.json`, so they share one task: the first with `--new-slate`, the second with `--slate SLT`. A blinded referee then picks the better change, which you record with `loopmath outcome --slate SLT --prefer RUN --judge referee --blinded`.
+
+A run counts as a success when it is accepted under your rule. By default that means the task's tests pass. A rule can also be a score target: `loopmath recommend ... --target 'heldout_perf>=2400'` or `--target 'runtime_s<=200'` gives the expected score and the chance of reaching the target. Set standing rules and other options with `loopmath config set KEY VALUE`, and the spending cap with `loopmath budget --usd X --period month`.
+
+Runs recorded by another tool that writes OCP v0.3, such as an experiment runner, come in with `loopmath run import DIR --finish`: several files or a directory, with one refit at the end (`--no-fit` skips it). Runs in your store always count as yours, whatever source their documents name. `loopmath fit --without SOURCE` leaves out one shipped prior source, and `loopmath status` names the options of the current fit.
+
+## The three views
+
+Each view is a self-contained HTML file written by a command; there is no server. The same numbers are available with `--json`.
+
+- **Previous runs:** `loopmath runs --html`. Every recorded run with its workflow graph, costs, signals and receipt.
+- **Plans for a task:** `loopmath recommend ... --html`. The candidates on a success-cost chart. Click one to see its workflow graph with per-piece predictions.
+- **Current estimates:** `loopmath posterior --html`. What loopmath believes at each level (model, effort, role, topology, task type, repository, feature), each with a range. Add `--workflow CFG` (a configuration id from `loopmath recommend` or your runs) to see the estimate for each piece of one workflow.
+
+Without a path, `--html` writes the page under `~/.loopmath/views/` and prints where it went.
+
+## Commands
+
+| Group | Commands |
+|---|---|
+| Plan | `task-types`, `workflows` (list, show, validate, diff), `recommend` |
+| Record | `run` (start, attempt, artifact, finish, import), `outcome`, `budget`, `config` (get, set) |
+| Learn | `fit`, `onboard`, `share`, `prior` |
+| View | `runs`, `posterior`, `status`, `report`, `doctor` |
+| Skill | `skill` (install, uninstall, show) |
+| OCP | `ocp` (validate, migrate) |
+| Log analysis | `analyze`, `graph`, `adapt`, `prices`, `validate-prices`, `scan`, `verify-receipts` |
+
+Each command prints a short summary by default. With `--json`, it prints exactly one JSON object instead. Exit codes: 0 ok, 1 user error, 2 not found, 3 not implemented, 4 store locked, 5 no fit yet. For flags, `loopmath <command> --help` is the source of truth.
+
+A workflow is a TOML file. `loopmath workflows list` shows the catalog and yours, which live in `~/.loopmath/workflows/`. This one implements, then sends a rejected change back once or twice:
+
+```toml
+id = "implement_review_mine"
+version = 1
+title = "Implement, then review"
+edges = ["issue -> implement", "repo -> implement", "implement -> diff", "diff -> review", "review -> verdict"]
+
+[[pieces]]
+id = "implement"
+role = "implementer"
+
+[[pieces]]
+id = "review"
+role = "reviewer"
+
+[[artifacts]]
+id = "issue"
+kind = "issue"
+
+[[artifacts]]
+id = "repo"
+kind = "repo"
+
+[[artifacts]]
+id = "diff"
+kind = "diff"
+
+[[artifacts]]
+id = "verdict"
+kind = "verdict"
+
+[control]
+budget_rounds = 3             # rounds, counting the first; 1 means no repair
+
+[[control.gates]]
+after = "review"              # the review's verdict decides
+on_fail = "implement"         # a rejected change goes back to implement
+
+[settings.implement]          # optional; with a setting for every piece, the file is a configuration
+harness = "claude-code"
+model = "claude-opus-5-5"
+effort = "high"
+
+[settings.review]
+harness = "codex"
+model = "gpt-5.6-sol"
+effort = "high"
+```
+
+Check it with `loopmath workflows validate FILE`, compare it with `loopmath workflows diff implement_review FILE`, and pass it to `recommend --workflow FILE` to have it considered, or to `run start --workflow FILE` to record a run with its settings (`--set PIECE=HARNESS:MODEL:EFFORT` overrides a piece).
+
+## The store and privacy
+
+The store is `~/.loopmath`. Set `LOOPMATH_HOME` or pass `--home` to put it elsewhere; the log parse cache moves with it, to `cache/` inside the store, unless you set `LOOPMATH_CACHE_DIR`. It holds:
+
+- one OCP v0.3 document per recorded run;
+- signals, receipts and fits;
+- your config and your workflows;
+- the views you write;
+- the log parse cache.
+
+Do not edit the store by hand; use the commands.
+
+Run files use the `metadata_only` privacy profile. They keep structure, models, tokens, dollars, paths and verdicts, but not transcript text.
+
+`loopmath share --out FILE` writes a reduced copy you can send to us. It keeps task types, workflows, models, tokens, dollars and outcomes. Repository names are hashed. Titles, paths, commands, session ids and commit shas are removed. `loopmath share --preview` prints exactly what would leave.
+
+## Analyzing logs without recording
+
+The log commands work on their own, with no store or fit:
+
+```sh
+loopmath analyze                 # cost per accepted run from the last 14 days of local logs
+loopmath graph --workspace NAME --format html --out graph.html
+```
+
+`analyze` reads `~/.claude/projects` and `~/.codex/sessions`. It grades the outcome evidence it finds, prices known models, and prints cost per accepted run with an 80% band. It also lists what it could not use and why.
+
+`graph` rebuilds which agent launched which, and which session read what another wrote. Its formats are `ocp`, `json`, `dot`, `run` and `html`. See the [workflow graph guide](docs/graph.md) and [adapters](docs/adapters.md).
+
+## Research data
+
+`loopmath research fit|transfer-test` and `loopmath analyze-e0` read data folders that are not part of the package. Name them with a flag (`--sweep-dir`, `--corpus`), an environment variable (`LOOPMATH_SWEEP_DIR`, `LOOPMATH_E0_CORPUS`), or config (`loopmath config set research.sweep_dir PATH`, `research.e0_corpus`). The research verbs need the `bayes` extra (`pip install 'loopmath[bayes]'`).
+
+## More
+
+- [OCP, the run format](spec/OCP.md): the normative note that goes with the [schemas](spec/), and the [versioning promise](spec/VERSIONING.md)
+- [Release policy](docs/release.md)
+- [Packaged model prices](src/loopmath/prices.toml)
+
+## License
+
+MIT.

loopmath-0.2.0/README.md

@@ -0,0 +1,228 @@
+# loopmath
+
+loopmath helps an orchestrator agent choose how to run a coding task, and learns from how it went.
+
+Before a task, it predicts how the user's usual agent workflow will do: the chance of an accepted result, and the cost in tokens and dollars. It shows the other workflows on a success-cost curve and offers two exploration picks. Each pick comes with its gain on every future similar run, its one-time price, and the number of runs it takes to pay back. After the task, the orchestrator records what ran and what came of it. loopmath fills in the token costs from the Claude Code and Codex logs, writes a receipt of predicted against actual, and refits.
+
+loopmath never starts or coordinates agents. Claude Code, Codex, herdr or your own tool does that; loopmath is a CLI they call. Everything runs locally. No command opens a network connection, the logs are opened read only, and loopmath writes only to its store (`~/.loopmath`) and to paths you name.
+
+The package installs two commands: `loopmath` and its short alias `loop`. If another `loop` is already on your PATH, use `loopmath`.
+
+## Install
+
+Python 3.11 or newer.
+
+```sh
+pipx install loopmath          # or: uv tool install loopmath, or pip install loopmath in a venv
+loopmath --version
+```
+
+From a clone of this repository:
+
+```sh
+python3 -m venv .venv
+.venv/bin/python -m pip install -e .
+```
+
+## First run
+
+```sh
+loopmath skill install      # teach your coding agents how to use loopmath
+```
+
+Then ask your agent to onboard, for example "onboard loopmath". The agent runs a dry run, asks you one question (which model labels your sessions, with the cost of each option), onboards, fits, and opens the results page.
+
+`skill install` writes six skills, one per job, and a shared `reference.md` with every command and JSON field they use. An agent loads only the skill for the job at hand, and each phrase belongs to one skill:
+
+| Skill | Ask your agent |
+|---|---|
+| `loopmath` | loopmath named without a job: "use loopmath", "what can loopmath do", "what next with loopmath" |
+| `loopmath-onboard` | "onboard", "set up", "start" or "try" loopmath; or loopmath has no runs yet |
+| `loopmath-import-runs` | OCP files (`*.ocp.json`), a folder of finished runs, or the output of an orchestrator or experiment harness that writes OCP |
+| `loopmath-update-fit` | "update", "refresh" or "rerun" the fit; what loopmath learned; runs imported or recorded without a refit |
+| `loopmath-plan-task` | "plan a task with loopmath"; which workflow, model or effort to use; a coding task of more than a few minutes in a repo that uses loopmath |
+| `loopmath-record-run` | a task planned with loopmath is done; "record", "log" or "save" a run; both runs of a pair need a blind judge |
+
+By default the skills go to every agent whose home exists: Claude Code (`~/.claude/skills/<name>/`, or under `$CLAUDE_CONFIG_DIR`) and Codex (`~/.codex/skills/<name>/`, or under `$CODEX_HOME`). `--target claude-code`, `codex` or `both` picks them yourself. If your Codex has no skills folder, the files go to `~/.codex/loopmath/<name>/` instead, with a short marked block in `~/.codex/AGENTS.md` that lists them. Add `--scope project` to install into the current repository (or `--dir PATH` for another one).
+
+It is safe to run again. It records the files it wrote, with their hashes, in `.loopmath-skills.json` beside the skill folders, and it replaces or removes only those. A skill file you changed is kept, with a note. Any other file where a skill goes stops the install before it writes anything, and names the path to move aside. The single skill that 0.1 installed is replaced when it is as 0.1 wrote it. `loopmath skill show NAME` prints one skill, and `loopmath skill uninstall` removes the files it wrote. `loopmath doctor` shows what loopmath can see: logs, agents, store, fit, prices and skills.
+
+To onboard by hand instead:
+
+```sh
+loopmath onboard --dry-run                                  # what it found, and what each labeller costs
+loopmath onboard --labeler claude:claude-haiku-4-5 --yes    # record it and run a first fit
+```
+
+`onboard` reads your recent Claude Code and Codex sessions (the last 90 days unless you pass `--since`). It groups them into runs, labels each group's task type with a model you choose, names your usual workflow per task type and repository, and fits. loopmath never picks the labelling model for you. `--labeler` takes one of:
+
+- `claude:<model>`, through your `claude` CLI;
+- `codex:<model>`, through your `codex` CLI;
+- `command:<cmd>`, any local command such as `command:ollama run <model>`, so nothing leaves the machine;
+- `none`, to skip labelling.
+
+Reading the history uses up to 8 worker processes (one per CPU, at most 8). Set `LOOPMATH_WORKERS=1` to keep everything in one process, or another number to change the count.
+
+loopmath ships with a prior built from our own sweeps and experiments, so `recommend` gives an answer before you have any history. Your own runs then move it.
+
+## The loop
+
+The plan and record skills take an agent through the loop in three commands:
+
+```sh
+loopmath recommend --type bug_fix --repo acme/api --title "Fix the parser crash" --json --brief --html
+loopmath run start --rec REC --choice goal --base-commit SHA --json      # the harness, model and effort per piece
+loopmath run record --run RUN --session UUID --verified tests=pass --json  # costs from the logs, the outcome, the receipt
+```
+
+The same loop step by step, for a tool of your own:
+
+```sh
+# 1. Plan: classify the task, then ask.
+loopmath task-types
+loopmath recommend --type bug_fix --repo acme/api --feature size=s --feature lang=python --json
+#    the usual workflow (without one, your best recorded workflow is the reference), the success-cost curve,
+#    alternatives, two exploration picks, a suggested pair
+
+# 2. Record: one run per workflow you run, one attempt per agent you launch.
+loopmath run start --type bug_fix --repo acme/api --base-commit SHA --config CFG --source usual --rec REC
+loopmath run attempt --run RUN --piece implement --harness claude-code --model claude-opus-5-5 \
+  --effort high --cwd . --session UUID          # launch the agent with: claude --session-id UUID
+loopmath run attempt --run RUN --end ATT --status done
+loopmath run artifact --run RUN --kind commit --path SHA --by ATT
+
+# 3. Outcome: verdicts, scores, and later events.
+loopmath outcome --run RUN --signal tests=pass --kind verdict --tier verified
+loopmath outcome --run RUN --signal runtime_s=182 --kind score --unit s --better lower
+
+# 4. Finish: costs from the logs, a receipt, a refit.
+loopmath run finish --run RUN
+
+# Later: an incident or revert traced back to the run that made the commit.
+loopmath outcome --commit SHA --signal incident=INC-42 --kind event --source tracker
+```
+
+A pair runs the goal workflow and an exploration pick from the same base commit, in separate worktrees. Save the recommendation (`recommend ... --json > rec.json`) and start both runs from it with `run start --task-file rec.json`, so they share one task: the first with `--new-slate`, the second with `--slate SLT`. A blinded referee then picks the better change, which you record with `loopmath outcome --slate SLT --prefer RUN --judge referee --blinded`.
+
+A run counts as a success when it is accepted under your rule. By default that means the task's tests pass. A rule can also be a score target: `loopmath recommend ... --target 'heldout_perf>=2400'` or `--target 'runtime_s<=200'` gives the expected score and the chance of reaching the target. Set standing rules and other options with `loopmath config set KEY VALUE`, and the spending cap with `loopmath budget --usd X --period month`.
+
+Runs recorded by another tool that writes OCP v0.3, such as an experiment runner, come in with `loopmath run import DIR --finish`: several files or a directory, with one refit at the end (`--no-fit` skips it). Runs in your store always count as yours, whatever source their documents name. `loopmath fit --without SOURCE` leaves out one shipped prior source, and `loopmath status` names the options of the current fit.
+
+## The three views
+
+Each view is a self-contained HTML file written by a command; there is no server. The same numbers are available with `--json`.
+
+- **Previous runs:** `loopmath runs --html`. Every recorded run with its workflow graph, costs, signals and receipt.
+- **Plans for a task:** `loopmath recommend ... --html`. The candidates on a success-cost chart. Click one to see its workflow graph with per-piece predictions.
+- **Current estimates:** `loopmath posterior --html`. What loopmath believes at each level (model, effort, role, topology, task type, repository, feature), each with a range. Add `--workflow CFG` (a configuration id from `loopmath recommend` or your runs) to see the estimate for each piece of one workflow.
+
+Without a path, `--html` writes the page under `~/.loopmath/views/` and prints where it went.
+
+## Commands
+
+| Group | Commands |
+|---|---|
+| Plan | `task-types`, `workflows` (list, show, validate, diff), `recommend` |
+| Record | `run` (start, attempt, artifact, finish, import), `outcome`, `budget`, `config` (get, set) |
+| Learn | `fit`, `onboard`, `share`, `prior` |
+| View | `runs`, `posterior`, `status`, `report`, `doctor` |
+| Skill | `skill` (install, uninstall, show) |
+| OCP | `ocp` (validate, migrate) |
+| Log analysis | `analyze`, `graph`, `adapt`, `prices`, `validate-prices`, `scan`, `verify-receipts` |
+
+Each command prints a short summary by default. With `--json`, it prints exactly one JSON object instead. Exit codes: 0 ok, 1 user error, 2 not found, 3 not implemented, 4 store locked, 5 no fit yet. For flags, `loopmath <command> --help` is the source of truth.
+
+A workflow is a TOML file. `loopmath workflows list` shows the catalog and yours, which live in `~/.loopmath/workflows/`. This one implements, then sends a rejected change back once or twice:
+
+```toml
+id = "implement_review_mine"
+version = 1
+title = "Implement, then review"
+edges = ["issue -> implement", "repo -> implement", "implement -> diff", "diff -> review", "review -> verdict"]
+
+[[pieces]]
+id = "implement"
+role = "implementer"
+
+[[pieces]]
+id = "review"
+role = "reviewer"
+
+[[artifacts]]
+id = "issue"
+kind = "issue"
+
+[[artifacts]]
+id = "repo"
+kind = "repo"
+
+[[artifacts]]
+id = "diff"
+kind = "diff"
+
+[[artifacts]]
+id = "verdict"
+kind = "verdict"
+
+[control]
+budget_rounds = 3             # rounds, counting the first; 1 means no repair
+
+[[control.gates]]
+after = "review"              # the review's verdict decides
+on_fail = "implement"         # a rejected change goes back to implement
+
+[settings.implement]          # optional; with a setting for every piece, the file is a configuration
+harness = "claude-code"
+model = "claude-opus-5-5"
+effort = "high"
+
+[settings.review]
+harness = "codex"
+model = "gpt-5.6-sol"
+effort = "high"
+```
+
+Check it with `loopmath workflows validate FILE`, compare it with `loopmath workflows diff implement_review FILE`, and pass it to `recommend --workflow FILE` to have it considered, or to `run start --workflow FILE` to record a run with its settings (`--set PIECE=HARNESS:MODEL:EFFORT` overrides a piece).
+
+## The store and privacy
+
+The store is `~/.loopmath`. Set `LOOPMATH_HOME` or pass `--home` to put it elsewhere; the log parse cache moves with it, to `cache/` inside the store, unless you set `LOOPMATH_CACHE_DIR`. It holds:
+
+- one OCP v0.3 document per recorded run;
+- signals, receipts and fits;
+- your config and your workflows;
+- the views you write;
+- the log parse cache.
+
+Do not edit the store by hand; use the commands.
+
+Run files use the `metadata_only` privacy profile. They keep structure, models, tokens, dollars, paths and verdicts, but not transcript text.
+
+`loopmath share --out FILE` writes a reduced copy you can send to us. It keeps task types, workflows, models, tokens, dollars and outcomes. Repository names are hashed. Titles, paths, commands, session ids and commit shas are removed. `loopmath share --preview` prints exactly what would leave.
+
+## Analyzing logs without recording
+
+The log commands work on their own, with no store or fit:
+
+```sh
+loopmath analyze                 # cost per accepted run from the last 14 days of local logs
+loopmath graph --workspace NAME --format html --out graph.html
+```
+
+`analyze` reads `~/.claude/projects` and `~/.codex/sessions`. It grades the outcome evidence it finds, prices known models, and prints cost per accepted run with an 80% band. It also lists what it could not use and why.
+
+`graph` rebuilds which agent launched which, and which session read what another wrote. Its formats are `ocp`, `json`, `dot`, `run` and `html`. See the [workflow graph guide](docs/graph.md) and [adapters](docs/adapters.md).
+
+## Research data
+
+`loopmath research fit|transfer-test` and `loopmath analyze-e0` read data folders that are not part of the package. Name them with a flag (`--sweep-dir`, `--corpus`), an environment variable (`LOOPMATH_SWEEP_DIR`, `LOOPMATH_E0_CORPUS`), or config (`loopmath config set research.sweep_dir PATH`, `research.e0_corpus`). The research verbs need the `bayes` extra (`pip install 'loopmath[bayes]'`).
+
+## More
+
+- [OCP, the run format](spec/OCP.md): the normative note that goes with the [schemas](spec/), and the [versioning promise](spec/VERSIONING.md)
+- [Release policy](docs/release.md)
+- [Packaged model prices](src/loopmath/prices.toml)
+
+## License
+
+MIT.

loopmath-0.2.0/pyproject.toml

@@ -0,0 +1,111 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "loopmath"
+version = "0.2.0"
+description = "Plan agent workflows, record how they went, and learn from your own Claude Code and Codex logs"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [
+    { name = "QKV Labs" },
+]
+keywords = [
+    "agents",
+    "claude code",
+    "codex",
+    "cost analysis",
+    "developer tools",
+    "workflow analysis",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development",
+    "Topic :: Software Development :: Quality Assurance",
+]
+# Core: everything the loop needs (onboard, recommend, run, outcome, finish, the
+# views). The default belief engine behind `fit`, `recommend` and receipts is
+# Gaussian and uses scipy (spec 00 section 4, `loopmath/belief/`); jsonschema
+# checks OCP documents; `analyze` runs on numpy and pandas. A plotting stack
+# stays out: matplotlib is only for the E0 figure writer (the `e0` extra).
+dependencies = [
+    "jsonschema>=4",
+    "numpy",
+    "pandas",
+    "scipy",
+]
+
+# The research verbs (`loopmath research fit|transfer-test`) use the older PyMC
+# engine and need the [bayes] extra; they say so when it is missing. The default
+# engine does not.
+[project.optional-dependencies]
+bayes = [
+    "pymc>=5",
+    # `fit_bayes.py` imports pytensor directly. Do not rely on pymc's
+    # transitive dependency to supply a module loopmath itself imports.
+    "pytensor",
+    "arviz",
+    # arviz writes a fit with `to_netcdf`, which needs a NetCDF backend it does
+    # not itself depend on. Without one, `loopmath research fit --out PATH` samples fine and
+    # then dies on the write. Declared here so a fresh install of the extra can
+    # actually use `--out`; the CLI still catches the missing backend and says
+    # which package to install rather than surfacing a raw ValueError.
+    "h5netcdf",
+]
+
+# The E0 walkdown verb writes figures, which is the only thing in the package
+# that needs a plotting stack. Without this extra, `loopmath analyze-e0` is simply
+# not registered and every other verb works unchanged.
+e0 = [
+    "matplotlib",
+]
+
+[project.scripts]
+loopmath = "loopmath.cli:main"
+loop = "loopmath.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/loopmath/loopmath"
+Issues = "https://github.com/loopmath/loopmath/issues"
+Repository = "https://github.com/loopmath/loopmath.git"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+loopmath = [
+    "prices.toml",
+    "workflows/catalog/*.toml",
+    "skill/skills/*.md",
+    "skill/skills/*/SKILL.md",
+    "priors/*.toml",
+    "priors/bundle/*",
+    "views/assets/*",
+    "ocp/schema/*.json",
+]
+
+[tool.setuptools.data-files]
+spec = [
+    "spec/ocp_conformance.py",
+    "spec/ocp-v0.schema.json",
+    "spec/ocp-v0.2.schema.json",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = '-m "not packaging"'
+markers = [
+    "packaging: builds and installs a distribution artifact in an isolated environment",
+]

loopmath-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+