Feature (optional): store context hydration helper #8

New Issue

2026-02-16T04:15:07-05:00

yindo commented

2026-02-16 04:15:07 -05:00

Originally created by @lwyBZss8924d on GitHub (Sep 18, 2025).

Summary

Provide a helper API to hydrate context lines for ranked results, simplifying CLI/orchestrator code that needs to render snippets.

Motivation

Multiple callers (CLI, agents) need to read files and extract n_lines context around a matched line.
Centralizing this logic improves consistency and reduces duplication.

Proposed API (Rust)

// File: src/workspace/store.rs
use anyhow::Result;
use crate::workspace::store::RankedLine;

pub async fn hydrate_context(
    &self,
    ranked: &[RankedLine],
    n_lines: usize,
) -> Result<Vec<(RankedLine, Vec<String>)>> {
    // Reads each file once, extracts [start..end) lines, returns alongside RankedLine
}

Notes

This is an optional helper; not required for JSON output features.
search CLI could reuse it when --output json to include the lines field consistently for workspace-backed results.

Acceptance criteria

Helper compiles and is covered by a basic test reading temp files.
No change to defaults unless explicitly used by callers.

Originally created by @lwyBZss8924d on GitHub (Sep 18, 2025). ## Summary Provide a helper API to hydrate context lines for ranked results, simplifying CLI/orchestrator code that needs to render snippets. ## Motivation - Multiple callers (CLI, agents) need to read files and extract `n_lines` context around a matched line. - Centralizing this logic improves consistency and reduces duplication. ## Proposed API (Rust) ```rust // File: src/workspace/store.rs use anyhow::Result; use crate::workspace::store::RankedLine; pub async fn hydrate_context( &self, ranked: &[RankedLine], n_lines: usize, ) -> Result<Vec<(RankedLine, Vec<String>)>> { // Reads each file once, extracts [start..end) lines, returns alongside RankedLine } ``` ## Notes - This is an optional helper; not required for JSON output features. - `search` CLI could reuse it when `--output json` to include the `lines` field consistently for workspace-backed results. ## Acceptance criteria - Helper compiles and is covered by a basic test reading temp files. - No change to defaults unless explicitly used by callers.

yindo commented

2026-02-16 04:15:07 -05:00

@lwyBZss8924d commented on GitHub (Sep 18, 2025):

Intent: standardize snippet packaging for citations and verification in agentic flows.

Why a context hydration helper matters:

Many callers independently re-implement "read file → slice [start..end) → return lines"; centralizing prevents drift and subtle off-by-one bugs.
For hierarchical navigation, agents need consistent, paragraph/line windows for citations (file:start::end) and judge steps.
Single pass I/O (read each file once) also avoids redundant disk ops when top-K spans multiple lines in the same file.

Scope

Optional helper only, does not alter existing APIs or defaults.

Outcome

Consistent evidence packaging across CLI and programmatic use, improving reliability of autonomous, recursive retrieval loops.

@lwyBZss8924d commented on GitHub (Sep 18, 2025): Intent: standardize snippet packaging for citations and verification in agentic flows. Why a context hydration helper matters: - Many callers independently re-implement "read file → slice [start..end) → return lines"; centralizing prevents drift and subtle off-by-one bugs. - For hierarchical navigation, agents need consistent, paragraph/line windows for citations (file:start::end) and judge steps. - Single pass I/O (read each file once) also avoids redundant disk ops when top-K spans multiple lines in the same file. Scope - Optional helper only, does not alter existing APIs or defaults. Outcome - Consistent evidence packaging across CLI and programmatic use, improving reliability of autonomous, recursive retrieval loops.

yindo commented

2026-02-16 04:15:07 -05:00

@lwyBZss8924d commented on GitHub (Sep 18, 2025):

Reference: OpenAI Model Selection Guide — Long-Context Agentic RAG

https://cookbook.openai.com/examples/partners/model_selection_guide/model_selection_guide#7-takeaways

Why a context hydration helper aligns with the Cookbook approach:

The hierarchical loop produces a small set of paragraph/line windows that need consistent packaging for citations (file:start::end) and LLM-as-judge verification.
Centralizing the "read once → slice [start..end) → return lines" logic avoids drift across CLI/programmatic callers and reduces redundant file I/O.

Agent example (excerpt) that consumes such snippets:

---
name: document-retriever
model: opus
---
# Depth-0/1/2 routing yields a shortlist of evidence windows per file.
# The agent emits citations and snippets into run artifacts, then verifies over cited text only.

A small helper in Store makes the evidence step straightforward and consistent across the ecosystem.

@lwyBZss8924d commented on GitHub (Sep 18, 2025): Reference: OpenAI Model Selection Guide — Long-Context Agentic RAG - https://cookbook.openai.com/examples/partners/model_selection_guide/model_selection_guide#7-takeaways Why a context hydration helper aligns with the Cookbook approach: - The hierarchical loop produces a small set of paragraph/line windows that need consistent packaging for citations (file:start::end) and LLM-as-judge verification. - Centralizing the "read once → slice [start..end) → return lines" logic avoids drift across CLI/programmatic callers and reduces redundant file I/O. Agent example (excerpt) that consumes such snippets: ```yaml --- name: document-retriever model: opus --- # Depth-0/1/2 routing yields a shortlist of evidence windows per file. # The agent emits citations and snippets into run artifacts, then verifies over cited text only. ``` A small helper in Store makes the evidence step straightforward and consistent across the ecosystem.

yindo commented

2026-02-16 04:15:07 -05:00

@logan-markewich commented on GitHub (Sep 18, 2025):

I'm not sure I totally understand the proposal here

The --n-lines param already provides the lines around the match hit. Is there something more that can be done here? Any example of usage/output would help!

@logan-markewich commented on GitHub (Sep 18, 2025): I'm not sure I totally understand the proposal here The `--n-lines` param already provides the lines around the match hit. Is there something more that can be done here? Any example of usage/output would help!

yindo referenced this issue

2026-02-16 04:15:15 -05:00

[PR #8] [MERGED] add examples with coding agents #21

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: run-llama/semtools#8