Skip to content

giuseppe-trisciuoglio/developer-kit / plugins/developer-kit-java/skills/langchain4j-rag-implementation-patterns

langchain4j-rag-implementation-patterns

Verified

Provides Retrieval-Augmented Generation (RAG) implementation patterns with LangChain4j for Java. Generates document ingestion pipelines, embedding stores, vector search, and semantic search capabilities. Use when building chat-with-documents systems, document Q&A over PDFs or text files, AI assistants with knowledge bases, semantic search over document repositories, or knowledge-enhanced AI applications with source attribution.

FileKindSize
SKILL.mdskill md12.8 KB
references/examples.mdmarkdown16.5 KB
references/references.mdmarkdown12.1 KB

references/references.md

View on GitHub
# LangChain4j RAG Implementation - API References

Complete API reference for implementing RAG systems with LangChain4j.

## Document Loading

### Document Loaders

**FileSystemDocumentLoader**: Load from filesystem.
```java
import dev.langchain4j.data.document.loader.FileSystemDocumentLoader;
import java.nio.file.Path;

List<Document> documents = FileSystemDocumentLoader.load("documents");
List<Document> single = FileSystemDocumentLoader.load("document.pdf");
```

**ClassPathDocumentLoader**: Load from classpath resources.
```java
List<Document> resources = ClassPathDocumentLoader.load("documents");
```

**UrlDocumentLoader**: Load from web URLs.
```java
Document webDoc = UrlDocumentLoader.load("https://example.com/doc.html");
```

## Document Splitting

### DocumentSplitter Interface

```java
interface DocumentSplitter {
    List<TextSegment> split(Document document);
    List<TextSegment> splitAll(Collection<Document> documents);
}
```

### DocumentSplitters Factory

**Recursive Split**: Smart recursive splitting by paragraphs, sentences, words.
```java
DocumentSplitter splitter = DocumentSplitters.recursive(
    500,     // Max segment size (tokens or characters)
    50       // Overlap size
);

// With token counting
DocumentSplitter splitter = DocumentSplitters.recursive(
    500,
    50,
    new OpenAiTokenCountEstimator("gpt-4o-mini")
);
```

**Paragraph Split**: Split by paragraphs.
```java
DocumentSplitter splitter = DocumentSplitters.byParagraph(500, 50);
```

**Sentence Split**: Split by sentences.
```java
DocumentSplitter splitter = DocumentSplitters.bySentence(500, 50);
```

**Line Split**: Split by lines.
```java
DocumentSplitter splitter = DocumentSplitters.byLine(500, 50);
```

## Embedding Models

### EmbeddingModel Interface

```java
public interface EmbeddingModel {
    // Embed single text
    Response<Embedding> embed(String text);
    Response<Embedding> embed(TextSegment textSegment);
    
    // Batch embedding
    Response<List<Embedding>> embedAll(List<TextSegment> textSegments);
    
    // Model dimension
    int dimension();
}
```

### OpenAI Embedding Model

```java
EmbeddingModel model = OpenAiEmbeddingModel.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .modelName("text-embedding-3-small")  // or text-embedding-3-large
    .dimensions(512)                       // Optional: reduce dimensions
    .timeout(Duration.ofSeconds(30))
    .logRequests(true)
    .logResponses(true)
    .build();
```

### Other Embedding Models

```java
// Google Vertex AI
EmbeddingModel google = VertexAiEmbeddingModel.builder()
    .project("PROJECT_ID")
    .location("us-central1")
    .modelName("textembedding-gecko")
    .build();

// Ollama (local)
EmbeddingModel ollama = OllamaEmbeddingModel.builder()
    .baseUrl("http://localhost:11434")
    .modelName("all-minilm")
    .build();

// AllMiniLmL6V2 (offline)
EmbeddingModel offline = new AllMiniLmL6V2EmbeddingModel();
```

## Vector Stores (EmbeddingStore)

### EmbeddingStore Interface

```java
public interface EmbeddingStore<Embedded> {
    // Add embeddings
    String add(Embedding embedding);
    String add(String id, Embedding embedding);
    String add(Embedding embedding, Embedded embedded);
    List<String> addAll(List<Embedding> embeddings);
    List<String> addAll(List<Embedding> embeddings, List<Embedded> embeddeds);
    List<String> addAll(List<String> ids, List<Embedding> embeddings, List<Embedded> embeddeds);
    
    // Search embeddings
    EmbeddingSearchResult<Embedded> search(EmbeddingSearchRequest request);
    
    // Remove embeddings
    void remove(String id);
    void removeAll(Collection<String> ids);
    void removeAll(Filter filter);
    void removeAll();
}
```

