debezium/dbz#2074 feat: add core retrieval layer and LangGraph node s…

[KMohnishM]

…upport

Description

This Pull Request implements the core retrieval integration layer for PyDebeziumAI (Week 4, PR 1).

With the core ingestion, transformation, and sync managers in place, this PR provides the consuming interface to expose the live-updating vector stores directly to LangChain QA chains and LangGraph agents.
Resolves: debezium/dbz#2074

Key Changes

1. Retrieval Package (pydebeziumai.retrieval):

   • Implemented create_retriever_tool: Wraps a VectorStoreAdapter into a LangChain Tool. Automatically uses LangChain's native create_retriever_tool if the langchain package is installed, and seamlessly falls back to a custom BaseTool implementation if only langchain-core is available.
   • Implemented create_retriever_node: Generates a LangGraph-compatible state graph node. Supports extracting query strings from state["query"], state["messages"] (auto-extracting the last message's content), Pydantic object attributes, or via a custom user-defined extractor callback.

2. Unit Test Suite (tests/unit/test_retrieval.py):

   • Validates correct creation and execution of the retriever tools under different setups.
   • Tests create_retriever_node query extraction patterns across dictionaries, message lists, object states, and custom extractor callables.
   • Assures proper type validation (raising ValueError when non-string queries are extracted).

Verification Results

All quality, formatting, and typing checks have been executed successfully inside WSL:

• Ruff check & formatting: Passed (All checks passed!)
• MyPy strict type-checking: Passed (Success: no issues found in 21 source files)
• PyTest suite: All 68 tests (including the 6 new unit tests) passed successfully: