Natural-language scheme editing

claude-bot commented

2026-07-07 17:38:03 +00:00

Contributor

Goal

Let users refine a scheme with plain-language instructions — "make it warmer and slower," "more Halloween, less pastel," "add a second accent color" — and get back a validated candidate scheme.

Why it's valuable

Iris already has the SuggestionProvider abstraction with Ollama/Anthropic/OpenAI-compatible providers, a prompt builder, and Pydantic response validation. Natural-language editing is a high-delight, low-cost extension of that existing pipeline rather than net-new infrastructure.

Sketch

New endpoint POST /schemes/{id}/refine { instruction } that feeds the current scheme JSON + the instruction to the provider, reusing the existing validator + retry + fallback.
Reuse the daily-limit counter (AI_DAILY_LIMIT).
UI: a text box on the scheme editor with the same before/after preview as "Generate Suggestion."

Acceptance criteria

Instruction returns a schema-valid modified candidate
Reuses validation/retry/fallback and the daily cap
Before/after preview before saving
Provider-mocked tests (happy path + invalid response)

Proposed enhancement (brainstorm follow-up); builds on the M7 AI pipeline.

## Goal Let users refine a scheme with plain-language instructions — "make it warmer and slower," "more Halloween, less pastel," "add a second accent color" — and get back a validated candidate scheme. ## Why it's valuable Iris already has the `SuggestionProvider` abstraction with Ollama/Anthropic/OpenAI-compatible providers, a prompt builder, and Pydantic response validation. Natural-language editing is a high-delight, low-cost extension of that existing pipeline rather than net-new infrastructure. ## Sketch - New endpoint `POST /schemes/{id}/refine { instruction }` that feeds the current scheme JSON + the instruction to the provider, reusing the existing validator + retry + fallback. - Reuse the daily-limit counter (`AI_DAILY_LIMIT`). - UI: a text box on the scheme editor with the same before/after preview as "Generate Suggestion." ## Acceptance criteria - [ ] Instruction returns a schema-valid modified candidate - [ ] Reuses validation/retry/fallback and the daily cap - [ ] Before/after preview before saving - [ ] Provider-mocked tests (happy path + invalid response) Proposed enhancement (brainstorm follow-up); builds on the M7 AI pipeline.

claude-bot added the

labels

2026-07-07 17:39:36 +00:00

claude-bot added this to the v1.1.0 milestone

2026-07-15 15:32:56 +00:00

rbrooks referenced this issue from a commit

2026-09-05 00:43:12 +00:00

Edit a scheme by describing the change (#22)

claude-bot referenced this issue from a pull request that will close it,

2026-09-05 00:43:27 +00:00

Edit a scheme by describing the change (#22) #130

claude-bot closed this issue

2026-09-05 00:50:27 +00:00

claude-bot referenced this issue from a commit

2026-09-05 00:50:28 +00:00

Edit a scheme by describing the change (#22) (#130)

claude-bot commented

2026-09-05 00:50:38 +00:00

Author

Contributor

Landed in #130 (squash-merged to main). All four acceptance criteria met.

The design question was what happens on failure, and it splits refinement from generation cleanly.

Generation falls back to a built-in template when the model fails, which is right — it has nothing to lose, and a template beats no scheme. Refinement starts from the user's own work, so the same fallback would replace what they were editing with a generic template: losing work rather than declining to change it. So RefinementFailedError is a distinct exception surfacing as a 502 whose message says the scheme is unchanged, and it is.

It proposes; it never writes. The endpoint returns a before and an after; accepting one loads it into the editor's own controls, and the user saves with the ordinary Save. That keeps an AI edit on exactly the path a manual edit takes — promotion to source: user (#99), staleness cleared, audit entry. Persisting directly would have let an AI edit of an approved scheme reach the lights with nobody seeing it. It's also why refining an approved scheme is allowed at all, where generation refuses to touch one.

Smaller things worth recording:

A segment the model forgets to mention keeps its current values. "Make it warmer" is not an instruction to delete a segment, and an omission is far likelier to be the model forgetting than the user asking. on is likewise carried forward rather than defaulted to true, which would switch a deliberately-off segment back on.
The refine prompt deliberately drops generation's few-shot examples. Those are whole festive schemes; showing them during an edit invites the model to replace the user's scheme with something resembling an example rather than adjusting what it was handed.
The instruction is length-bounded and rejected when blank. The cap counts requests, not tokens — an unbounded instruction makes one pasted novel a single request and a very large bill. My own test caught the blank case: I expected a rejection and got a 503 from the provider path, which meant a stray space was reaching the model.
A failed call still counts against the cap. Charging only for successes would make a broken provider an unlimited retry loop.

Verified: 27 new provider-mocked tests, ruff/mypy clean, 749 backend tests, frontend tsc/eslint clean, CI green.

Landed in #130 (squash-merged to `main`). All four acceptance criteria met. **The design question was what happens on failure**, and it splits refinement from generation cleanly. Generation falls back to a built-in template when the model fails, which is right — it has nothing to lose, and a template beats no scheme. Refinement starts from the user's own work, so the *same* fallback would replace what they were editing with a generic template: losing work rather than declining to change it. So `RefinementFailedError` is a distinct exception surfacing as a 502 whose message says the scheme is unchanged, and it is. **It proposes; it never writes.** The endpoint returns a before and an after; accepting one loads it into the editor's own controls, and the user saves with the ordinary Save. That keeps an AI edit on exactly the path a manual edit takes — promotion to `source: user` (#99), staleness cleared, audit entry. Persisting directly would have let an AI edit of an *approved* scheme reach the lights with nobody seeing it. It's also why refining an approved scheme is allowed at all, where generation refuses to touch one. **Smaller things worth recording:** - A segment the model forgets to mention keeps its current values. "Make it warmer" is not an instruction to delete a segment, and an omission is far likelier to be the model forgetting than the user asking. `on` is likewise carried forward rather than defaulted to true, which would switch a deliberately-off segment back on. - The refine prompt deliberately drops generation's few-shot examples. Those are whole festive schemes; showing them during an *edit* invites the model to replace the user's scheme with something resembling an example rather than adjusting what it was handed. - The instruction is length-bounded and rejected when blank. The cap counts requests, not tokens — an unbounded instruction makes one pasted novel a single request and a very large bill. **My own test caught the blank case**: I expected a rejection and got a 503 from the provider path, which meant a stray space was reaching the model. - A failed call still counts against the cap. Charging only for successes would make a broken provider an unlimited retry loop. Verified: 27 new provider-mocked tests, `ruff`/`mypy` clean, 749 backend tests, frontend `tsc`/`eslint` clean, CI green.

claude-bot referenced this issue

2026-09-05 01:37:41 +00:00

README screenshots and an optional public demo instance #136

Rows
Columns

Natural-language scheme editing #22

Goal

Why it's valuable

Sketch

Acceptance criteria