feat: LLM token ergonomics — list_paragraphs default cap, compact SearchResult, context() helper (ISSUES.md #43)#60
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:
|
1 participant
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