feat(messagehistory): implement SemanticMessageHistory with vector search

Adds SemanticMessageHistory class for storing and retrieving LLM conversation
history with vector embeddings for semantic search. This matches the Python
redis-vl-python SemanticMessageHistory implementation.

New classes:
- SemanticMessageHistory: Main class with getRelevant() for semantic search
- SemanticMessageHistorySchema: Schema with vector field for embeddings
- SemanticChatMessage: Message model with vector field support

Features:
- Automatic message embedding using configurable vectorizer
- getRelevant(prompt) for semantic similarity search on history
- Configurable distance threshold for search precision
- Role filtering (user, llm, system, tool) in semantic search
- Fallback to recent messages when no semantic matches
- Session tagging for multi-conversation support

Tests:
- 22 unit tests for SemanticMessageHistory
- 15 integration tests with Redis Stack

Documentation:
- Updated message-history.adoc with full SemanticMessageHistory examples
- Updated FEATURE_PARITY_REPORT.md to reflect ~95% parity

Author: bsbodden

FEATURE_PARITY_REPORT.md

@@ -0,0 +1,334 @@
+# RedisVL4J vs Python redis-vl-python Feature Parity Report
+
+**Generated:** 2024-12-10
+**Python Version Reference:** redis-vl-python (latest main branch)
+**Java Version Reference:** RedisVL4J (current main branch)
+
+---
+
+## Executive Summary
+
+RedisVL4J has achieved **~95% feature parity** with the Python redis-vl-python library. The core functionality (schema, index, queries, vectorizers, rerankers, caching, routing, SVS-VAMANA, semantic message history) is complete. The main gaps are in:
+
+1. **Vectorizer integrations** - Missing several cloud provider integrations (use LangChain4J as workaround)
+2. **CLI Tools** - No command-line interface
+3. **Async Support** - No async variants (Java uses different concurrency models)
+4. **Compression utilities** - Missing CompressionAdvisor helper (low priority)
+
+---
+
+## Detailed Feature Comparison
+
+### Legend
+- ✅ Fully Implemented
+- ⚠️ Partially Implemented
+- ❌ Not Implemented
+- N/A Not Applicable (platform-specific)
+
+---
+
+## 1. SCHEMA AND INDEX MANAGEMENT
+
+| Feature | Python | Java | Notes |
+|---------|--------|------|-------|
+| **IndexSchema** | ✅ | ✅ | Full parity |
+| **StorageType (HASH/JSON)** | ✅ | ✅ | Full parity |
+| **Multiple prefixes** | ✅ | ✅ | Full parity |
+| **Stopwords configuration** | ✅ | ✅ | Full parity |
+| **YAML/JSON schema loading** | ✅ | ✅ | Full parity |
+| **Schema validation** | ✅ | ✅ | Full parity |
+| **IndexInfo** | ✅ | ⚠️ | Basic info available |
+
+### Field Types
+
+| Field Type | Python | Java | Notes |
+|------------|--------|------|-------|
+| **TextField** | ✅ | ✅ | Full parity |
+| **TagField** | ✅ | ✅ | Full parity |
+| **NumericField** | ✅ | ✅ | Full parity |
+| **GeoField** | ✅ | ✅ | Full parity |
+| **FlatVectorField** | ✅ | ✅ | Full parity |
+| **HNSWVectorField** | ✅ | ✅ | Full parity |
+| **SVSVectorField** | ✅ | ✅ | Full parity (commit 379fa2b) |
+
+### Vector Field Attributes
+
+| Attribute | Python | Java | Notes |
+|-----------|--------|------|-------|
+| dims | ✅ | ✅ | |
+| distance_metric (COSINE, L2, IP) | ✅ | ✅ | |
+| datatype (float16, float32, float64) | ✅ | ✅ | |
+| datatype (bfloat16, int8, uint8) | ✅ | ✅ | Full parity (commit 379fa2b) |
+| HNSW: m, ef_construction, ef_runtime | ✅ | ✅ | |
+| HNSW: epsilon | ✅ | ✅ | Added in PR #439 |
+| SVS-VAMANA: compression types | ✅ | ✅ | LVQ4, LVQ4x4, LVQ4x8, LVQ8, LeanVec4x8, LeanVec8x8 |
+| SVS-VAMANA: graph parameters | ✅ | ✅ | graphMaxDegree, constructionWindowSize, searchWindowSize, etc. |
+
+---
+
+## 2. SEARCH INDEX OPERATIONS
+
+| Feature | Python | Java | Notes |
+|---------|--------|------|-------|
+| **SearchIndex** | ✅ | ✅ | Full parity |
+| **AsyncSearchIndex** | ✅ | N/A | Java uses different async patterns |
+| create() / drop() / exists() | ✅ | ✅ | |
+| addDocument() / updateDocument() | ✅ | ✅ | |
+| deleteDocument() | ✅ | ✅ | |
+| load() (batch loading) | ✅ | ✅ | |
+| fetch() | ✅ | ✅ | |
+| clear() | ✅ | ✅ | |
+| getInfo() / getDocumentCount() | ✅ | ✅ | |
+| search() / query() | ✅ | ✅ | |
+| paginate() | ✅ | ✅ | |
+| batchSearch() / batchQuery() | ✅ | ✅ | |
+| expireKeys() | ✅ | ✅ | |
+| from_existing() | ✅ | ✅ | |
+| listall() | ✅ | ✅ | |
+
+---
+
+## 3. QUERY TYPES
+
+| Query Type | Python | Java | Notes |
+|------------|--------|------|-------|
+| **VectorQuery** | ✅ | ✅ | Full parity |
+| **VectorRangeQuery / RangeQuery** | ✅ | ✅ | Full parity |
+| **FilterQuery** | ✅ | ✅ | Full parity |
+| **TextQuery** | ✅ | ✅ | Full parity |
+| **CountQuery** | ✅ | ✅ | Full parity |
+| **HybridQuery** | ✅ | ✅ | Full parity |
+| **AggregationQuery** | ✅ | ✅ | Full parity |
+| **MultiVectorQuery** | ✅ | ✅ | Full parity |
+
+### Query Features
+
+| Feature | Python | Java | Notes |
+|---------|--------|------|-------|
+| Pre-filtering | ✅ | ✅ | |
+| Runtime params (efRuntime) | ✅ | ✅ | PR #439 |
+| Runtime params (epsilon) | ✅ | ✅ | PR #439 |
+| SVS-VAMANA runtime params | ✅ | ✅ | PR #439 (searchWindowSize, etc.) |
+| Return fields | ✅ | ✅ | |
+| Skip decode fields | ✅ | ✅ | |
+| Sorting (single/multi-field) | ✅ | ✅ | |
+| Hybrid alpha parameter | ✅ | ✅ | |
+| Distance normalization | ✅ | ✅ | |
+
+### Filter Types
+
+| Filter | Python | Java | Notes |
+|--------|--------|------|-------|
+| Tag filter | ✅ | ✅ | |
+| Text filter | ✅ | ✅ | |
+| Numeric filter (>, <, ==, >=, <=) | ✅ | ✅ | |
+| Geo filter (radius, box) | ✅ | ✅ | |
+| Wildcard | ✅ | ✅ | |
+| Prefix | ✅ | ✅ | |
+| Fuzzy | ✅ | ✅ | |
+| AND / OR / NOT combinators | ✅ | ✅ | |
+
+---
+
+## 4. VECTORIZER INTEGRATIONS
+
+| Vectorizer | Python | Java | Notes |
+|------------|--------|------|-------|
+| **BaseVectorizer** | ✅ | ✅ | |
+| **HFTextVectorizer** (HuggingFace) | ✅ | ⚠️ | Java has SentenceTransformersVectorizer |
+| **OpenAITextVectorizer** | ✅ | ❌ | **GAP** |
+| **AzureOpenAITextVectorizer** | ✅ | ❌ | **GAP** |
+| **CohereTextVectorizer** | ✅ | ❌ | **GAP** |
+| **MistralAITextVectorizer** | ✅ | ❌ | **GAP** |
+| **VertexAITextVectorizer** | ✅ | ❌ | **GAP** |
+| **BedrockTextVectorizer** | ✅ | ❌ | **GAP** |
+| **VoyageAITextVectorizer** | ✅ | ❌ | **GAP** |
+| **CustomTextVectorizer** | ✅ | ✅ | Via BaseVectorizer extension |
+| **LangChain4JVectorizer** | N/A | ✅ | Java-specific integration |
+| **SentenceTransformersVectorizer** | ✅ (via HF) | ✅ | ONNX-based local models |
+| **MockVectorizer** | ✅ | ✅ | For testing |
+| **vectorizer_from_dict()** | ✅ | ❌ | **GAP: Factory function** |
+| **EmbeddingsCache integration** | ✅ | ✅ | |
+
+---
+
+## 5. RERANKER IMPLEMENTATIONS
+
+| Reranker | Python | Java | Notes |
+|----------|--------|------|-------|
+| **BaseReranker** | ✅ | ✅ | Full parity |
+| **CohereReranker** | ✅ | ✅ | Full parity |
+| **HFCrossEncoderReranker** | ✅ | ✅ | Full parity |
+| **VoyageAIReranker** | ✅ | ✅ | Full parity |
+
+---
+
+## 6. LLM CACHE IMPLEMENTATIONS
+
+| Feature | Python | Java | Notes |
+|---------|--------|------|-------|
+| **BaseCache** | ✅ | ✅ | |
+| **SemanticCache** | ✅ | ✅ | Full parity |
+| **LangCacheSemanticCache** | ✅ | ✅ | Full parity (PR #442) |
+| URL percent-encoding | ✅ | ✅ | PR #442 |
+| Per-entry TTL | ✅ | ✅ | PR #442 |
+| **EmbeddingsCache** | ✅ | ✅ | Full parity |
+| CacheEntry / CacheHit models | ✅ | ⚠️ | Basic support |
+| SemanticCacheIndexSchema | ✅ | ⚠️ | Auto-generated |
+| Async cache operations | ✅ | N/A | |
+
+---
+
+## 7. MESSAGE HISTORY / SESSION MANAGEMENT
+
+| Feature | Python | Java | Notes |
+|---------|--------|------|-------|
+| **BaseMessageHistory** | ✅ | ✅ | |
+| **MessageHistory** (Standard) | ✅ | ✅ | Full parity |
+| **SemanticMessageHistory** | ✅ | ✅ | Full parity - `getRelevant()` semantic search |
+| Session tagging | ✅ | ✅ | |
+| Role filtering (user, llm, system, tool) | ✅ | ✅ | |
+| TTL management | ✅ | ✅ | |
+| Tool call storage | ✅ | ✅ | |
+| Metadata storage | ✅ | ✅ | |
+| get_recent() | ✅ | ✅ | |
+| get_relevant() (semantic search) | ✅ | ❌ | **GAP** |
+| Deprecated SessionManager aliases | ✅ | N/A | Not needed in Java |
+
+---
+
+## 8. SEMANTIC ROUTER
+
+| Feature | Python | Java | Notes |
+|---------|--------|------|-------|
+| **SemanticRouter** | ✅ | ✅ | Full parity |
+| **Route** | ✅ | ✅ | Full parity |
+| **RoutingConfig** | ✅ | ✅ | Full parity |
+| **RouteMatch** | ✅ | ✅ | Full parity |
+| Distance aggregation methods | ✅ | ✅ | |
+| Vectorizer integration | ✅ | ✅ | |
+| Auto-schema generation | ✅ | ✅ | |
+
+---
+
+## 9. LANGCHAIN4J INTEGRATIONS (Java-Specific)
+
+| Feature | Python | Java | Notes |
+|---------|--------|------|-------|
+| **EmbeddingStore** | N/A | ✅ | Java-specific |
+| **ContentRetriever** | N/A | ✅ | Java-specific |
+| **DocumentStore** | N/A | ✅ | Java-specific |
+| **ChatMemoryStore** | N/A | ✅ | Java-specific |
+| **FilterMapper** | N/A | ✅ | Java-specific |
+
+---
+
+## 10. CLI TOOLS
+
+| Feature | Python | Java | Notes |
+|---------|--------|------|-------|
+| **rvl CLI** | ✅ | ❌ | **GAP: No CLI** |
+| rvl index create | ✅ | ❌ | |
+| rvl index delete | ✅ | ❌ | |
+| rvl index info | ✅ | ❌ | |
+| rvl stats | ✅ | ❌ | |
+| rvl version | ✅ | ❌ | |
+
+---
+
+## 11. UTILITIES
+
+| Utility | Python | Java | Notes |
+|---------|--------|------|-------|
+| **TokenEscaper** | ✅ | ✅ | Full parity |
+| **Distance calculations** | ✅ | ✅ | |
+| **Vector normalization** | ✅ | ✅ | |
+| **Logging utilities** | ✅ | ✅ | Via SLF4J |
+| **CompressionAdvisor** | ✅ | ❌ | **GAP: SVS compression helper** |
+| **SVSConfig** | ✅ | ❌ | **GAP: SVS configuration model** |
+
+---
+
+## 12. CONNECTION MANAGEMENT
+
+| Feature | Python | Java | Notes |
+|---------|--------|------|-------|
+| Basic Redis connection | ✅ | ✅ | |
+| Connection pooling | ✅ | ✅ | |
+| SSL/TLS | ✅ | ✅ | |
+| Sentinel support | ✅ | ✅ | |
+| Cluster support | ✅ | ✅ | |
+| URL-based configuration | ✅ | ✅ | |
+| Async connections | ✅ | N/A | |
+
+---
+
+## Summary of Gaps
+
+### Medium Priority (Extended Functionality)
+
+1. **Cloud Vectorizer Integrations**
+   - Missing: OpenAI, Azure OpenAI, Cohere, Mistral, Vertex AI, Bedrock, Voyage AI
+   - Workaround: Use LangChain4J embeddings which support most of these
+
+2. **CompressionAdvisor Utility**
+   - Python: Helper to recommend SVS compression settings based on dimensions/priorities
+   - Java: Not implemented (SVS-VAMANA core functionality IS implemented)
+
+### Low Priority (Nice-to-Have)
+
+3. **CLI Tools**
+   - Python: `rvl` command-line interface
+   - Java: Not implemented - lower priority for Java library consumers
+
+4. **vectorizer_from_dict() Factory**
+   - Python: Factory function to create vectorizers from config
+   - Java: Builder pattern serves similar purpose
+
+### Completed (Previously Gap)
+
+5. **SemanticMessageHistory** - ✅ NOW IMPLEMENTED
+   - Python: `get_relevant(prompt)` searches messages semantically using vector similarity
+   - Java: `SemanticMessageHistory` class with `getRelevant()` method - full parity
+
+---
+
+## Recommendations
+
+### For 0.1.0 Release (Current)
+
+The current feature set is sufficient for a production-ready 0.1.0 release:
+- Core schema/index/query functionality ✅
+- Vector search (FLAT, HNSW, SVS-VAMANA) ✅
+- Semantic caching ✅
+- Semantic routing ✅
+- LangChain4J integration ✅
+- Rerankers ✅
+- Message History (including SemanticMessageHistory) ✅
+
+### For Future Releases
+
+1. **Ongoing**: Add cloud vectorizer integrations as needed (or recommend LangChain4J)
+2. **Consider**: CLI tools if there's user demand
+
+---
+
+## Test Coverage Comparison
+
+| Area | Python Tests | Java Tests | Notes |
+|------|--------------|------------|-------|
+| Schema | ✅ | ✅ | Comprehensive |
+| Index | ✅ | ✅ | Comprehensive |
+| Queries | ✅ | ✅ | Comprehensive |
+| Filters | ✅ | ✅ | Comprehensive |
+| Vectorizers | ✅ | ✅ | Local models tested |
+| Rerankers | ✅ | ✅ | Mock/integration tests |
+| SemanticCache | ✅ | ✅ | Comprehensive |
+| LangCache | ✅ | ✅ | Comprehensive (PR #442) |
+| MessageHistory | ✅ | ✅ | Basic coverage |
+| SemanticRouter | ✅ | ✅ | Comprehensive |
+| LangChain4J | N/A | ✅ | Comprehensive |
+
+---
+
+*Report generated for RedisVL4J feature parity audit.*