best_engine_ai_helper.ralph module

ralph — the generic Ralph loop and its two instantiations.

The Ralph loop is the “produce, inspect, fix, repeat until a verdict” pattern used throughout the sprezzature suite. This module implements the generic driver and two concrete variants:

  • eyeball_loop: inspects a visual artifact (PNG) with a vision-language model; fixes the source code that generated it.

  • prose_loop: inspects prose with a text model enforcing a writing charter; fixes the text at paragraph-pair seams.

Both variants share the same generic driver so the convergence logic, iteration budget, and no-op guard are implemented once.

Author

Warith Harchaoui <warith.harchaoui@deraison.ai>

best_engine_ai_helper.ralph.eyeball_loop(source, *, kind, llm_chat, renderers=None, max_iters=6, on_iteration=None)[source]

Run the eyeball loop on a visual artifact source.

Renders the source to a PNG, critiques it with a VLM, applies a text-model fix to the source, and repeats. Uses the generic ralph_loop driver internally.

Parameters:

  • source (str) – Source text to render: a Vega-Lite JSON string, HTML, Mermaid, or TikZ.

  • kind (str) – Surface kind. Controls which renderer is selected: "vega", "html", "mermaid", "tikz", "svg".

  • llm_chat (callable) – The chat function from llm.py (or a compatible mock). Injected so tests can patch it without touching the module-level default.

  • renderers (dict or None) – Optional dict mapping kind strings to render callables (source_str) -> bytes. When None the function raises NotImplementedError pointing to the sprezzature-figures renderers.

  • max_iters (int) – Maximum iteration budget. Default 6.

  • on_iteration (callable or None) – Optional per-iteration callback.

Returns:

(final_source, history).

Return type:

tuple[str, list[tuple[int, str, dict]]]

Raises:

NotImplementedError – If renderers is None and no built-in renderer is available for kind. Wire in the renderers from sprezzature-figures.

best_engine_ai_helper.ralph.prose_loop(text, *, charter, llm_chat, max_passes=3)[source]

Enforce the writing charter on a prose block via paragraph-pair seam checks.

Implements WRITING.md §10 “Flow by Paragraph Pairs” locally. For each overlapping window (para n, para n+1), a text model checks the seam for bolted-on transitions, logic gaps, echoed words, and charter violations. When a seam needs fixing, a second call edits the last sentence of n and the opening of n+1. The loop repeats until a full pass makes no edit or the budget is spent.

Parameters:

  • text (str) – Prose block to refine. Paragraphs are separated by blank lines.

  • charter (str) – Writing charter excerpt to embed in every seam and fix prompt. Keeps the model focused on the specific rules that matter for this language.

  • llm_chat (callable) – The chat function from llm.py or a compatible mock.

  • max_passes (int) – Maximum number of full passes over all paragraph pairs. Default 3.

Returns:

The refined prose block with the same paragraph structure.

Return type:

str

Examples

>>> # With a mock llm that fixes nothing, the output equals the input
>>> def noop_chat(p, **kw): return '{"needs_fix": false, "reasons": []}'
>>> text = "Paragraph one.\n\nParagraph two."
>>> result = prose_loop(text, charter="No dashes.", llm_chat=noop_chat)
>>> result == text
True
best_engine_ai_helper.ralph.ralph_loop(source, *, render, inspect, apply_fix, verdict, max_iters=6, on_iteration=None)[source]

Run the produce-inspect-fix-repeat loop until convergence or budget is spent.

The caller supplies four callbacks that define the loop’s behaviour; the driver handles iteration, convergence detection, and history recording.

Parameters:

  • source (Any) – Initial artifact source: a file path, a code string, a prose block. The loop edits this value in place across iterations.

  • render (callable) – render(source) -> artifact — turn the source into an inspectable artifact. For the eyeball loop this renders a PNG; for the prose loop the artifact is the text itself (identity).

  • inspect (callable) – inspect(artifact) -> critique: str — examine the artifact and return a free-form critique string.

  • apply_fix (callable) – apply_fix(source, critique) -> new_source — edit the source to address the critique. Must return the same type as source.

  • verdict (callable) – verdict(critique) -> dict — decide whether to ship. The dict must have at minimum a boolean "ship" key.

  • max_iters (int) – Maximum number of produce-inspect-fix cycles. Default 6.

  • on_iteration (callable or None) – Optional callback called at the end of each iteration with arguments (iter_index, source, artifact, critique, verdict_dict). Use for logging or writing assessment files.

Returns:

(final_source, history) where history is a list of (iteration_index, critique, verdict_dict) triples.

Return type:

tuple[Any, list[tuple[int, str, dict]]]

Examples

>>> def mock_render(s):  return s + "_rendered"
>>> def mock_inspect(a): return "no issues"
>>> def mock_fix(s, c):  return s
>>> def mock_verdict(c): return {"ship": True, "blocking": [], "score": 1.0}
>>> src, hist = ralph_loop(
...     "source",
...     render=mock_render, inspect=mock_inspect,
...     apply_fix=mock_fix, verdict=mock_verdict,
... )
>>> src
'source'
>>> hist[0][2]["ship"]
True