Introduce Valkey Vector Store for LangChain AWS

[Jonathan-Improving]

AI Disclaimer

This implementation was developed with assistance from AI coding agents (Claude/Kiro) for code generation, testing patterns, and documentation. All code has been manually reviewed and tested.

Why This Solution

Valkey GLIDE provides the official AWS-recommended client with better performance than the Redis fork. The synchronous API (valkey-glide-sync) was chosen to match LangChain's synchronous VectorStore interface, ensuring seamless integration without async complexity.

Key decisions:

• GLIDE over Redis fork: Better AWS support, active development
• Sync over Async: Matches LangChain patterns, simpler implementation
• Module-level functions: Follows GLIDE's API design (ft.search(client, ...))
• Optional dependency: Keeps base package lightweight

Areas for Careful Review

1. Exception handling in utilities/valkey.py - cluster fallback logic
2. Filter expression generation in filters.py - operator precedence
3. Vector search query construction in base.py - KNN query format
4. Type hints - Union types for GlideClient/GlideClusterClient
5. Integration tests - require real Valkey instance with FT module

[MatthiasHowellYopp]

Minor questions - basically looks good.

[jbrinkman]

You need to move this out of draft so we can do proper code reviews on it.

[jbrinkman]

Code Review: Valkey Vector Store Integration

Thanks for this contribution! I've reviewed the PR against the AGENTS.md guidelines and general code quality standards. The implementation is solid overall, but there are several critical issues that need to be addressed before this can be merged.

Critical Issues (Must Fix)

1. ⚠️ PR Description Missing Required Details

Severity: BLOCKING

The current PR description does not meet AGENTS.md requirements. According to the pull request guidelines, the description must include:

• AI Disclaimer: "Always add a disclaimer to the PR description mentioning how AI agents are involved with the contribution"
• The "Why": "Describe the 'why' of the changes, why the proposed solution is the right one. Limit prose."
• Areas for Careful Review: "Highlight areas of the proposed changes that require careful review"

Current PR body:

This is a draft PR, set for merging into another temporary branch (for now) for the 
primary purpose of collecting initial feedback from internal BitQuill developers 
before promoting it to the LangChain team.

Please update the PR description to address these three requirements from AGENTS.md.

2. Remove libs/aws/Pipfile

Severity: BLOCKING

This file conflicts with the project's uv tooling. Per AGENTS.md: "This monorepo uses uv for dependency management."

Action: Delete libs/aws/Pipfile

3. Relocate libs/aws/langchain_aws/vectorstores/valkey/SUMMARY.md

Severity: BLOCKING

This 325-line implementation notes document should not be in the source tree. It appears to be development/design documentation.

Options:

• Move to docs/ if it's user-facing documentation
• Move to project root or a notes/ directory if internal
• Remove entirely if temporary development notes

4. Bare Exception Handling in utilities/valkey.py

Severity: HIGH
Lines: 50-58

Per AGENTS.md security guidelines: "Proper exception handling (no bare except:) and use a msg variable for error messages"

Current:

try:
    config = GlideClusterClientConfiguration(addresses=addresses, **kwargs)
    client = GlideClusterClient.create(config)
    return client
except Exception:  # ❌ Too broad
    # Fall back to standalone
    ...

Recommended:

try:
    config = GlideClusterClientConfiguration(addresses=addresses, **kwargs)
    return GlideClusterClient.create(config)
except (ConnectionError, TimeoutError, ValueError) as e:
    logger.debug(f"Cluster connection failed, falling back to standalone: {e}")
    config = GlideClientConfiguration(addresses=addresses, **kwargs)
    return GlideClient.create(config)

5. Workaround Code in Ollama Example (Line 93)

File: libs/aws/examples/valkey_vectorstore_ollama_example.py

vectorstore.similarity_search_with_score_by_vector = \
    vectorstore.similarity_search_with_score_by_vector.__get__(vectorstore, ValkeyVectorStore)

This method rebinding is a red flag that suggests a deeper issue with the implementation. This needs investigation and proper fix rather than a workaround in example code.

Code Quality Issues (Should Fix)

6. Missing Raises: Sections in Docstrings

Per AGENTS.md documentation standards, docstrings should document exceptions. Several functions in base.py and utilities/valkey.py raise exceptions but don't document them.

7. Error Messages Should Reference langchain-aws[valkey]

Installation error messages should reference the optional dependency group:

raise ImportError(
    "Could not import valkey-glide-sync python package. "
    "Please install it with `pip install langchain-aws[valkey]`."
)

8. Multiple # type: ignore Comments

Several type ignore comments suggest type definitions could be improved. Consider adding proper type stubs or refining type hints.

9. Unused Code: schema.py (256 lines)

The schema.py file contains extensive class definitions (ValkeyModel, FlatVectorField, HNSWVectorField, etc.) but these classes are never imported or used anywhere in the codebase. Either integrate this schema system or remove it.

Strengths ✅

• Excellent documentation (README.md) with clear examples
• Comprehensive test coverage (39 unit tests + 14 integration tests)
• Full type hints throughout the implementation
• Follows existing LangChain vectorstore patterns
• Good separation of concerns with filter system
• Clean integration with AWS services

Recommendations Summary

Must Fix (Blocking):

1. Update PR description with all AGENTS.md requirements
2. Remove libs/aws/Pipfile
3. Relocate or remove SUMMARY.md from source tree
4. Fix bare exception handling in utilities/valkey.py
5. Investigate and fix method rebinding workaround in Ollama example

Should Fix (Non-blocking):
6. Add Raises: sections to docstrings
7. Update error messages to reference langchain-aws[valkey]
8. Review and reduce # type: ignore comments
9. Remove unused schema.py or integrate it

Once these critical issues are addressed, this will be ready for merge. The core implementation is solid and well-tested!

[MatthiasHowellYopp]

just one minor comment

[Jonathan-Improving]

PR moved to LangChain Repo, see here.