docs(rag): document SearchResultItem support in build_context / deduplicate_chunks#435
docs(rag): document SearchResultItem support in build_context / deduplicate_chunks#435MervinPraison wants to merge 1 commit into
Conversation
…licate_chunks (fixes #431) - Updated docs/rag/module.mdx with new signatures accepting Union[Dict, SearchResultItem] - Added Tabs examples showing both dict and SearchResultItem usage - Documented metadata fallback behavior for source/filename lookup - Added cross-references in docs/rag/retrieval.mdx and docs/knowledge/overview.mdx - Follows AGENTS.md style guidelines with Mintlify components Co-authored-by: Mervin Praison <MervinPraison@users.noreply.github.com>
Qodo reviews are paused for this user.Troubleshooting steps vary by plan Learn more → On a Teams plan? Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center? |
|
Warning Review limit reached
More reviews will be available in 57 minutes and 40 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (3)
✨ 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 |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the documentation across several files to indicate that RAG context utilities, such as build_context and deduplicate_chunks, now directly support SearchResultItem objects and mixed inputs with automatic metadata fallback. However, the review feedback highlights a critical discrepancy: the underlying implementation in praisonaiagents/rag/context.py does not currently support these objects directly, which would result in runtime AttributeErrors. To resolve this, either the RAG context utility implementation must be updated to support SearchResultItem objects and the documented fallback behavior, or the documentation must be corrected to instruct users to convert these objects to dictionaries first.
| <Note> | ||
| Knowledge search returns `SearchResultItem` objects (see `praisonaiagents.knowledge.models`) that can be passed directly into RAG context utilities like `build_context` and `deduplicate_chunks`. | ||
| </Note> |
There was a problem hiding this comment.
This note states that SearchResultItem objects can be passed directly into build_context and deduplicate_chunks. However, doing so currently raises an AttributeError because those utility functions expect dictionaries and call .get() on the items.
Please update this note to mention that they must be converted to dictionaries first (e.g., using [r.to_dict() for r in results]), or ensure that the underlying RAG context utilities are updated to support SearchResultItem objects directly.
| <Tab title="SearchResultItem results"> | ||
| ```python | ||
| from praisonaiagents.rag import build_context, deduplicate_chunks | ||
| from praisonaiagents.knowledge.models import SearchResultItem | ||
|
|
||
| # SearchResultItem format | ||
| results = [ | ||
| SearchResultItem(text="First content", source="a.pdf", filename="a.pdf"), | ||
| SearchResultItem(text="Second content", source="b.pdf", filename="b.pdf"), | ||
| ] | ||
|
|
||
| # Mixed dict + object input also works | ||
| results.append({"text": "Third content", "metadata": {"filename": "c.pdf"}}) | ||
|
|
||
| # Build context from SearchResultItem objects | ||
| context, used_results = build_context( | ||
| results=results, | ||
| max_tokens=2000, | ||
| include_source=True, | ||
| ) | ||
|
|
||
| unique = deduplicate_chunks(results) | ||
| ``` | ||
| </Tab> |
There was a problem hiding this comment.
The code example shown here will raise an AttributeError: 'SearchResultItem' object has no attribute 'get' at runtime.
In praisonaiagents/rag/context.py, both build_context and deduplicate_chunks expect dictionaries and call .get("text"), .get("memory"), and .get("metadata") directly on the items in the results list. They do not currently support SearchResultItem objects directly.
To make this example work with the current codebase, the SearchResultItem objects must be converted to dictionaries first using .to_dict():
# Convert SearchResultItem objects to dicts before passing to context utilities
dict_results = [r.to_dict() if hasattr(r, "to_dict") else r for r in results]
context, used_results = build_context(
results=dict_results,
max_tokens=2000,
include_source=True,
)Alternatively, the implementation of build_context and deduplicate_chunks in praisonaiagents/rag/context.py should be updated to handle both dict and object types (similar to how DefaultCitationFormatter handles them using isinstance or getattr).
| <Note> | ||
| `build_context` and `deduplicate_chunks` accept a mix of `dict` results and `SearchResultItem` objects. When `include_source=True`, the label is taken from `metadata["filename"]` / `metadata["source"]` first, falling back to the top-level `filename` / `source` attribute on the item, and finally to `Source N`. | ||
| </Note> | ||
|
|
||
| ### Result Item Formats | ||
|
|
||
| The context utilities support two input formats with automatic fallback for metadata lookups: | ||
|
|
||
| | Lookup | 1st choice | 2nd choice | Fallback | | ||
| |--------|------------|------------|----------| | ||
| | `source` | `metadata["source"]` | `item.source` (object) / `item["source"]` (dict) | `""` | | ||
| | `filename` | `metadata["filename"]` | `item.filename` / `item["filename"]` | `""` | | ||
| | `text` | `item.text` / `item["text"]` | `item.memory` / `item["memory"]` | `""` (item skipped in `build_context`) | |
There was a problem hiding this comment.
The fallback behavior described in this note and table does not match the actual implementation in praisonaiagents/rag/context.py.
Currently, build_context only looks up metadata.get("source") and metadata.get("filename"). It does not fall back to top-level attributes like item.source or item.filename, nor does it support attribute/key lookups on SearchResultItem objects (which will cause an AttributeError as noted above).
Please either:
- Update the implementation of
build_contextanddeduplicate_chunksinpraisonaiagents/rag/context.pyto match this documented fallback behavior. - Or update this documentation to accurately reflect that only dictionary inputs with
metadatakeys are supported.
| # Note: Each retrieved item is a SearchResultItem object (see praisonaiagents.knowledge.models) | ||
| # that can be passed directly into build_context / deduplicate_chunks |
There was a problem hiding this comment.
This note indicates that SearchResultItem objects can be passed directly into build_context / deduplicate_chunks. As noted in other files, this is currently not supported by the implementation in praisonaiagents/rag/context.py and will result in an AttributeError.
Please update this comment to reflect the need for dictionary conversion (e.g., r.to_dict()) or update the context utilities to support objects.
Summary
Changes
Test Plan
Fixes #431
🤖 Generated with Claude Code