Skip to content

docs: sync README files with latest repo state #381

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
yyiilluu wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: sync README files with latest repo state #381

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion reflexio/server/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -424,13 +424,14 @@ Key files:
- `agent_success_evaluation_constants.py`: Output schema (`AgentSuccessEvaluationOutput`)
- `agent_success_evaluation_utils.py`: Message construction utilities
- `scheduler.py`: `GroupEvaluationScheduler` singleton - min-heap priority queue with daemon thread, defers evaluation until 10 min after last request in session
- `sampling.py`: deterministic per-session sampling for the session-success and retrieved-learning judge families; the publish scheduler samples once and passes explicit booleans to the runner

@coderabbitai coderabbitai Bot Jul 25, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Align the flow description with the documented sampling owner.

This new entry correctly says generation_service.py performs publish-path sampling, but the adjacent flow still routes directly through agent_success_evaluation/scheduler.py. Clarify that the inactivity scheduler and publish admission are separate paths, or update the flow to include generation_service.py/sampling.py.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@reflexio/server/README.md` at line 427, Update the README flow description
around the sampling entry to distinguish inactivity scheduling from publish
admission: show that generation_service.py and sampling.py own publish-path
sampling, while agent_success_evaluation/scheduler.py handles the separate
inactivity path. Ensure the documented flow no longer implies that publish
admission routes directly through the inactivity scheduler.

- `runner.py`: `run_group_evaluation()` - fetches all requests/interactions for a session, builds `RequestInteractionDataModel` list, runs `service.py`, then the retrieved-learning phase; returns `GroupEvaluationOutcome` (per-family statuses)
- `components/retrieved_learning_evaluator.py`: `RetrievedLearningEvaluator` - per-learning relevance/impact judges over `Interaction.retrieved_learnings`; results replace the session's `retrieved_learning_evaluation` snapshot atomically (generation + session-fingerprint fenced, see `services/storage/storage_base/retrieved_learning_state.py`)
- `services/storage/storage_base/evaluation_state_keys.py`: single source of truth for the three evaluation `_operation_state` key formats (agent-success marker, grade-on-demand cache, retrieved-learning state) shared by producers and governance erasure

**Flow**: Interactions → `agent_success_evaluation/scheduler.py` → `agent_success_evaluation/runner.py` → `agent_success_evaluation/service.py` → `agent_success_evaluation/components/evaluator.py` → `AgentSuccessEvaluationResult` → Storage

**Session-Level Evaluation**: Evaluator treats one user's `request_interaction_data_models` in a session as a single conversation. Sampling rate checked once per session (not per-request). Results are keyed by `(user_id, session_id, evaluation_name)` so reused session IDs across users do not clobber each other.
**Session-Level Evaluation**: Evaluator treats one user's `request_interaction_data_models` in a session as a single conversation. Sampling is checked once per session (not per-request): `sampling_rate` controls session-success, `evaluation_only_sampling_rate` can override evaluation-only publishes, and `retrieved_learning_sampling_rate` lets retrieved-learning judges run at a separate density while inheriting `sampling_rate` when unset. Results are keyed by `(user_id, session_id, evaluation_name)` so reused session IDs across users do not clobber each other.

**Tool Context**: Reads `tool_can_use` from root `Config` level (shared with playbook extraction).

Expand Down
2 changes: 1 addition & 1 deletion reflexio/server/services/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ strings before deleting old import paths in the same PR.
|-----------|-------------|-----------|
| `profile/` | `ProfileGenerationService` | `service.py`, `components/extractor.py`, `components/consolidator.py` |
| `playbook/` | `PlaybookGenerationService` | `components/extractor.py`, `components/consolidator.py`, `components/aggregator.py` (cluster-fingerprint change detection) — has its own [README](playbook/README.md) |
| `agent_success_evaluation/` | `AgentSuccessEvaluationService` | `service.py` (session-level service), `runner.py` (`run_group_evaluation`), `scheduler.py` (`GroupEvaluationScheduler`, 10-min defer), `regen_jobs.py`, `components/evaluator.py` |
| `agent_success_evaluation/` | `AgentSuccessEvaluationService` | `service.py` (session-level service), `runner.py` (`run_group_evaluation`), `scheduler.py` (`GroupEvaluationScheduler`, 10-min defer), `sampling.py` (per-family session gates), `regen_jobs.py`, `components/evaluator.py` |

## Durable and Async Extraction

Expand Down
7 changes: 7 additions & 0 deletions reflexio/server/services/agent_success_evaluation/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,20 @@ Session-level agent success evaluation module.
- `service.py`: `AgentSuccessEvaluationService`, the request-path service that runs configured evaluators and saves result rows.
- `runner.py`: `run_group_evaluation(...)`, the background/manual workflow entry point that loads a session, runs the service, and marks operation state. After agent-success work it also runs the retrieved-learning evaluation (independent completion; generation + session-fingerprint fenced) and returns a `GroupEvaluationOutcome` carrying both statuses.
- `scheduler.py`: `GroupEvaluationScheduler`, the deferred inactivity scheduler.
- `sampling.py`: deterministic per-session sampling gates for the session-success and retrieved-learning judge families. `generation_service.py` is the only scheduled-publish caller; it samples once, admits the session when either family is selected, and passes booleans to the runner.
- `components/evaluator.py`: `AgentSuccessEvaluator`, the LLM evaluator component.
- `components/retrieved_learning_evaluator.py`: `RetrievedLearningEvaluator`, per-learning relevance/impact judges over `Interaction.retrieved_learnings`; results go to the `retrieved_learning_evaluation` table.
- `regen_jobs.py`: regeneration job planning and execution; remains root-level because API/admin regenerate flows import it directly.
- `_eval_health.py`: producer/scheduler health counters.
- `agent_success_evaluation_constants.py`: prompt/model output constants.
- `agent_success_evaluation_utils.py`: request DTO and prompt-message construction helpers.

## Sampling Contract

- `AgentSuccessConfig.sampling_rate` controls the session-success judge; `evaluation_only_sampling_rate` can override it for evaluation-only publishes.
- `AgentSuccessConfig.retrieved_learning_sampling_rate` controls the retrieved-learning relevance/impact judges and inherits `sampling_rate` when unset.
- Direct runner callers (regen jobs and on-demand grade routes) leave the sampling booleans at their defaults and run both families; sampling remains a scheduler/publish decision.

## Prompt IDs

- Owns `agent_success_evaluation`, `retrieved_learning_relevance`, and `retrieved_learning_impact`.
Expand Down