Repository navigation
feat: LLM token ergonomics — list_paragraphs default cap, compact SearchResult, context() helper (ISSUES.md #43) - #60
Merged
Conversation
…rchResult, context() helper (ISSUES.md #43) - list_paragraphs: bare calls now return at most 200 paragraphs; when more remain, a trailing "... N more paragraphs; use start=… or limit=None" notice gives the next start. Notices always begin with "..." and never match the P{i}#{hash} ref shape. limit=None restores the full listing. - list_paragraphs_structured: same 200-record default cap, silent (no notice record) to keep the result homogeneously typed; detect truncation by comparing len(result) with paragraph_count(). - SearchResult: new paragraph_index field (1-based, same integer as in paragraph_ref) and a compact one-line repr/str (SearchResult(P3#a7b2 occ=1 '30 days'), trailing spans_rev marker). - Document.context(ref, window=2): the paragraphs around a ref as ParagraphInfo records, clamped at document edges; shares ref validation with get_paragraph_location via the extracted _resolve_validated_ref(). - Internal callers that consume entries as refs (benchmarks, conftest find_ref, docstring example) now pass limit=None; README/quickstart/ SKILL.md/api.md rewritten to the notice-based pagination idiom; the docx-session eval help example uses limit=None so filtered output cannot silently miss matches past P200.
|
Warning Review limit reached
Next review available in: 22 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (8)
📝 WalkthroughWalkthroughParagraph listing now defaults to 200 entries with truncation notices, while structured listings remain silent when capped. Documents gain validated surrounding-context lookup, and search results expose paragraph indexes with compact representations. Tests, benchmarks, examples, and documentation reflect these contracts. ChangesParagraph API updates
Estimated code review effort: 4 (Complex) | ~45 minutes Sequence Diagram(s)sequenceDiagram
participant SearchResult
participant Document
participant ParagraphInfo
SearchResult->>Document: provide paragraph_ref
Document->>Document: validate index and paragraph hash
Document->>ParagraphInfo: return surrounding paragraph records
Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with 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.
Inline comments:
In `@docx_editor/document.py`:
- Around line 570-599: Update _resolve_validated_ref to return a named immutable
ResolvedRef dataclass containing the validated index, paragraph element, and
fetched paragraphs list. Modify get_paragraph_location and other callers to use
these fields, reusing ResolvedRef.paragraphs for context slicing instead of
calling getElementsByTagName("w:p") again, while preserving existing validation
behavior.
In `@skills/docx/SKILL.md`:
- Line 636: Remove the trailing space from the inline code span in the
paragraph-reference documentation, changing the displayed token to represent the
pipe without whitespace while preserving the surrounding explanation.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 1992c355-f711-4e0b-943f-085935f5be9e
📒 Files selected for processing (13)
README.mdbenchmarks/corpus/corpus_harness.pybenchmarks/hash_anchored_vs_plain.pydocs/api.mddocs/quickstart.mddocx_editor/document.pydocx_editor/session.pydocx_editor/track_changes.pyskills/docx/SKILL.mdtests/conftest.pytests/test_document.pytests/test_find_all.pytests/test_paragraph_hash.py
… detection, occ=0 examples, singular notice, no redundant DOM query
- document.py: '.. versionchanged::' reST directives replaced with Google-style
'Note:' sections (mkdocstrings' google parser renders the directive as
literal text); list_paragraphs_structured docstring example now demonstrates
truncation detection against a bounded call via the last record's index
(the limit=None example could never trigger the check); notice noun
pluralizes ('1 more paragraph'); _resolve_validated_ref returns the
validated paragraph list so get_paragraph_location no longer re-queries
the DOM.
- docs/api.md: bold 'Changed in 0.6.1:' label (file convention), occ=0 in the
repr example (paragraph_occurrence is 0-based), index-based truncation rule.
- SKILL.md: occ=0 repr example, index-based truncation rule.
…, complete limit=None sweep - track_changes.py: repr elides matched text past 60 chars (display only; the text attribute keeps the full match) — sentence-length search anchors otherwise blow up the exact token budget the compact repr exists for. - SKILL.md refs_only example and docx-session exec help example now pass limit=None like their siblings, so no entry can be a truncation notice. - README: merge the duplicated bare list_paragraphs() intro line into the pagination example. - docs/api.md: document the repr elision.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #60 +/- ##
=====================================
Coverage 95.7% 95.7%
=====================================
Files 11 11
Lines 3740 3764 +24
Branches 744 746 +2
=====================================
+ Hits 3581 3605 +24
Misses 73 73
Partials 86 86 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
pablospe
added a commit
that referenced
this pull request
Jul 30, 2026
…structure, workspace reset (ISSUES.md #52 + #60) Six code items plus two documentation items from the round-3/4 dogfood papercut list (ISSUES.md #52 and #60 — repo-local item numbers, not GitHub issues). - SearchResult stands in for (text, paragraph, occurrence) on replace, delete, insert_after, insert_before, add_comment and the four EditOperation constructors. Passing paragraph=/occurrence= alongside one raises rather than picking a winner. - ParagraphInfo gains in_table / style / outline_level, so a table of contents needs one list_paragraphs_structured() call instead of a second list_paragraph_locations() pass. - EditValidationResult.current_ref gives dry-run stale-hash rows the ref for the paragraph's current content. It clears the hash check only; the rebuilt operation is re-validated like any other. - Document.discard_workspace() replaces the deep Workspace import for resetting after a crashed script. - ExecResult/EvalResult gain started, distinguishing a timeout of your own running code from one that never left the kernel queue. - replace() trims whitespace-only spans character-wise, so a spacing fix is a pure insertion or deletion instead of an invisible del+ins pair. - Docs: pagination overshoot documented as a valid empty answer (no behaviour change), get_paragraph()/context() marked O(document). Two fidelity fixes found in review, both beyond the original scope: - w:delText never carried xml:space="preserve", so a conforming consumer trimmed the edges and rejecting a whitespace deletion restored the wrong spacing. Every tracked deletion whose text has a whitespace edge now carries the attribute. - ipykernel discards requests queued behind a command that raises. exec_code reported those as status="ok" (exit 0, no output) having run nothing; started now detects it, the exec CLI warns loudly, and eval names the discard instead of blaming its transport. Exit codes unchanged. word/styles.xml is memoized per Document and parsed without the line-tracking parser, keeping get_paragraph() at its previous per-call cost now that it needs the style maps; the location APIs get an ~11x win on repeat calls. Reviewed by three independent reviewers plus codex, red-teamed: 11 findings confirmed and fixed, 3 killed as false positives, 6 downgraded; a second pass caught and fixed an overstatement in the first round's own fix. 1409 passed, 2 skipped. CI green on Python 3.10-3.14.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements ISSUES.md #43 (LLM token ergonomics). Note: that number is a repo-local ISSUES.md item, not a GitHub issue — intentionally no
Closeskeyword.list_paragraphsdefault cap: a bare call now returns at most 200 paragraphs (previously unbounded). Whenever paragraphs remain beyond the returned window — default or explicitlimit— the last entry is a truncation notice, e.g."... 50 more paragraphs; use start=201 or limit=None", telling the caller the nextstart. Notice lines always begin with...and never match theP{i}#{hash}ref shape, so ref-consuming code can filter them withentry.startswith("...").limit=Nonerestores the full listing.list_paragraphs_structured: same 200-record default cap, but silent (no notice record) to keep the result homogeneously typed — truncation is detected by comparinglen(result)withparagraph_count().SearchResultergonomics: newparagraph_indexfield (1-based, the same integer embedded inparagraph_ref— no more string-parsing refs) and a compact one-linerepr/str(SearchResult(P3#a7b2 occ=1 '30 days'), with a trailingspans_revmarker) so printing a wholefind_all()list stays cheap.Document.context(ref, window=2): returns the paragraphs around a ref asParagraphInforecords, clamped at document edges — the "show me the section around this match" helper. Shares parse/bounds/hash validation withget_paragraph_locationvia the extracted_resolve_validated_ref().conftest.find_ref, a docstring example) now passlimit=None; README, quickstart, SKILL.md, and api.md rewritten to the notice-based pagination idiom; thedocx-session evalhelp example useslimit=Noneso filtered output cannot silently miss matches past P200.Testing
uv run pytest)TestListParagraphsDefaultCap(8 tests, 250-paragraph fixture),TestSearchResultErgonomics(5),TestDocumentContext(10, incl. stale-hash, out-of-range, closed-doc)ruff check/ruff format --checkclean;ty checkexit 0 with baseline-identical diagnosticsSummary by CodeRabbit
New Features
Documentation
Bug Fixes