Deprecate semantic guided retriever

[oussamahansal]

Summary

Moves semantic-guided retriever classes into a deprecated/ sub-package with deprecation warnings. Existing imports continue to work but emit DeprecationWarning.

Rationale

The semantic-guided search approach requires maintaining a dedicated statement vector index, which adds storage cost and indexing overhead. The traversal-based search achieves equivalent or better results using only the chunk index.

Migration Guide

Before (deprecated)	After (recommended)
from graphrag_toolkit.lexical_graph.retrieval.retrievers import SemanticGuidedRetriever	Use CompositeTraversalBasedRetriever
from graphrag_toolkit.lexical_graph.retrieval.retrievers import SemanticGuidedChunkRetriever	Use CompositeTraversalBasedRetriever
LexicalGraphQueryEngine.for_semantic_guided_search()	LexicalGraphQueryEngine.for_traversal_based_search()

What still works (backward compat)

• All existing imports resolve without error (via __getattr__ lazy loading)
• A DeprecationWarning is emitted on first use
• No code changes required for existing users until removal

Removal timeline

Targeted for removal in the next major version. Users should migrate before then.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[github-actions]

Lexical Graph Coverage Report: The coverage is at unknown% (target: unknown%). Download the HTML report here.

[github-actions]

Lexical Graph Coverage Report: The coverage is at 46.56% (target: 80%). Download the HTML report here.

[github-actions]

Lexical Graph Coverage Report: The coverage is at 46.56% (target: 80%). Download the HTML report here.

[github-actions]

Lexical Graph Coverage Report: The coverage is at unknown% (target: unknown%). Download the HTML report here.

[github-actions]

Lexical Graph Coverage Report: The coverage is at unknown% (target: unknown%). Download the HTML report here.

[github-actions]

Lexical Graph Coverage Report: The coverage is at 46.03% (target: 80%). Download the HTML report here.

[mykola-pereyma]

can you add a tests to check deprecation logic?
like tests/unit/retrieval/test_deprecated_imports.py

import pytest
import warnings

def test_deprecated_import_emits_warning():
    with warnings.catch_warnings(record=True) as w:
        warnings.simplefilter('always')
        from graphrag_toolkit.lexical_graph.retrieval.retrievers import SemanticGuidedRetriever
        assert len(w) == 1
        assert issubclass(w[0].category, DeprecationWarning)
        assert 'deprecated' in str(w[0].message).lower()

def test_unknown_attribute_raises():
    with pytest.raises(AttributeError):
        from graphrag_toolkit.lexical_graph.retrieval.retrievers import NonExistentClass

[github-actions]

Lexical Graph Coverage Report: The coverage is at 46.03% (target: 80%). Download the HTML report here.