Skip to content

feat(evaluation): Improve iteration loop efficiency - #1101

Merged
AkhileshNegi merged 7 commits into
mainfrom
feature/evaluation-iteration-loop
Aug 26, 2026
Merged

AkhileshNegi merged 7 commits into
mainfrom
feature/evaluation-iteration-loop

Conversation

@AkhileshNegi

@AkhileshNegi AkhileshNegi commented Aug 3, 2026 •

Copy link
Copy Markdown
Collaborator

Issue

Closes #1159

Summary

  • Before: Improving a config's prompt required manually running an eval, reading scores, calling improve-prompt, then re-running the eval — repeated by hand each round.
  • Now: POST /api/v2/evaluations/iterations kicks off a self-driving eval → improve-prompt → eval loop via a LangGraph state machine (start_eval_node → wait_eval_node → start_improve_node → wait_improve_node, looping back or finalizing), returns 202 immediately, and delivers the round-by-round report to callback_url once it stops.
  • Stop score = mean of Adherence to Ground Truth + Adherence to Prompt; Adherence to Knowledge Base is recorded per round for visibility only and never gates stopping. Stops on 3 consecutive low-delta rounds (ceiling_reached), a max_rounds cap (max_rounds_reached), or a hard round failure (round_failed).
  • New evaluation_iteration_run table is thin bookkeeping only (status/stop_reason/dataset/config/callback) — round-by-round state lives in a Postgres LangGraph checkpoint keyed by thread_id = str(iteration_run.id).
  • Resumption reuses the existing /cron/evaluations tick (dispatch_pending_evaluation_iteration_resumes) rather than a new scheduler; no orchestrator polls a provider directly.
  • Migration 082_add_evaluation_iteration_run.py adds the new table; docs/wiki/modules/evaluations.md and domain-map.md updated per the maintenance rule.

Checklist

Before submitting a pull request, please ensure that you mark these task.

  • Ran fastapi run --reload app/main.py or docker compose up in the repository root and test.
  • If you've fixed a bug or added code that is tested and has test cases.

Notes

Design detail: docs/wiki/modules/evaluations.md (Async section) and docs/architecture/kaapi-evaluations-ARCHITECTURE.md.

@coderabbitai

coderabbitai Bot commented Aug 3, 2026 •

Copy link
Copy Markdown
Contributor

Important

Review skipped

Auto reviews are limited based on label configuration.

🏷️ Required labels (at least one) (1)
  • ready-for-review

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 8e249aca-be8a-4cff-8744-92eaca1335d0

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@github-actions github-actions Bot changed the title Evaluation: Iteration loop feat(evaluation): Improve iteration loop efficiency Aug 3, 2026
@AkhileshNegi
AkhileshNegi marked this pull request as ready for review August 19, 2026 10:38
…eration-loop

# Conflicts:
#	backend/app/services/evaluations/fast.py
#	docs/wiki/modules/evaluations.md
@AkhileshNegi
AkhileshNegi requested a review from vprashrex August 20, 2026 05:28
@github-actions

github-actions Bot commented Aug 20, 2026 •

Copy link
Copy Markdown

OpenAPI changes   ⚪ No API surface changes

Note

This PR does not modify the API contract.

main ↔ df5eead9 · generated by oasdiff

@codecov

codecov Bot commented Aug 20, 2026

Copy link
Copy Markdown

{"finalize_node": "finalize_node", "start_improve_node": "start_improve_node"},
)
graph.add_edge("start_improve_node", "wait_improve_node")
graph.add_edge("wait_improve_node", "start_eval_node")

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wait_improve_node currently has an unconditional edge, so round_failed never reaches finalize_node and the webhook doesn't fire. Reuse route_after_eval here, mapping the continue branch to start_eval_node, so failures finalize correctly and both wait nodes follow the same pattern.

graph.add_conditional_edges(
    "wait_improve_node",
    route_after_eval,
    {"finalize_node": "finalize_node", "start_improve_node": "start_eval_node"},
)

)


def _mark_iteration_run_failed(

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

here mark the row FAILED but never hit the callback_url, caller just waits forever. row already has the url, can we POST a failure report from here too?

so a caller passing an oversized value degrades to the safety cap instead of
failing outright.
"""
resolved_max_rounds = min(

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Silently capping max_rounds at 25 is surprising when the caller asks for 100. Since each round costs money, we should reject invalid values instead. Add le=EVAL_ITERATION_MAX_ROUNDS_HARD_CAP to EvaluationIterationCreateRequest so FastAPI returns a 422 and the limit is reflected in OpenAPI.

just nitpick

Comment thread backend/app/alembic/versions/082_add_evaluation_iteration_run.py
Comment thread backend/app/services/evaluations/iteration_graph.py
@AkhileshNegi AkhileshNegi self-assigned this Aug 26, 2026
@AkhileshNegi AkhileshNegi added the enhancement New feature or request label Aug 26, 2026
@AkhileshNegi
AkhileshNegi merged commit 0438c01 into main Aug 26, 2026
2 of 3 checks passed
@AkhileshNegi
AkhileshNegi deleted the feature/evaluation-iteration-loop branch August 26, 2026 17:11
@github-actions

Copy link
Copy Markdown

🎉 This PR is included in version 1.5.0-main.11 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request released on @main

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Evaluation: Automate prompt improvement

2 participants