codebrain_generate_verified

Instructions

Implementation Reference

• codebrain/server.py:235-281 (handler)

  The main handler function for the 'codebrain_generate_verified' tool. Decorated with @mcp.tool(), it implements a verifier loop: runs the LLM via chat(), checks output constraints (word limits, regex) using verifier.run_checks(), and retries with tightened instructions on failure up to max_retries times.

  @mcp.tool()
  async def codebrain_generate_verified(
      prompt: str,
      system: str = "",
      min_words: int | None = None,
      max_words: int | None = None,
      must_match: str | None = None,
      max_retries: int = 2,
      use_brain: bool = True,
  ) -> str:
      """Generate with verifier loop — enforces word limits and regex schemas.
  
      Runs `codebrain_generate`, then checks the output against the requested
      constraints. On failure, retries with a tightened instruction that
      names the specific problem. Gives up after `max_retries` attempts and
      returns the last output with a `[codebrain warning] ...` prefix.
  
      Args:
          prompt: The task description or content request.
          system: Optional system message to steer tone / format / constraints.
          min_words: Minimum output word count (None = unbounded).
          max_words: Maximum output word count (None = unbounded).
          must_match: Regex pattern the output must match (`re.search` semantics).
          max_retries: Max retry attempts on verification failure (default 2).
          use_brain: If true, prepend `.brain/context.md` to the system prompt.
      """
      composed_system = _compose_system(system, use_brain)
      current_prompt = prompt
      output = ""
      reason = ""
      for attempt in range(max_retries + 1):
          try:
              output = await chat(current_prompt, system=composed_system)
          except BackendError as exc:
              return f"[codebrain error] {exc}"
          ok, reason = verifier.run_checks(
              output,
              min_words=min_words,
              max_words=max_words,
              must_match=must_match,
          )
          if ok:
              return output
          current_prompt = (
              prompt + "\n\n" + verifier.tightened_retry_instruction(reason)
          )
      return f"[codebrain warning] verification failed after {max_retries} retries ({reason}):\n\n{output}"

• codebrain/server.py:236-260 (schema)

  Input schema for the tool defined in the function signature: prompt (str), system (str, optional), min_words (int or None), max_words (int or None), must_match (str or None), max_retries (int, default 2), use_brain (bool, default True). Returns str.

  async def codebrain_generate_verified(
      prompt: str,
      system: str = "",
      min_words: int | None = None,
      max_words: int | None = None,
      must_match: str | None = None,
      max_retries: int = 2,
      use_brain: bool = True,
  ) -> str:
      """Generate with verifier loop — enforces word limits and regex schemas.
  
      Runs `codebrain_generate`, then checks the output against the requested
      constraints. On failure, retries with a tightened instruction that
      names the specific problem. Gives up after `max_retries` attempts and
      returns the last output with a `[codebrain warning] ...` prefix.
  
      Args:
          prompt: The task description or content request.
          system: Optional system message to steer tone / format / constraints.
          min_words: Minimum output word count (None = unbounded).
          max_words: Maximum output word count (None = unbounded).
          must_match: Regex pattern the output must match (`re.search` semantics).
          max_retries: Max retry attempts on verification failure (default 2).
          use_brain: If true, prepend `.brain/context.md` to the system prompt.
      """

• codebrain/server.py:235-235 (registration)

  The tool is registered via the @mcp.tool() decorator on line 235, where 'mcp' is a FastMCP instance created on line 12.

  @mcp.tool()

• codebrain/verifier.py:57-92 (helper)

  The verifier.run_checks() helper runs all requested checks (word count, regex) and returns (ok, reason). The tightened_retry_instruction() helper (lines 86-92) builds the retry directive naming the specific failure.

  def run_checks(
      text: str,
      text_in: str | None = None,
      min_words: int | None = None,
      max_words: int | None = None,
      must_match: str | None = None,
      check_noop: bool = False,
  ) -> tuple[bool, str]:
      """Run every requested check in order and return on first failure.
  
      `check_noop` requires `text_in` to be provided.
      """
      if check_noop:
          if text_in is None:
              return False, "check_noop requires text_in"
          ok, reason = detect_noop(text_in, text)
          if not ok:
              return False, reason
      if min_words is not None or max_words is not None:
          ok, reason = check_word_count(text, min_words, max_words)
          if not ok:
              return False, reason
      if must_match is not None:
          ok, reason = check_regex_schema(text, must_match)
          if not ok:
              return False, reason
      return True, ""
  
  
  def tightened_retry_instruction(reason: str) -> str:
      """Build a one-line retry directive that names the specific failure."""
      return (
          f"Your previous output failed verification: {reason}. "
          "Regenerate addressing that specific problem. Output only the "
          "corrected result."
      )

• codebrain/server.py:25-33 (helper)

  The _compose_system() helper prepends the .brain/context.md project context to the system prompt when use_brain=True.

  def _compose_system(system: str, use_brain: bool) -> str:
      """Prepend project .brain context to the user-provided system prompt."""
      if not use_brain:
          return system
      brain = _load_brain_context()
      if not brain:
          return system
      header = "Project context (from .brain/context.md):\n" + brain
      return f"{header}\n\n{system}" if system else header