Remove LlamaIndex as mandatory runtime dependency#322
Draft
mykola-pereyma wants to merge 8 commits into
Draft
Conversation
Introduce graphrag_toolkit.core as the foundation layer replacing LlamaIndex internal types: - Node, Document, NodeRef, NodeWithScore, QueryBundle (Pydantic models) - LLMProvider ABC + BedrockLLMProvider (boto3 converse API) - EmbeddingProvider ABC + BedrockEmbeddingProvider (boto3 invoke_model) - PromptTemplate, ChatPromptTemplate - Retriever, Extractor, Transform, PostProcessor, QueryEngine ABCs - Pipeline runner, CallbackRegistry - Compatibility aliases (TextNode=Node, BaseNode=Node) All new code with comprehensive unit tests. Part of: awslabs#299, awslabs#91
Replace LlamaIndex imports in storage/ and retrieval/ subsystems: - VectorStoreQuery, MetadataFilters → core.vector_store_types - TextNode, NodeWithScore, QueryBundle → core.types - Retriever, PostProcessor → core ABCs - QueryEngine → core.query_engine Mechanical import changes — no behavioral modification. Part of: awslabs#299, awslabs#91
Replace LlamaIndex imports in indexing/extract, indexing/build, and indexing/load: - TextNode, Document → core.types - Extractor, Transform → core ABCs - IngestionPipeline → core.pipeline - PromptTemplate → core.prompt - SentenceSplitter → core.text_splitter (custom implementation) Adds Anti-Corruption Layer (indexing/compat/llama_index_adapter.py) to normalize LlamaIndex nodes at the IdRewriter boundary. Part of: awslabs#299, awslabs#91
Replace LlamaIndex imports in top-level files and test suite: - config.py: LLMType/EmbeddingType use core providers - lexical_graph_index.py: custom SentenceSplitter as default chunker - lexical_graph_query_engine.py: core Response/QueryBundle types - LLMCache: wraps BedrockLLMProvider - Test fixtures: use core.types instead of llama_index.core.schema - requirements.txt: add tiktoken, remove LlamaIndex from mandatory deps Part of: awslabs#299, awslabs#91
…ct.toml - Node, NodeRef, Document, NodeWithScore, QueryBundle → Pydantic BaseModel - model_validator for backward-compat node_id→id_ mapping - NodeWithScore.score is Optional[float] - pyproject.toml: LlamaIndex moved to optional extras ([readers], [chunking], [opensearch], [llms]) Part of: awslabs#299, awslabs#91
- SentenceSplitter: token-based chunking using tiktoken cl100k_base, produces chunk-for-chunk identical output to LlamaIndex (verified) - TokenTextSplitter: fixed token-count chunks with overlap - run_async(): safely handles Jupyter/existing event loops via ThreadPoolExecutor fallback These eliminate llama-index-core as a runtime dependency for the default chunking and async paths. Part of: awslabs#299, awslabs#91
Address critical review findings: - BedrockLLMProvider: add .model property, _get_all_kwargs() returns snake_case keys with defaults (max_tokens=4096, temperature=0.0) - BedrockEmbeddingProvider: add retry config (adaptive, 10 retries, 60s) - CallbackRegistry: list snapshot in emit() for thread safety - Extractor: use run_async() instead of bare asyncio.run() Part of: awslabs#299, awslabs#91
The node_strategy can generate property dicts containing 'id' as a key,
which overwrites the actual node ID when spread into parameters via
**node['properties']. Filter out reserved keys ('id', 'node_id', 'label')
from the property key strategy to prevent false-negative test failures.
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.
Remove LlamaIndex as Mandatory Runtime Dependency
Motivation
LlamaIndex as a mandatory dependency creates two blocking issues for production deployments:
aiobotocore pin conflict (Dependency conflict: aiobotocore pins botocore to narrow ranges incompatible with bedrock-agentcore #299): LlamaIndex transitive dependency tree pins aiobotocore to a version range incompatible with bedrock-agentcore, making it impossible to use graphrag-toolkit in Bedrock Agent environments.
Deployment footprint (Retrieval requires very large dependencies #91): llama-index-core pulls ~700MB of transitive dependencies, pushing deployments beyond Lambda 250MB limit and adding cold-start latency to EKS containers.
Approach
Introduce a lean
core/module providing the exact interfaces the toolkit needs, implemented directly against boto3:LlamaIndex becomes optional via extras (
[readers],[chunking],[opensearch]).Key Design Decisions
Challenges Addressed
.modelproperty, snake_case kwargs, anthropic message format conversion)run_async()with ThreadPoolExecutor fallback)__getstate__/__setstate__for boto3 clients)Test Results
Integration tests are UNMODIFIED from main branch — proving full behavioral compatibility across all pipeline phases including batch inference and versioning.
Deployment Footprint
For agentic deployments: eliminates aiobotocore conflict, ~150MB smaller, ~50 fewer transitive packages, faster cold start.
Not Covered (Future Work)
[readers]extra[chunking]extra is deprecatedCommits
Resolves #299, #91