# 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