ReCUR

ReCUR: Recursive Cognition Upgrade Routine

ReCUR is a command-line tool designed to elevate the quality of large language model (LLM) outputs through a recursive, multi-phase improvement loop. Unlike single-shot prompting, ReCUR works by producing an initial response and then subjecting it to successive refinement rounds, where multiple alternatives are generated, graded, and compared using customizable rubrics.

Core Workflow

1. Prompt + Context: You start with a user prompt and may optionally pass in one or more file fragments. These fragments act as contextual anchors to guide model generations.
2. Initial Generation: A base response is generated from your prompt via a pluggable LLM backend (Google GenAI by default).
3. Round Estimation: The system decides how many recursive refinement rounds to perform using either a heuristic based on token count or a manual override.
4. Alternative Generation: For each round, ReCUR spawns N concurrent alternatives in parallel, each trying to improve upon the current best response.
5. Scoring & Promotion: Each alternative is scored against the current best using a detailed grading rubric (clarity, correctness, relevance). If a candidate scores higher, it becomes the new baseline for future rounds.
6. Final Selection: After all rounds, ReCUR shuffles the pool of unique responses and performs a final grade-based comparison to select the best possible answer.

Features

• Fully configurable: supports YAML configs and CLI overrides
• Fragment support: inject contextual documents to guide model behavior
• Parallel alt-generation using asyncio
• Rubric-based grading with support for custom or domain-specific criteria
• LLM abstraction layer for easy provider swapping (e.g., Echo for testing)
• Structured JSON logging and optional audit output
• Robust logging via Loguru with configurable levels and output
• Comprehensive test suite with >90% test coverage using pytest
• CI linting, formatting, and typing checks via Ruff, Black, and mypy

Use Cases

• Education: Refine explanations over rounds to ensure clarity for different age groups or learning levels
• Documentation: Improve technical writing using structured context and a rubric favoring precision
• Creative Writing: Iterate story drafts using style- or tone-aware rubrics
• QA Assistant: Combine code snippets with question prompts to generate answers with increasing relevance

Fragment Support

You can specify one or more context files using the --context-file CLI option or in the config file. These fragments will be automatically prepended to every prompt issued to the LLM. This is ideal for use cases like:

• Providing reference documentation
• Maintaining consistency in technical language
• Embedding system design files or data schemas

Example CLI Usage

recur
  --prompt "Improve this design spec"
  --context-file ./docs/design.md
  --rubric-file ./rubrics/clarity.yml
  --rounds 3
  --alts 4
  --temperature 0.3
  --audit-json run.json
  --output-file final.txt

Customization

All major components (LLM, grader, selector) are modular and swappable. Want to use Claude or Mistral instead of Gemini? Just implement the LLM interface. Prefer cosine similarity over rubric scoring? Drop in a new grader class.

Getting Started

1. Clone the repo
2. Install dependencies: uv pip install -e .
3. Run a test query: uv run recur --prompt "Summarize general relativity"

Coming Soon

• Support for dynamic fragment updates (editable across rounds)
• Multi-agent voting and response fusion
• Live visual interface for tracking response evolution
• Integrated benchmarking and leaderboard mode

ReCUR offers an experimental but powerful approach to systematic AI output refinement. Whether you're engineering prompts, crafting content, or building intelligent tools, ReCUR puts quality control in your hands.

Designing a modular pipeline that cleanly separates LLM calls, grading, and selection while maintaining performance with asyncio and backoff strategies.

Advanced async patterns in Python, pluggable architecture for LLMs, structured logging with Loguru, CLI + config merging strategies.