### In-Memory Store

```java
EmbeddingStore<TextSegment> store = new InMemoryEmbeddingStore<>();

// Merge stores
InMemoryEmbeddingStore<TextSegment> merged = InMemoryEmbeddingStore.merge(
    store1, store2, store3
);
```

### Pinecone

```java
EmbeddingStore<TextSegment> store = PineconeEmbeddingStore.builder()
    .apiKey(System.getenv("PINECONE_API_KEY"))
    .index("my-index")
    .namespace("production")
    .environment("gcp-starter")  // or "aws-us-east-1"
    .build();
```

### Weaviate

```java
EmbeddingStore<TextSegment> store = WeaviateEmbeddingStore.builder()
    .host("localhost")
    .port(8080)
    .scheme("http")
    .collectionName("Documents")
    .build();
```

### Qdrant

```java
EmbeddingStore<TextSegment> store = QdrantEmbeddingStore.builder()
    .host("localhost")
    .port(6333)
    .collectionName("documents")
    .build();
```

### Chroma

```java
EmbeddingStore<TextSegment> store = ChromaEmbeddingStore.builder()
    .baseUrl("http://localhost:8000")
    .collectionName("my-collection")
    .build();
```

### Neo4j

```java
EmbeddingStore<TextSegment> store = Neo4jEmbeddingStore.builder()
    .withBasicAuth("bolt://localhost:7687", "neo4j", "password")
    .dimension(1536)
    .label("Document")
    .build();
```

### MongoDB Atlas

```java
EmbeddingStore<TextSegment> store = MongoDbEmbeddingStore.builder()
    .databaseName("search")
    .collectionName("documents")
    .indexName("vector_index")
    .createIndex(true)
    .fromClient(mongoClient)
    .build();
```

### PostgreSQL (pgvector)

```java
EmbeddingStore<TextSegment> store = PgVectorEmbeddingStore.builder()
    .host("localhost")
    .port(5432)
    .database("embeddings")
    .user("postgres")
    .password("password")
    .table("embeddings")
    .createTableIfNotExists(true)
    .build();
```

### Milvus

```java
EmbeddingStore<TextSegment> store = MilvusEmbeddingStore.builder()
    .host("localhost")
    .port(19530)
    .collectionName("documents")
    .dimension(1536)
    .build();
```

## Document Ingestion

### EmbeddingStoreIngestor

```java
public class EmbeddingStoreIngestor {
    public static Builder builder();
    
    public IngestionResult ingest(Document document);
    public IngestionResult ingest(Document... documents);
    public IngestionResult ingest(Collection<Document> documents);
}
```

### Building an Ingestor

```java
EmbeddingStoreIngestor ingestor = EmbeddingStoreIngestor.builder()
    
    // Document transformation
    .documentTransformer(doc -> {
        doc.metadata().put("source", "manual");
        return doc;
    })
    
    // Document splitting strategy
    .documentSplitter(DocumentSplitters.recursive(500, 50))
    
    // Text segment transformation
    .textSegmentTransformer(segment -> {
        String enhanced = "Category: Spring\n" + segment.text();
        return TextSegment.from(enhanced, segment.metadata());
    })
    
    // Embedding model (required)
    .embeddingModel(embeddingModel)
    
    // Embedding store (required)
    .embeddingStore(embeddingStore)
    
    .build();
```

### IngestionResult

```java
IngestionResult result = ingestor.ingest(documents);

// Access results
TokenUsage usage = result.tokenUsage();
long totalTokens = usage.totalTokenCount();
long inputTokens = usage.inputTokenCount();
```

## Content Retrieval

### EmbeddingSearchRequest

```java
EmbeddingSearchRequest request = EmbeddingSearchRequest.builder()
    .queryEmbedding(embedding)           // Required
    .maxResults(5)                       // Default: 3
    .minScore(0.7)                       // Threshold 0-1
    .filter(new IsEqualTo("category", "tutorial"))
    .build();
```

### EmbeddingSearchResult

```java
EmbeddingSearchResult<TextSegment> result = store.search(request);
List<EmbeddingMatch<TextSegment>> matches = result.matches();

for (EmbeddingMatch<TextSegment> match : matches) {
    double score = match.score();           // Relevance 0-1
    TextSegment segment = match.embedded(); // Retrieved content
    String id = match.embeddingId();        // Store ID
}
```

### ContentRetriever Interface

```java
public interface ContentRetriever {
    Content retrieve(Query query);
    List<Content> retrieveAll(List<Query> queries);
}
```

### EmbeddingStoreContentRetriever

