Skip to content
Raindrop Developer Hub

LangChain Integration

Overview

Raindrop provides LangChain integrations for Python and TypeScript that enable you to use SmartBuckets as retrievers in your LangChain applications. The retrievers perform semantic search (chunk_search) across documents stored in your SmartBuckets and return results as LangChain Document objects.

Installation

For Python applications, install the integration package using pip. The package requires Python 3.8 or higher and includes all necessary dependencies for LangChain compatibility:

Terminal window
pip install lm-raindrop-integrations

The Python package includes optional dependencies for LangChain. If you haven’t already installed LangChain in your project, the package will automatically include the required LangChain core components. For production applications, you may want to explicitly install LangChain with your preferred version:

Terminal window
pip install lm-raindrop-integrations langchain

API Key Configuration

Both implementations support multiple methods for providing your LiquidMetal API key. The most secure approach is to use environment variables, which keeps sensitive credentials out of your source code. Set the RAINDROP_API_KEY environment variable with your API key:

Terminal window
export RAINDROP_API_KEY="your-api-key-here"

Alternatively, you can provide the API key directly when initializing the retriever, though this approach should be used carefully in production environments. You can obtain an API key by signing up at raindrop.run and following the onboarding process to create your first SmartBucket.

Basic Usage

The fundamental usage pattern for both Python and TypeScript implementations follows the same conceptual approach: initialize a retriever with your bucket name and API key, then use the invoke method to perform searches. The retrievers handle all the complexity of API communication and result formatting behind the scenes.

Here’s a complete example showing how to use the Python retriever in a typical application:

from lm_raindrop_integrations import LangchainSmartBucketRetriever
import os


# Initialize the retriever with environment variable for API key
retriever = LangchainSmartBucketRetriever(
    bucket_name="my-knowledge-base"  # API key read from RAINDROP_API_KEY env var
)


# Or provide API key explicitly
retriever = LangchainSmartBucketRetriever(
    api_key="your-api-key",
    bucket_name="my-knowledge-base"
)


# Perform a semantic search
results = retriever.invoke("What are the best practices for machine learning?")


# Process and display results
for i, doc in enumerate(results, 1):
    print(f"Result {i}:")
    print(f"Content: {doc.page_content[:200]}...")
    print(f"Relevance Score: {doc.metadata['score']:.3f}")
    print(f"Source: {doc.metadata['source']['object_name']}")
    print(f"Chunk ID: {doc.metadata['chunk_signature']}")
    print("-" * 50)

Both implementations return results in the same conceptual format, though they follow language-specific conventions for property naming. The Python version uses snake_case following Python conventions, while the TypeScript version uses camelCase following JavaScript conventions.

Response Format

Returns a list of Document objects:

# Example response structure
[
    Document(
        page_content="Machine learning is a subset of artificial intelligence that enables systems to learn and improve from experience without being explicitly programmed. It involves algorithms that can identify patterns in data and make predictions or decisions based on those patterns.",
        metadata={
            'chunk_signature': 'sha256:abc123def456...',
            'payload_signature': 'sha256:789xyz012...',
            'score': 0.89,
            'type': 'text/plain',
            'source': {
                'object_name': 'ml_fundamentals.pdf',
                'bucket_name': 'ai_knowledge_base',
                'application_name': 'documentation_system',
                'module_id': 'docs_module_v1',
                'application_version_id': '01JBQX9K7M3P2N4R5S6T7V8W9X',
                'source_raw': { /* full source object */ }
            }
        }
    ),
    Document(
        page_content="Deep learning represents a specialized subset of machine learning that uses artificial neural networks with multiple layers to model and understand complex patterns in data.",
        metadata={
            'chunk_signature': 'sha256:def789ghi012...',
            'payload_signature': 'sha256:345abc678...',
            'score': 0.76,
            'type': 'text/plain',
            'source': {
                'object_name': 'neural_networks_guide.pdf',
                'bucket_name': 'ai_knowledge_base',
                'application_name': 'documentation_system',
                'module_id': 'docs_module_v1',
                'application_version_id': '01JBQX9K7M3P2N4R5S6T7V8W9X',
                'source_raw': { /* full source object */ }
            }
        }
    )
]

Metadata Fields

  • chunk_signature / chunkSignature: Hash identifying the text chunk
  • score: Relevance score (0-1, higher = more relevant)
  • source: Document source information including bucket and application metadata
  • payload_signature / payloadSignature: Hash identifying the original payload
  • type: Content type of the source document