loopsmith-cli 0.1.2__tar.gz → 0.1.4__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,241 @@
1
+ Metadata-Version: 2.4
2
+ Name: loopsmith-cli
3
+ Version: 0.1.4
4
+ Summary: Self-evolving agent loops behind a deterministic verification gate. Installs the prebuilt Rust binary as `loopsmith`.
5
+ Author-email: bitphill <bitphill@tuta.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/bitphill/loopsmith
8
+ Project-URL: Repository, https://github.com/bitphill/loopsmith
9
+ Project-URL: Changelog, https://github.com/bitphill/loopsmith/blob/main/CHANGELOG.md
10
+ Project-URL: Issues, https://github.com/bitphill/loopsmith/issues
11
+ Keywords: agent,loop,llm,orchestration,cli,rust
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Operating System :: POSIX :: Linux
16
+ Classifier: Operating System :: MacOS :: MacOS X
17
+ Classifier: Operating System :: Microsoft :: Windows
18
+ Classifier: Programming Language :: Rust
19
+ Classifier: Topic :: Software Development :: Build Tools
20
+ Requires-Python: >=3.8
21
+ Description-Content-Type: text/markdown
22
+
23
+ <div align="center">
24
+ <img src="https://raw.githubusercontent.com/bitphill/loopsmith/v0.1.4/assets/loopsmith-logo-256.png" alt="loopsmith" width="180" />
25
+ <h1>loopsmith</h1>
26
+ <p><em>Self-evolving agent loops. The gate is code, so "done" cannot be argued.</em></p>
27
+ </div>
28
+
29
+ [![PyPI](https://img.shields.io/pypi/v/loopsmith-cli?logo=python&logoColor=white&label=PyPI&color=3775a9)](https://pypi.org/project/loopsmith-cli/)
30
+ [![license](https://img.shields.io/badge/license-MIT-C8CAD1?labelColor=222)](https://github.com/bitphill/loopsmith/blob/main/LICENSE)
31
+ ![platforms](https://img.shields.io/badge/os-linux%20%7C%20macos%20%7C%20windows-2A5A8A)
32
+ ![python](https://img.shields.io/badge/python-%E2%89%A53.8-3775a9?logo=python&logoColor=white)
33
+
34
+ ```bash
35
+ pip install loopsmith-cli
36
+ loopsmith doctor
37
+ ```
38
+
39
+ > **This distribution is a Rust binary, not a Python library.** There is nothing to
40
+ > `import`. It installs a `loopsmith` command. To drive loops from Python, use
41
+ > `subprocess` — its exit codes are its API.
42
+
43
+ ## TL;DR:
44
+
45
+ You have a job you redo every week and are fussy about — a competitor roundup, a
46
+ lead list, a landing page, a research brief. Write down **what you want** and
47
+ **how anyone would tell it's good**, in one plain text file. loopsmith puts an AI
48
+ to work on it, checks the result, sends it back when it falls short, and stops
49
+ when it passes. It can run on a schedule for weeks without you.
50
+
51
+ The rule that makes it safe to walk away: **the AI never gets to say "done".** A
52
+ deterministic checker reads the actual files and decides — and it can revoke, so
53
+ a goal that stops being true stops being satisfied.
54
+
55
+ **Not a developer?** Marketing, sales, research, ops — if you can edit a text
56
+ file, you can run a loop.
57
+
58
+ ### ➜ [START-HERE — README-FOR-DUMMIES.md](https://github.com/bitphill/loopsmith/blob/v0.1.4/README-FOR-DUMMIES.md)
59
+
60
+ A plain-English guide: one install line, thirteen ready-made loops to copy, the
61
+ six settings you actually edit, and how to leave it running on a schedule.
62
+
63
+ ## What it is
64
+
65
+ You describe a purpose in a config — goals, how each is checked, what counts as
66
+ success, when to stop, what the loop may never do. loopsmith handles scheduling,
67
+ provider routing, memory, verification, and termination, and can run for weeks
68
+ without you.
69
+
70
+ One rule holds the whole design up:
71
+
72
+ > **A model must not be the thing that certifies its own completion.**
73
+
74
+ `goal_satisfied` is written by a deterministic Rust gate and by nothing else, and
75
+ the gate can **revoke**: delete a required artifact and a satisfied goal flips
76
+ back. A system that can only promote is a burndown chart with extra steps.
77
+
78
+ ## Five minutes
79
+
80
+ ```bash
81
+ pip install loopsmith-cli
82
+
83
+ # --path must be outside any repo you care about: a loop edits files and writes
84
+ # state, so it does not get pointed at the tool that runs it.
85
+ loopsmith new --path ~/loops/nightly-refactor --purpose "keep the module simple"
86
+
87
+ cd ~/loops/nightly-refactor
88
+ $EDITOR loop.yaml # your goals, and how each one is checked
89
+ loopsmith validate loop.yaml
90
+ loopsmith plan loop.yaml
91
+ ./run.sh # run.cmd on Windows
92
+ ```
93
+
94
+ ### `validate` fails on purpose
95
+
96
+ ```
97
+ error pre_execution: 2 step(s) not marked done: Run this task manually end to
98
+ end at least once; Write down what 'done' means in checkable terms.
99
+ Automating before understanding produces fast, confident garbage
100
+ ```
101
+
102
+ That refusal is the most valuable thing the tool does. Do the task by hand once —
103
+ the manual run *is* the spec. Mark each `pre_execution` step `done: true` once you
104
+ actually have.
105
+
106
+ ## What a config looks like
107
+
108
+ Ten sections, **A** to **J**: information, the manual work list, goals,
109
+ validations, success criteria, stop gates, schedules, constraints, execution
110
+ guidelines, default skills. YAML or Markdown — the same model either way.
111
+
112
+ ```yaml
113
+ name: nightly-refactor
114
+ description: keep the payments module simple without breaking it
115
+
116
+ pre_execution:
117
+ - step: Ran the refactor by hand on one file and kept the diff
118
+ done: true
119
+
120
+ goals:
121
+ - name: simpler
122
+ description: Cyclomatic complexity down, behaviour unchanged.
123
+
124
+ validations:
125
+ - target: simpler
126
+ name: tests-still-pass
127
+ mode: objective
128
+ statement: The suite exits clean.
129
+ detector:
130
+ type: script
131
+ command: ./scripts/check-tests.sh
132
+ expect_exit: 0
133
+ blocking: true
134
+
135
+ success:
136
+ - target: overall
137
+ name: all-blocking-pass
138
+ mode: percentage
139
+ statement: Every blocking validation passes.
140
+ threshold: 1.0
141
+
142
+ stop_gates:
143
+ max_iterations: 8
144
+ max_revisions_per_node: 3
145
+ max_cost_usd: 5.0
146
+ no_progress_iterations: 3
147
+
148
+ graph:
149
+ nodes:
150
+ - id: refactor
151
+ role: builder
152
+ instruction: Simplify one function. State any assumption you had to make.
153
+ goals: [simpler]
154
+ isolated: true # its own git worktree
155
+ - id: review
156
+ role: judge
157
+ instruction: Check the diff against the brief. Pass or fail per check, with evidence.
158
+ depends_on: [refactor]
159
+ goals: [simpler]
160
+ tier: strong
161
+ ```
162
+
163
+ Detectors are `file_exists`, `regex`, `script`, and composites. Only a detector
164
+ can satisfy a goal — a model's opinion of its own work never does.
165
+
166
+ ## While it runs
167
+
168
+ | Question | Command |
169
+ |---|---|
170
+ | What does the gate say? | `loopsmith status <config> <run-id>` |
171
+ | What happened? | `loopsmith ledger <config> <run-id>` |
172
+ | Why did it stop? | the last line of `logs/<run-id>.log` |
173
+ | What does it want changed about itself? | `loopsmith proposals <config> <run-id>` |
174
+ | Which providers can it reach? | `loopsmith providers <config>` |
175
+ | Will this machine get in the way? | `loopsmith doctor <config>` |
176
+
177
+ **The loop never edits its own config.** Changes to goals, validations, success
178
+ criteria, and sub-agent adoption are written as *proposals* for a human to apply.
179
+
180
+ ## Providers and BYOK
181
+
182
+ Every provider is a command template, which is what makes bring-your-own-key
183
+ free: Claude Code, Ollama, a Grok CLI, an OpenAI-compatible endpoint driven by
184
+ `curl`, an MCP server over stdio — all of them are "a program you run with a
185
+ prompt". Adding one is a config edit, never a rebuild.
186
+
187
+ `requires_env` names variables that must **exist**. loopsmith never reads their
188
+ values, so a key cannot reach a prompt, a log, or the ledger.
189
+
190
+ > ⚠ Never paste an API key into a chat window, a config file, or an issue. If one
191
+ > ends up somewhere it should not be, rotate it — deleting the message is not
192
+ > enough.
193
+
194
+ ## How this distribution installs the binary
195
+
196
+ The binary is fetched **on first run**, not during `pip install`, and cached under
197
+ `~/.loopsmith/bin/<version>/` (override with `LOOPSMITH_HOME`).
198
+
199
+ That is deliberate. A wheel that downloads at install time breaks in every
200
+ environment that installs without a network and runs with one — CI images, Docker
201
+ build stages, locked-down build hosts — and the failure surfaces as an install
202
+ error for a package the user has not tried to use yet.
203
+
204
+ Every download is **verified against the release's published `SHA256SUMS` before it
205
+ is executed**. Fetching a binary and running it unverified is a supply-chain hole
206
+ with a progress bar.
207
+
208
+ Prebuilt for:
209
+
210
+ | Platform | Target |
211
+ |---|---|
212
+ | Linux x86_64 (glibc) | `x86_64-unknown-linux-gnu` |
213
+ | Linux x86_64 (musl, auto-detected) | `x86_64-unknown-linux-musl` |
214
+ | Linux arm64 | `aarch64-unknown-linux-gnu` |
215
+ | macOS Intel | `x86_64-apple-darwin` |
216
+ | macOS Apple silicon | `aarch64-apple-darwin` |
217
+ | Windows x86_64 | `x86_64-pc-windows-msvc` |
218
+
219
+ Anywhere else, build from source — it is the same program:
220
+
221
+ ```bash
222
+ cargo install loopsmith
223
+ ```
224
+
225
+ ## The distribution name
226
+
227
+ `loopsmith` on PyPI was already registered by an unrelated project, so this
228
+ distribution is `loopsmith-cli`. The installed command is `loopsmith` either way.
229
+ Elsewhere: [`loopsmith`](https://crates.io/crates/loopsmith) on crates.io,
230
+ [`@bitphill/loopsmith`](https://www.npmjs.com/package/@bitphill/loopsmith) on npm,
231
+ and the `bitphill/loopsmith` Homebrew tap.
232
+
233
+ ## Documentation
234
+
235
+ - [Full README](https://github.com/bitphill/loopsmith#readme)
236
+ - [Section-by-section config reference](https://github.com/bitphill/loopsmith/blob/main/HOW-TO-USE.md)
237
+ - [Architecture and the reasoning behind it](https://github.com/bitphill/loopsmith/blob/main/README-DETAIL.md)
238
+ - [Thirteen worked examples](https://github.com/bitphill/loopsmith/tree/main/config/examples)
239
+ - [Changelog](https://github.com/bitphill/loopsmith/blob/main/CHANGELOG.md)
240
+
241
+ MIT licensed. © bitphill
@@ -0,0 +1,219 @@
1
+ <div align="center">
2
+ <img src="https://raw.githubusercontent.com/bitphill/loopsmith/v0.1.4/assets/loopsmith-logo-256.png" alt="loopsmith" width="180" />
3
+ <h1>loopsmith</h1>
4
+ <p><em>Self-evolving agent loops. The gate is code, so "done" cannot be argued.</em></p>
5
+ </div>
6
+
7
+ [![PyPI](https://img.shields.io/pypi/v/loopsmith-cli?logo=python&logoColor=white&label=PyPI&color=3775a9)](https://pypi.org/project/loopsmith-cli/)
8
+ [![license](https://img.shields.io/badge/license-MIT-C8CAD1?labelColor=222)](https://github.com/bitphill/loopsmith/blob/main/LICENSE)
9
+ ![platforms](https://img.shields.io/badge/os-linux%20%7C%20macos%20%7C%20windows-2A5A8A)
10
+ ![python](https://img.shields.io/badge/python-%E2%89%A53.8-3775a9?logo=python&logoColor=white)
11
+
12
+ ```bash
13
+ pip install loopsmith-cli
14
+ loopsmith doctor
15
+ ```
16
+
17
+ > **This distribution is a Rust binary, not a Python library.** There is nothing to
18
+ > `import`. It installs a `loopsmith` command. To drive loops from Python, use
19
+ > `subprocess` — its exit codes are its API.
20
+
21
+ ## TL;DR:
22
+
23
+ You have a job you redo every week and are fussy about — a competitor roundup, a
24
+ lead list, a landing page, a research brief. Write down **what you want** and
25
+ **how anyone would tell it's good**, in one plain text file. loopsmith puts an AI
26
+ to work on it, checks the result, sends it back when it falls short, and stops
27
+ when it passes. It can run on a schedule for weeks without you.
28
+
29
+ The rule that makes it safe to walk away: **the AI never gets to say "done".** A
30
+ deterministic checker reads the actual files and decides — and it can revoke, so
31
+ a goal that stops being true stops being satisfied.
32
+
33
+ **Not a developer?** Marketing, sales, research, ops — if you can edit a text
34
+ file, you can run a loop.
35
+
36
+ ### ➜ [START-HERE — README-FOR-DUMMIES.md](https://github.com/bitphill/loopsmith/blob/v0.1.4/README-FOR-DUMMIES.md)
37
+
38
+ A plain-English guide: one install line, thirteen ready-made loops to copy, the
39
+ six settings you actually edit, and how to leave it running on a schedule.
40
+
41
+ ## What it is
42
+
43
+ You describe a purpose in a config — goals, how each is checked, what counts as
44
+ success, when to stop, what the loop may never do. loopsmith handles scheduling,
45
+ provider routing, memory, verification, and termination, and can run for weeks
46
+ without you.
47
+
48
+ One rule holds the whole design up:
49
+
50
+ > **A model must not be the thing that certifies its own completion.**
51
+
52
+ `goal_satisfied` is written by a deterministic Rust gate and by nothing else, and
53
+ the gate can **revoke**: delete a required artifact and a satisfied goal flips
54
+ back. A system that can only promote is a burndown chart with extra steps.
55
+
56
+ ## Five minutes
57
+
58
+ ```bash
59
+ pip install loopsmith-cli
60
+
61
+ # --path must be outside any repo you care about: a loop edits files and writes
62
+ # state, so it does not get pointed at the tool that runs it.
63
+ loopsmith new --path ~/loops/nightly-refactor --purpose "keep the module simple"
64
+
65
+ cd ~/loops/nightly-refactor
66
+ $EDITOR loop.yaml # your goals, and how each one is checked
67
+ loopsmith validate loop.yaml
68
+ loopsmith plan loop.yaml
69
+ ./run.sh # run.cmd on Windows
70
+ ```
71
+
72
+ ### `validate` fails on purpose
73
+
74
+ ```
75
+ error pre_execution: 2 step(s) not marked done: Run this task manually end to
76
+ end at least once; Write down what 'done' means in checkable terms.
77
+ Automating before understanding produces fast, confident garbage
78
+ ```
79
+
80
+ That refusal is the most valuable thing the tool does. Do the task by hand once —
81
+ the manual run *is* the spec. Mark each `pre_execution` step `done: true` once you
82
+ actually have.
83
+
84
+ ## What a config looks like
85
+
86
+ Ten sections, **A** to **J**: information, the manual work list, goals,
87
+ validations, success criteria, stop gates, schedules, constraints, execution
88
+ guidelines, default skills. YAML or Markdown — the same model either way.
89
+
90
+ ```yaml
91
+ name: nightly-refactor
92
+ description: keep the payments module simple without breaking it
93
+
94
+ pre_execution:
95
+ - step: Ran the refactor by hand on one file and kept the diff
96
+ done: true
97
+
98
+ goals:
99
+ - name: simpler
100
+ description: Cyclomatic complexity down, behaviour unchanged.
101
+
102
+ validations:
103
+ - target: simpler
104
+ name: tests-still-pass
105
+ mode: objective
106
+ statement: The suite exits clean.
107
+ detector:
108
+ type: script
109
+ command: ./scripts/check-tests.sh
110
+ expect_exit: 0
111
+ blocking: true
112
+
113
+ success:
114
+ - target: overall
115
+ name: all-blocking-pass
116
+ mode: percentage
117
+ statement: Every blocking validation passes.
118
+ threshold: 1.0
119
+
120
+ stop_gates:
121
+ max_iterations: 8
122
+ max_revisions_per_node: 3
123
+ max_cost_usd: 5.0
124
+ no_progress_iterations: 3
125
+
126
+ graph:
127
+ nodes:
128
+ - id: refactor
129
+ role: builder
130
+ instruction: Simplify one function. State any assumption you had to make.
131
+ goals: [simpler]
132
+ isolated: true # its own git worktree
133
+ - id: review
134
+ role: judge
135
+ instruction: Check the diff against the brief. Pass or fail per check, with evidence.
136
+ depends_on: [refactor]
137
+ goals: [simpler]
138
+ tier: strong
139
+ ```
140
+
141
+ Detectors are `file_exists`, `regex`, `script`, and composites. Only a detector
142
+ can satisfy a goal — a model's opinion of its own work never does.
143
+
144
+ ## While it runs
145
+
146
+ | Question | Command |
147
+ |---|---|
148
+ | What does the gate say? | `loopsmith status <config> <run-id>` |
149
+ | What happened? | `loopsmith ledger <config> <run-id>` |
150
+ | Why did it stop? | the last line of `logs/<run-id>.log` |
151
+ | What does it want changed about itself? | `loopsmith proposals <config> <run-id>` |
152
+ | Which providers can it reach? | `loopsmith providers <config>` |
153
+ | Will this machine get in the way? | `loopsmith doctor <config>` |
154
+
155
+ **The loop never edits its own config.** Changes to goals, validations, success
156
+ criteria, and sub-agent adoption are written as *proposals* for a human to apply.
157
+
158
+ ## Providers and BYOK
159
+
160
+ Every provider is a command template, which is what makes bring-your-own-key
161
+ free: Claude Code, Ollama, a Grok CLI, an OpenAI-compatible endpoint driven by
162
+ `curl`, an MCP server over stdio — all of them are "a program you run with a
163
+ prompt". Adding one is a config edit, never a rebuild.
164
+
165
+ `requires_env` names variables that must **exist**. loopsmith never reads their
166
+ values, so a key cannot reach a prompt, a log, or the ledger.
167
+
168
+ > ⚠ Never paste an API key into a chat window, a config file, or an issue. If one
169
+ > ends up somewhere it should not be, rotate it — deleting the message is not
170
+ > enough.
171
+
172
+ ## How this distribution installs the binary
173
+
174
+ The binary is fetched **on first run**, not during `pip install`, and cached under
175
+ `~/.loopsmith/bin/<version>/` (override with `LOOPSMITH_HOME`).
176
+
177
+ That is deliberate. A wheel that downloads at install time breaks in every
178
+ environment that installs without a network and runs with one — CI images, Docker
179
+ build stages, locked-down build hosts — and the failure surfaces as an install
180
+ error for a package the user has not tried to use yet.
181
+
182
+ Every download is **verified against the release's published `SHA256SUMS` before it
183
+ is executed**. Fetching a binary and running it unverified is a supply-chain hole
184
+ with a progress bar.
185
+
186
+ Prebuilt for:
187
+
188
+ | Platform | Target |
189
+ |---|---|
190
+ | Linux x86_64 (glibc) | `x86_64-unknown-linux-gnu` |
191
+ | Linux x86_64 (musl, auto-detected) | `x86_64-unknown-linux-musl` |
192
+ | Linux arm64 | `aarch64-unknown-linux-gnu` |
193
+ | macOS Intel | `x86_64-apple-darwin` |
194
+ | macOS Apple silicon | `aarch64-apple-darwin` |
195
+ | Windows x86_64 | `x86_64-pc-windows-msvc` |
196
+
197
+ Anywhere else, build from source — it is the same program:
198
+
199
+ ```bash
200
+ cargo install loopsmith
201
+ ```
202
+
203
+ ## The distribution name
204
+
205
+ `loopsmith` on PyPI was already registered by an unrelated project, so this
206
+ distribution is `loopsmith-cli`. The installed command is `loopsmith` either way.
207
+ Elsewhere: [`loopsmith`](https://crates.io/crates/loopsmith) on crates.io,
208
+ [`@bitphill/loopsmith`](https://www.npmjs.com/package/@bitphill/loopsmith) on npm,
209
+ and the `bitphill/loopsmith` Homebrew tap.
210
+
211
+ ## Documentation
212
+
213
+ - [Full README](https://github.com/bitphill/loopsmith#readme)
214
+ - [Section-by-section config reference](https://github.com/bitphill/loopsmith/blob/main/HOW-TO-USE.md)
215
+ - [Architecture and the reasoning behind it](https://github.com/bitphill/loopsmith/blob/main/README-DETAIL.md)
216
+ - [Thirteen worked examples](https://github.com/bitphill/loopsmith/tree/main/config/examples)
217
+ - [Changelog](https://github.com/bitphill/loopsmith/blob/main/CHANGELOG.md)
218
+
219
+ MIT licensed. © bitphill
@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
6
6
  # `loopsmith` on PyPI was already registered by an unrelated project, so the
7
7
  # distribution is `loopsmith-cli`. The installed command is `loopsmith`.
8
8
  name = "loopsmith-cli"
9
- version = "0.1.2"
9
+ version = "0.1.4"
10
10
  description = "Self-evolving agent loops behind a deterministic verification gate. Installs the prebuilt Rust binary as `loopsmith`."
11
11
  readme = "README.md"
12
12
  license = "MIT"
@@ -25,7 +25,7 @@ import urllib.request
25
25
  import zipfile
26
26
  from pathlib import Path
27
27
 
28
- __version__ = "0.1.2"
28
+ __version__ = "0.1.4"
29
29
 
30
30
  REPO = "bitphill/loopsmith"
31
31
  _RELEASE_BASE = f"https://github.com/{REPO}/releases/download/v{__version__}"
@@ -0,0 +1,241 @@
1
+ Metadata-Version: 2.4
2
+ Name: loopsmith-cli
3
+ Version: 0.1.4
4
+ Summary: Self-evolving agent loops behind a deterministic verification gate. Installs the prebuilt Rust binary as `loopsmith`.
5
+ Author-email: bitphill <bitphill@tuta.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/bitphill/loopsmith
8
+ Project-URL: Repository, https://github.com/bitphill/loopsmith
9
+ Project-URL: Changelog, https://github.com/bitphill/loopsmith/blob/main/CHANGELOG.md
10
+ Project-URL: Issues, https://github.com/bitphill/loopsmith/issues
11
+ Keywords: agent,loop,llm,orchestration,cli,rust
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Operating System :: POSIX :: Linux
16
+ Classifier: Operating System :: MacOS :: MacOS X
17
+ Classifier: Operating System :: Microsoft :: Windows
18
+ Classifier: Programming Language :: Rust
19
+ Classifier: Topic :: Software Development :: Build Tools
20
+ Requires-Python: >=3.8
21
+ Description-Content-Type: text/markdown
22
+
23
+ <div align="center">
24
+ <img src="https://raw.githubusercontent.com/bitphill/loopsmith/v0.1.4/assets/loopsmith-logo-256.png" alt="loopsmith" width="180" />
25
+ <h1>loopsmith</h1>
26
+ <p><em>Self-evolving agent loops. The gate is code, so "done" cannot be argued.</em></p>
27
+ </div>
28
+
29
+ [![PyPI](https://img.shields.io/pypi/v/loopsmith-cli?logo=python&logoColor=white&label=PyPI&color=3775a9)](https://pypi.org/project/loopsmith-cli/)
30
+ [![license](https://img.shields.io/badge/license-MIT-C8CAD1?labelColor=222)](https://github.com/bitphill/loopsmith/blob/main/LICENSE)
31
+ ![platforms](https://img.shields.io/badge/os-linux%20%7C%20macos%20%7C%20windows-2A5A8A)
32
+ ![python](https://img.shields.io/badge/python-%E2%89%A53.8-3775a9?logo=python&logoColor=white)
33
+
34
+ ```bash
35
+ pip install loopsmith-cli
36
+ loopsmith doctor
37
+ ```
38
+
39
+ > **This distribution is a Rust binary, not a Python library.** There is nothing to
40
+ > `import`. It installs a `loopsmith` command. To drive loops from Python, use
41
+ > `subprocess` — its exit codes are its API.
42
+
43
+ ## TL;DR:
44
+
45
+ You have a job you redo every week and are fussy about — a competitor roundup, a
46
+ lead list, a landing page, a research brief. Write down **what you want** and
47
+ **how anyone would tell it's good**, in one plain text file. loopsmith puts an AI
48
+ to work on it, checks the result, sends it back when it falls short, and stops
49
+ when it passes. It can run on a schedule for weeks without you.
50
+
51
+ The rule that makes it safe to walk away: **the AI never gets to say "done".** A
52
+ deterministic checker reads the actual files and decides — and it can revoke, so
53
+ a goal that stops being true stops being satisfied.
54
+
55
+ **Not a developer?** Marketing, sales, research, ops — if you can edit a text
56
+ file, you can run a loop.
57
+
58
+ ### ➜ [START-HERE — README-FOR-DUMMIES.md](https://github.com/bitphill/loopsmith/blob/v0.1.4/README-FOR-DUMMIES.md)
59
+
60
+ A plain-English guide: one install line, thirteen ready-made loops to copy, the
61
+ six settings you actually edit, and how to leave it running on a schedule.
62
+
63
+ ## What it is
64
+
65
+ You describe a purpose in a config — goals, how each is checked, what counts as
66
+ success, when to stop, what the loop may never do. loopsmith handles scheduling,
67
+ provider routing, memory, verification, and termination, and can run for weeks
68
+ without you.
69
+
70
+ One rule holds the whole design up:
71
+
72
+ > **A model must not be the thing that certifies its own completion.**
73
+
74
+ `goal_satisfied` is written by a deterministic Rust gate and by nothing else, and
75
+ the gate can **revoke**: delete a required artifact and a satisfied goal flips
76
+ back. A system that can only promote is a burndown chart with extra steps.
77
+
78
+ ## Five minutes
79
+
80
+ ```bash
81
+ pip install loopsmith-cli
82
+
83
+ # --path must be outside any repo you care about: a loop edits files and writes
84
+ # state, so it does not get pointed at the tool that runs it.
85
+ loopsmith new --path ~/loops/nightly-refactor --purpose "keep the module simple"
86
+
87
+ cd ~/loops/nightly-refactor
88
+ $EDITOR loop.yaml # your goals, and how each one is checked
89
+ loopsmith validate loop.yaml
90
+ loopsmith plan loop.yaml
91
+ ./run.sh # run.cmd on Windows
92
+ ```
93
+
94
+ ### `validate` fails on purpose
95
+
96
+ ```
97
+ error pre_execution: 2 step(s) not marked done: Run this task manually end to
98
+ end at least once; Write down what 'done' means in checkable terms.
99
+ Automating before understanding produces fast, confident garbage
100
+ ```
101
+
102
+ That refusal is the most valuable thing the tool does. Do the task by hand once —
103
+ the manual run *is* the spec. Mark each `pre_execution` step `done: true` once you
104
+ actually have.
105
+
106
+ ## What a config looks like
107
+
108
+ Ten sections, **A** to **J**: information, the manual work list, goals,
109
+ validations, success criteria, stop gates, schedules, constraints, execution
110
+ guidelines, default skills. YAML or Markdown — the same model either way.
111
+
112
+ ```yaml
113
+ name: nightly-refactor
114
+ description: keep the payments module simple without breaking it
115
+
116
+ pre_execution:
117
+ - step: Ran the refactor by hand on one file and kept the diff
118
+ done: true
119
+
120
+ goals:
121
+ - name: simpler
122
+ description: Cyclomatic complexity down, behaviour unchanged.
123
+
124
+ validations:
125
+ - target: simpler
126
+ name: tests-still-pass
127
+ mode: objective
128
+ statement: The suite exits clean.
129
+ detector:
130
+ type: script
131
+ command: ./scripts/check-tests.sh
132
+ expect_exit: 0
133
+ blocking: true
134
+
135
+ success:
136
+ - target: overall
137
+ name: all-blocking-pass
138
+ mode: percentage
139
+ statement: Every blocking validation passes.
140
+ threshold: 1.0
141
+
142
+ stop_gates:
143
+ max_iterations: 8
144
+ max_revisions_per_node: 3
145
+ max_cost_usd: 5.0
146
+ no_progress_iterations: 3
147
+
148
+ graph:
149
+ nodes:
150
+ - id: refactor
151
+ role: builder
152
+ instruction: Simplify one function. State any assumption you had to make.
153
+ goals: [simpler]
154
+ isolated: true # its own git worktree
155
+ - id: review
156
+ role: judge
157
+ instruction: Check the diff against the brief. Pass or fail per check, with evidence.
158
+ depends_on: [refactor]
159
+ goals: [simpler]
160
+ tier: strong
161
+ ```
162
+
163
+ Detectors are `file_exists`, `regex`, `script`, and composites. Only a detector
164
+ can satisfy a goal — a model's opinion of its own work never does.
165
+
166
+ ## While it runs
167
+
168
+ | Question | Command |
169
+ |---|---|
170
+ | What does the gate say? | `loopsmith status <config> <run-id>` |
171
+ | What happened? | `loopsmith ledger <config> <run-id>` |
172
+ | Why did it stop? | the last line of `logs/<run-id>.log` |
173
+ | What does it want changed about itself? | `loopsmith proposals <config> <run-id>` |
174
+ | Which providers can it reach? | `loopsmith providers <config>` |
175
+ | Will this machine get in the way? | `loopsmith doctor <config>` |
176
+
177
+ **The loop never edits its own config.** Changes to goals, validations, success
178
+ criteria, and sub-agent adoption are written as *proposals* for a human to apply.
179
+
180
+ ## Providers and BYOK
181
+
182
+ Every provider is a command template, which is what makes bring-your-own-key
183
+ free: Claude Code, Ollama, a Grok CLI, an OpenAI-compatible endpoint driven by
184
+ `curl`, an MCP server over stdio — all of them are "a program you run with a
185
+ prompt". Adding one is a config edit, never a rebuild.
186
+
187
+ `requires_env` names variables that must **exist**. loopsmith never reads their
188
+ values, so a key cannot reach a prompt, a log, or the ledger.
189
+
190
+ > ⚠ Never paste an API key into a chat window, a config file, or an issue. If one
191
+ > ends up somewhere it should not be, rotate it — deleting the message is not
192
+ > enough.
193
+
194
+ ## How this distribution installs the binary
195
+
196
+ The binary is fetched **on first run**, not during `pip install`, and cached under
197
+ `~/.loopsmith/bin/<version>/` (override with `LOOPSMITH_HOME`).
198
+
199
+ That is deliberate. A wheel that downloads at install time breaks in every
200
+ environment that installs without a network and runs with one — CI images, Docker
201
+ build stages, locked-down build hosts — and the failure surfaces as an install
202
+ error for a package the user has not tried to use yet.
203
+
204
+ Every download is **verified against the release's published `SHA256SUMS` before it
205
+ is executed**. Fetching a binary and running it unverified is a supply-chain hole
206
+ with a progress bar.
207
+
208
+ Prebuilt for:
209
+
210
+ | Platform | Target |
211
+ |---|---|
212
+ | Linux x86_64 (glibc) | `x86_64-unknown-linux-gnu` |
213
+ | Linux x86_64 (musl, auto-detected) | `x86_64-unknown-linux-musl` |
214
+ | Linux arm64 | `aarch64-unknown-linux-gnu` |
215
+ | macOS Intel | `x86_64-apple-darwin` |
216
+ | macOS Apple silicon | `aarch64-apple-darwin` |
217
+ | Windows x86_64 | `x86_64-pc-windows-msvc` |
218
+
219
+ Anywhere else, build from source — it is the same program:
220
+
221
+ ```bash
222
+ cargo install loopsmith
223
+ ```
224
+
225
+ ## The distribution name
226
+
227
+ `loopsmith` on PyPI was already registered by an unrelated project, so this
228
+ distribution is `loopsmith-cli`. The installed command is `loopsmith` either way.
229
+ Elsewhere: [`loopsmith`](https://crates.io/crates/loopsmith) on crates.io,
230
+ [`@bitphill/loopsmith`](https://www.npmjs.com/package/@bitphill/loopsmith) on npm,
231
+ and the `bitphill/loopsmith` Homebrew tap.
232
+
233
+ ## Documentation
234
+
235
+ - [Full README](https://github.com/bitphill/loopsmith#readme)
236
+ - [Section-by-section config reference](https://github.com/bitphill/loopsmith/blob/main/HOW-TO-USE.md)
237
+ - [Architecture and the reasoning behind it](https://github.com/bitphill/loopsmith/blob/main/README-DETAIL.md)
238
+ - [Thirteen worked examples](https://github.com/bitphill/loopsmith/tree/main/config/examples)
239
+ - [Changelog](https://github.com/bitphill/loopsmith/blob/main/CHANGELOG.md)
240
+
241
+ MIT licensed. © bitphill
@@ -1,54 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: loopsmith-cli
3
- Version: 0.1.2
4
- Summary: Self-evolving agent loops behind a deterministic verification gate. Installs the prebuilt Rust binary as `loopsmith`.
5
- Author-email: bitphill <bitphill@tuta.com>
6
- License-Expression: MIT
7
- Project-URL: Homepage, https://github.com/bitphill/loopsmith
8
- Project-URL: Repository, https://github.com/bitphill/loopsmith
9
- Project-URL: Changelog, https://github.com/bitphill/loopsmith/blob/main/CHANGELOG.md
10
- Project-URL: Issues, https://github.com/bitphill/loopsmith/issues
11
- Keywords: agent,loop,llm,orchestration,cli,rust
12
- Classifier: Development Status :: 4 - Beta
13
- Classifier: Environment :: Console
14
- Classifier: Intended Audience :: Developers
15
- Classifier: Operating System :: POSIX :: Linux
16
- Classifier: Operating System :: MacOS :: MacOS X
17
- Classifier: Operating System :: Microsoft :: Windows
18
- Classifier: Programming Language :: Rust
19
- Classifier: Topic :: Software Development :: Build Tools
20
- Requires-Python: >=3.8
21
- Description-Content-Type: text/markdown
22
-
23
- # loopsmith-cli
24
-
25
- Self-evolving agent loops. The gate is code, so "done" cannot be argued.
26
-
27
- ```bash
28
- pip install loopsmith-cli
29
- loopsmith doctor
30
- loopsmith new --path ~/loops/my-loop --purpose "keep the module simple"
31
- ```
32
-
33
- This package downloads the prebuilt Rust binary for your platform on first run,
34
- from the matching
35
- [GitHub release](https://github.com/bitphill/loopsmith/releases), and verifies it
36
- against the release's published `SHA256SUMS` before executing it. The installed
37
- command is `loopsmith`.
38
-
39
- Prebuilt for Linux (x86_64 glibc and musl, aarch64), macOS (x86_64 and Apple
40
- silicon), and Windows (x86_64). Anywhere else, build from source:
41
-
42
- ```bash
43
- cargo install loopsmith
44
- ```
45
-
46
- The distribution is named `loopsmith-cli` because `loopsmith` on PyPI was already
47
- registered by an unrelated project. The command is `loopsmith` regardless.
48
-
49
- The download happens on first run rather than during `pip install`, so an image
50
- that is built without a network and run with one still works.
51
-
52
- Full documentation: <https://github.com/bitphill/loopsmith>
53
-
54
- MIT licensed.
@@ -1,32 +0,0 @@
1
- # loopsmith-cli
2
-
3
- Self-evolving agent loops. The gate is code, so "done" cannot be argued.
4
-
5
- ```bash
6
- pip install loopsmith-cli
7
- loopsmith doctor
8
- loopsmith new --path ~/loops/my-loop --purpose "keep the module simple"
9
- ```
10
-
11
- This package downloads the prebuilt Rust binary for your platform on first run,
12
- from the matching
13
- [GitHub release](https://github.com/bitphill/loopsmith/releases), and verifies it
14
- against the release's published `SHA256SUMS` before executing it. The installed
15
- command is `loopsmith`.
16
-
17
- Prebuilt for Linux (x86_64 glibc and musl, aarch64), macOS (x86_64 and Apple
18
- silicon), and Windows (x86_64). Anywhere else, build from source:
19
-
20
- ```bash
21
- cargo install loopsmith
22
- ```
23
-
24
- The distribution is named `loopsmith-cli` because `loopsmith` on PyPI was already
25
- registered by an unrelated project. The command is `loopsmith` regardless.
26
-
27
- The download happens on first run rather than during `pip install`, so an image
28
- that is built without a network and run with one still works.
29
-
30
- Full documentation: <https://github.com/bitphill/loopsmith>
31
-
32
- MIT licensed.
@@ -1,54 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: loopsmith-cli
3
- Version: 0.1.2
4
- Summary: Self-evolving agent loops behind a deterministic verification gate. Installs the prebuilt Rust binary as `loopsmith`.
5
- Author-email: bitphill <bitphill@tuta.com>
6
- License-Expression: MIT
7
- Project-URL: Homepage, https://github.com/bitphill/loopsmith
8
- Project-URL: Repository, https://github.com/bitphill/loopsmith
9
- Project-URL: Changelog, https://github.com/bitphill/loopsmith/blob/main/CHANGELOG.md
10
- Project-URL: Issues, https://github.com/bitphill/loopsmith/issues
11
- Keywords: agent,loop,llm,orchestration,cli,rust
12
- Classifier: Development Status :: 4 - Beta
13
- Classifier: Environment :: Console
14
- Classifier: Intended Audience :: Developers
15
- Classifier: Operating System :: POSIX :: Linux
16
- Classifier: Operating System :: MacOS :: MacOS X
17
- Classifier: Operating System :: Microsoft :: Windows
18
- Classifier: Programming Language :: Rust
19
- Classifier: Topic :: Software Development :: Build Tools
20
- Requires-Python: >=3.8
21
- Description-Content-Type: text/markdown
22
-
23
- # loopsmith-cli
24
-
25
- Self-evolving agent loops. The gate is code, so "done" cannot be argued.
26
-
27
- ```bash
28
- pip install loopsmith-cli
29
- loopsmith doctor
30
- loopsmith new --path ~/loops/my-loop --purpose "keep the module simple"
31
- ```
32
-
33
- This package downloads the prebuilt Rust binary for your platform on first run,
34
- from the matching
35
- [GitHub release](https://github.com/bitphill/loopsmith/releases), and verifies it
36
- against the release's published `SHA256SUMS` before executing it. The installed
37
- command is `loopsmith`.
38
-
39
- Prebuilt for Linux (x86_64 glibc and musl, aarch64), macOS (x86_64 and Apple
40
- silicon), and Windows (x86_64). Anywhere else, build from source:
41
-
42
- ```bash
43
- cargo install loopsmith
44
- ```
45
-
46
- The distribution is named `loopsmith-cli` because `loopsmith` on PyPI was already
47
- registered by an unrelated project. The command is `loopsmith` regardless.
48
-
49
- The download happens on first run rather than during `pip install`, so an image
50
- that is built without a network and run with one still works.
51
-
52
- Full documentation: <https://github.com/bitphill/loopsmith>
53
-
54
- MIT licensed.
File without changes