```java
ContentRetriever retriever = EmbeddingStoreContentRetriever.builder()
    .embeddingStore(embeddingStore)
    .embeddingModel(embeddingModel)
    
    // Static configuration
    .maxResults(5)
    .minScore(0.7)
    
    // Dynamic configuration per query
    .dynamicMaxResults(query -> 10)
    .dynamicMinScore(query -> 0.8)
    .dynamicFilter(query -> 
        new IsEqualTo("userId", extractUserId(query))
    )
    
    .build();
```

## Advanced RAG

### RetrievalAugmentor

```java
public interface RetrievalAugmentor {
    AugmentationResult augment(UserMessage message);
    AugmentationResult augmentAll(List<UserMessage> messages);
}
```

### DefaultRetrievalAugmentor

```java
RetrievalAugmentor augmentor = DefaultRetrievalAugmentor.builder()
    
    // Query transformation
    .queryTransformer(new CompressingQueryTransformer(chatModel))
    
    // Content retrieval
    .contentRetriever(contentRetriever)
    
    // Content aggregation and re-ranking
    .contentAggregator(ReRankingContentAggregator.builder()
        .scoringModel(scoringModel)
        .minScore(0.8)
        .build())
    
    // Parallelization
    .executor(customExecutor)
    
    .build();
```

### Use with AI Services

```java
Assistant assistant = AiServices.builder(Assistant.class)
    .chatModel(chatModel)
    .retrievalAugmentor(augmentor)
    .build();
```

## Metadata and Filtering

### Metadata Object

```java
// Create from map
Metadata meta = Metadata.from(Map.of(
    "userId", "user123",
    "category", "tutorial",
    "score", 0.95
));

// Add entries
meta.put("status", "active");
meta.put("version", 2);

// Retrieve entries
String userId = meta.getString("userId");
int version = meta.getInt("version");
double score = meta.getDouble("score");

// Check existence
boolean has = meta.containsKey("userId");

// Remove entry
meta.remove("userId");

// Merge
Metadata other = Metadata.from(Map.of("source", "db"));
meta.merge(other);
```

### Filter Operations

```java
import dev.langchain4j.store.embedding.filter.comparison.*;
import dev.langchain4j.store.embedding.filter.logical.*;

// Equality
Filter filter = new IsEqualTo("status", "active");
Filter filter = new IsNotEqualTo("deprecated", "true");

// Comparison
Filter filter = new IsGreaterThan("score", 0.8);
Filter filter = new IsLessThanOrEqualTo("daysOld", 30);
Filter filter = new IsGreaterThanOrEqualTo("priority", 5);
Filter filter = new IsLessThan("errorRate", 0.01);

// Membership
Filter filter = new IsIn("category", Arrays.asList("tech", "guide"));
Filter filter = new IsNotIn("status", Arrays.asList("archived"));

// String operations
Filter filter = new ContainsString("content", "Spring");

// Logical operations
Filter filter = new And(
    new IsEqualTo("userId", "123"),
    new IsGreaterThan("score", 0.7)
);

Filter filter = new Or(
    new IsEqualTo("type", "doc"),
    new IsEqualTo("type", "guide")
);

Filter filter = new Not(new IsEqualTo("archived", "true"));
```

## TextSegment

### Creating TextSegments

```java
// Text only
TextSegment segment = TextSegment.from("This is the content");

// With metadata
Metadata metadata = Metadata.from(Map.of("source", "docs"));
TextSegment segment = TextSegment.from("Content", metadata);

// Accessing
String text = segment.text();
Metadata meta = segment.metadata();
```

## Best Practices

1. **Chunk Size**: Use 300-500 tokens per chunk for optimal balance
2. **Overlap**: Use 10-50 token overlap for semantic continuity
3. **Metadata**: Include source and timestamp for traceability
4. **Batch Processing**: Ingest documents in batches when possible
5. **Similarity Threshold**: Adjust minScore (0.7-0.85) based on precision/recall needs
6. **Vector DB Selection**: In-memory for dev/test, Pinecone/Qdrant for production
7. **Filtering**: Pre-filter by metadata to reduce search space
8. **Re-ranking**: Use scoring models for better relevance in production
9. **Monitoring**: Track retrieval quality metrics
10. **Testing**: Use small in-memory stores for unit tests

## Performance Tips

- Use recursive splitting for semantic coherence
- Enable batch processing for large datasets
- Use dynamic max results based on query complexity
- Cache embedding model for frequently accessed content
- Implement async ingestion for large document collections
- Monitor token usage for cost optimization
- Use appropriate vector DB indexes for scale
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall