-
Notifications
You must be signed in to change notification settings - Fork 81
chore(docs): Add an Async Explainer doc #200
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from 4 commits
Commits
Show all changes
9 commits
Select commit
Hold shift + click to select a range
57fd9cf
chore(docs): Add an Async Explainer doc
dishaprakash 4303462
update class names
dishaprakash 4caff7a
update class names
dishaprakash 3ee1262
heading change
dishaprakash c0a8ccd
Update Async explainer after review
dishaprakash 2485657
Merge branch 'main' into dishaprakash-patch-1
dishaprakash 99fb685
Rename Async explainer.md to v2_design_overview.md
dishaprakash c715faf
Rename v2_design_overview.md to docs/v2_design_overview.md
dishaprakash c0f496c
Merge branch 'main' into dishaprakash-patch-1
averikitsch File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,38 @@ | ||
# Design Rationale: Mixed Interface PGVectorStore | ||
|
||
This document outlines the design choices behind the PGVectorStore integration for LangChain, focusing on its dual interface that supports both synchronous and asynchronous usage patterns. | ||
dishaprakash marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
## Motivation: Performance through Asynchronicity | ||
|
||
Database interactions are often I/O-bound, making asynchronous programming crucial for performance. | ||
|
||
- **Non-Blocking Operations:** Asynchronous code prevents the application from stalling while waiting for database responses, improving throughput and responsiveness. | ||
dishaprakash marked this conversation as resolved.
Show resolved
Hide resolved
|
||
- **Asynchronous Foundation (`asyncio` and Drivers):** Built upon Python's `asyncio`, the integration is designed to work with asynchronous PostgreSQL drivers to handle database operations efficiently. While compatible drivers are supported, the `asyncpg` driver is specifically recommended due to its high performance in concurrent scenarios. You can explore its benefits ([link](https://magic.io/blog/asyncpg-1m-rows-from-postgres-to-python/)) and performance benchmarks ([link](https://fernandoarteaga.dev/blog/psycopg-vs-asyncpg/)) for more details. | ||
dishaprakash marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
This foundation ensures the core database interactions are fast and scalable. | ||
dishaprakash marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
## The Two-Class Approach: Enabling a Mixed Interface | ||
|
||
To cater to different application architectures while maintaining performance, we provide two classes: | ||
|
||
1. **`AsyncPGVectorStore` (Core Asynchronous Implementation):** | ||
* This class contains the pure `async/await` logic for all database operations using `asyncpg`. | ||
dishaprakash marked this conversation as resolved.
Show resolved
Hide resolved
|
||
* It's designed for **direct use within asynchronous applications**. Users working in an `asyncio` environment can `await` its methods for maximum efficiency and direct control within the event loop. | ||
* It represents the fundamental, non-blocking way of interacting with the database. | ||
|
||
2. **`PGVectorStore` (Synchronous Interface / Asynchronous Internals):** | ||
dishaprakash marked this conversation as resolved.
Show resolved
Hide resolved
|
||
* This class provides both asynchronous & synchronous APIs. | ||
* When one of its methods is called, it internally invokes the corresponding `async` method from `AsyncPGVectorStore`. | ||
* It **manages the execution of this underlying asynchronous logic**, handling the necessary `asyncio` event loop interactions (e.g., starting/running the coroutine) behind the scenes. | ||
* This allows users of synchronous codebases to leverage the performance benefits of the asynchronous core without needing to rewrite their application structure. | ||
|
||
## Benefits of this Dual Interface Design | ||
|
||
This two-class structure provides significant advantages: | ||
|
||
- **Interface Flexibility:** Developers can **choose the interface that best fits their needs**: | ||
* Use `PGVectorStore` for easy integration into existing synchronous applications. | ||
* Use `AsyncPGVectorStore` for optimal performance and integration within `asyncio`-based applications. | ||
- **Ease of Use:** `PGVectorStore` offers a familiar synchronous programming model, hiding the complexity of managing async execution from the end-user. | ||
- **Robustness:** The clear separation helps prevent common errors associated with mixing synchronous and asynchronous code incorrectly, such as blocking the event loop from synchronous calls within an async context. | ||
- **Efficiency for Async Users:** `AsyncPGVectorStore` provides a direct path for async applications, avoiding any potential overhead from the sync-to-async bridging layer present in `PGVectorStore`. |
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.
Uh oh!
There was an error while loading. Please reload this page.