Repository navigation
Conversation
Expose previously hardcoded parameters through API endpoints, allowing clients to customize: Ingest parameters: - chunk_strategy (semantic/by_title) - document splitting strategy - chunk_size - maximum tokens per chunk - min_tokens - minimum chunk size for semantic splitting - rolling_window_size - semantic similarity window size - prefix_title/prefix_summary - include prefixes in chunks Query parameters: - top_k - number of results to retrieve (default: 5) - top_n - optional limit on final results - relevancy_score_threshold - filter by similarity score - query_transformation - advanced options for query processing Maintains backward compatibility with legacy field names through Pydantic aliases. Adds infrastructure for query transformation features (fusion, step-back, rewrite). Fixes superagent-ai#35
This branch has not been deployed
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
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.
Expose Configurable Parameters via API with Default Values
Summary
This pull request exposes previously hardcoded ingest and query parameters through the API endpoints, enabling clients to customize document processing and search behavior while maintaining sensible defaults. This implementation directly addresses issue #35 by making the RAG system more flexible and adaptable to different use cases.
Problem Statement
Previously, critical parameters like chunk size, splitting strategy, retrieval count, and filtering thresholds were hardcoded in the service layer, limiting the system's flexibility. Users had to modify source code to customize behavior, which reduced usability and created maintenance challenges.
Solution
All configurable parameters have been exposed through the API with comprehensive Pydantic models and backward-compatible field aliases. This allows clients to customize behavior at runtime while maintaining full backward compatibility with existing code.
Changes
1. Ingest Parameters (models/ingest.py)
Added flexible document processing configuration through
SplitterConfig:Primary Parameters
chunk_strategy(alias:name)Literal["semantic", "by_title"]"semantic"semantic: Uses semantic similarity to create meaningful, contextual chunksby_title: Groups content by document structure and titleschunk_size(alias:max_tokens)int400tokensmax_tokensfield nameSupporting Parameters
min_tokens: Minimum tokens for chunks (semantic method only, default: 30)rolling_window_size: Window size for semantic similarity comparison (semantic method only, default: 1)prefix_title: Include document titles in chunk prefixes (default: true)prefix_summary: Include document summaries in chunk prefixes (default: true)Backward Compatibility
This ensures existing code using
nameandmax_tokenscontinues to work without modification.2. Query Parameters (models/query.py)
Added comprehensive query customization through
RequestPayload:Retrieval Configuration
top_k: int (default: 5)top_n: Optional[int] (default: None)Filtering Options
relevancy_score_threshold: Optional[float] (default: None)Query Transformations
New
QueryTransformationConfigwith three advanced options:fusion: Splits a single query into multiple related searches, improving coveragestep_back: Retrieves broader context by asking a more general question firstrewrite: Rewrites queries to improve semantic matching with documents3. Service Layer Updates
service/embedding.py
chunk_strategyandchunk_sizechunk_strategyinstead ofnameservice/router.py
get_documents() function enhanced with:
top_kparameter from request payloadrelevancy_score_thresholdfiltering logictop_nresult limiting after re-rankingquery() function prepared for:
Implementation Details
Validation & Type Safety
All parameters use Pydantic BaseModel for:
Filtering Logic (service/router.py)
Query Transformation Hooks
Infrastructure is in place for future implementation:
API Usage Examples
Example 1: Standard Ingest with Defaults
{ "index_name": "my_docs", "vector_database": { "type": "qdrant", "url": "http://localhost:6333" }, "files": [ {"url": "https://example.com/document.pdf"} ] }Example 2: Custom Ingest Configuration
{ "index_name": "my_docs", "vector_database": {...}, "document_processor": { "encoder": { "provider": "openai", "model_name": "text-embedding-3-small" }, "splitter": { "chunk_strategy": "semantic", "chunk_size": 600, "min_tokens": 50, "rolling_window_size": 2, "prefix_title": true, "prefix_summary": true }, "unstructured": { "partition_strategy": "hi_res" } }, "files": [...] }Example 3: Standard Query with Defaults
{ "input": "What is machine learning?", "index_name": "my_docs", "vector_database": {...} }Example 4: Advanced Query with Filtering
{ "input": "Recent advances in AI", "index_name": "my_docs", "vector_database": {...}, "top_k": 20, "top_n": 5, "relevancy_score_threshold": 0.75, "query_transformation": { "rewrite": true, "fusion": true, "step_back": false } }Example 5: Strict Relevancy Requirements
{ "input": "Specific technical requirement", "index_name": "technical_docs", "vector_database": {...}, "top_k": 50, "top_n": 3, "relevancy_score_threshold": 0.85 }Files Changed
Testing Recommendations
Unit Tests
Integration Tests
Edge Cases
Backward Compatibility
✅ Fully Backward Compatible
name,max_tokens) still work via Pydantic aliasesMigration Path for Users
No migration required - existing code continues to work.
Users can optionally adopt new parameters:
Future Work
Short Term
Implement query transformation features:
Add comprehensive test suite
Generate OpenAPI documentation with parameter descriptions
Add parameter validation helpers
Medium Term
Long Term
Performance Impact
Security Considerations
✅ No Security Issues
Documentation
API Documentation
The Pydantic models automatically generate OpenAPI/Swagger documentation with:
Usage Documentation
Complete examples provided for:
Checklist
Related Issues
Fixes #35