From 8be714e926392baff99e7dd47aba6256c23250b9 Mon Sep 17 00:00:00 2001 From: sagi lefler Date: Wed, 3 Jun 2026 13:40:21 -0600 Subject: [PATCH] docs: add AGENTS.md, CONTRIBUTING.md, and LICENSE (GTI-848) - Add CONTRIBUTING.md: setup, architecture, workflow, testing, code style, demos, PR/commit conventions, and resources - Add AGENTS.md: agent guide covering build/test/release model, module map, working rules, and CI workflows - Add MIT LICENSE (resolves dangling README link) - Expand README with architecture, core use cases, repository structure, and dependency/runtime model - Gitignore .claude/ and specs/ Co-Authored-By: Claude Opus 4.8 (1M context) --- .gitignore | 6 + AGENTS.md | 261 +++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 319 ++++++++++++++++++++++++++++++++++++++++++++++++ LICENSE | 21 ++++ README.md | 67 ++++++++++ 5 files changed, 674 insertions(+) create mode 100644 AGENTS.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE diff --git a/.gitignore b/.gitignore index df8ae1b..723de38 100644 --- a/.gitignore +++ b/.gitignore @@ -81,5 +81,11 @@ notebooks/*_output.ipynb spotbugs-output.txt +# Claude Code +.claude/ + +# Specs / scratch +specs/ + # Demos demos/rag-multimodal/src/main/resources/application.properties diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..1a42afb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,261 @@ +# RedisVL Java Agent Guide + +**Last updated**: 2026-06-03 + +Guidance for AI coding agents (Claude Code, Cursor, Copilot, etc.) working in the +**redis-vl-java** repository. Humans should also read [CONTRIBUTING.md](CONTRIBUTING.md); +this file gives agents the fast path to building, testing, and conforming to project +conventions. + +## Project Overview + +RedisVL Java is a Gradle multi-module Java library — the AI-native Redis vector library — +published to Maven Central as `com.redis:redisvl` and consumed as a dependency by Java +applications. It is not a deployable service. It is closer to an SDK plus patterns, +examples, and docs for AI-native Redis usage than a thin client wrapper. + +Built on [Jedis](https://github.com/redis/jedis), it provides index schemas, vector / +hybrid / text queries, storage, vectorizers, rerankers, and extensions (LLM cache, message +history, semantic router, summarization). Public API lives under `com.redis.vl.*`. + +## What the Library Does + +Major capabilities: + +- Define Redis search/index schemas in YAML or Java +- Create and manage Redis-backed search indices (`SearchIndex`) +- Store documents, metadata, and embeddings (Redis Hash or Redis JSON) +- Run vector, text, filter, hybrid, count, and aggregation queries +- LangChain4J adapters for embedding store, retriever, chat memory, and document store +- LLM semantic caching and embeddings cache +- Semantic routing +- LLM chat / message history persistence +- Vectorizers (LangChain4J providers + local ONNX models) and rerankers +- VCR-style record/replay testing for deterministic LLM/embedding flows + +## How Customers Use It + +1. Run Redis 8+ or Redis Stack (search + vector capabilities required). +2. Add `com.redis:redisvl` to a Java 17+ application; connect to Redis via Jedis. +3. Define an `IndexSchema` (YAML or Java) and create a `SearchIndex`. +4. Load data and embeddings into Redis. +5. Query with `VectorQuery`, `HybridQuery`, `FilterQuery`, and related types. + +Adoption tends to fall into three buckets: teams that want a Java vector-search library on +Redis (basic `schema`/`index`/`query` APIs); teams building RAG/chat apps with LangChain4J +(the `langchain4j` adapters); and teams wanting reusable AI infra patterns (the +`extensions`). + +## Supported Redis Targets + +- **Redis 8.0+** (built-in search and vector capabilities) +- **Redis 8.4+** for native `FT.HYBRID` support +- Redis Stack, Redis Enterprise, Redis Cloud + +Plain Redis OSS without the search/vector capabilities does not support the full feature +set. + +## Source of Truth + +Read in this order: + +1. The active feature spec in `specs//` (local-only — see Spec Workflow) +2. `README.md` — user-facing project overview and public API examples +3. The Antora docs under `docs/` +4. This file + +## Before Coding + +1. If a feature spec exists, read its spec, plan, and tasks. +2. Read `README.md` for the public API surface and user expectations. +3. Look at neighboring code before introducing new patterns. + +Do not implement behavior changes that contradict an approved spec or existing +conventions. + +## Module Map + +| Module | Purpose | +|---|---| +| `core/` | Core library — schema, index, query, storage, extensions, vectorizers, rerankers, VCR. Published as `com.redis:redisvl`. **Tests live here** in `core/src/test/`. | +| `docs/` | Antora documentation site + Javadoc generation | +| `demos/` | Sample applications (`rag-multimodal`, `langchain4j-vcr`, `spring-ai-vcr`) | +| `notebooks/` | Jupyter notebooks for interactive walkthroughs | +| `specs/` | Feature specs, one folder per feature (gitignored / local-only) | + +Key config files: `gradle.properties`, `build.gradle.kts`, `core/build.gradle.kts`, +`settings.gradle.kts`, `jreleaser.yml`. + +## Best Demos to Run First + +```bash +./gradlew :demos:langchain4j-vcr:test # Record/replay testing with LangChain4J +./gradlew :demos:spring-ai-vcr:test # Record/replay testing with Spring AI +``` + +The VCR demos run with no API key (pre-recorded cassettes). `demos:rag-multimodal` is a +JavaFX multimodal RAG demo. + +## New Feature Gate + +For non-trivial features, work from an approved spec. A feature spec lives in +`specs//` and consists of: + +1. `specs//spec.md` — requirements and acceptance scenarios +2. `specs//plan.md` — implementation design +3. `specs//tasks.md` — execution checklist + +Prefer not to write implementation code for a sizeable feature until the spec is agreed. +Bug fixes and small changes don't require a spec. + +Branch names must be **under 50 characters**: a short type prefix, a `/`, then the slug. + +``` +feat/848-agents-contributing ✓ +fix/maxdistance-precision ✓ +docs/document-count-chatrole ✓ +chore/upgrade-jedis ✓ +feat/add-a-very-long-description-that-keeps-going ✗ too long +``` + +Common prefixes: `feat/`, `fix/`, `docs/`, `chore/`, `refactor/`, `test/`. + +## Working Rules + +- Keep changes focused and reviewable; do not refactor unrelated code. +- Add or update tests when behavior changes. **Tests go in `core/src/test/java/com/redis/vl/`** (this repo colocates tests inside `core` — there is no separate `tests/` module). +- Tag long-running tests `@Tag("slow")` and live-service tests `@Tag("integration")` so they stay out of the default build. +- Do not add dependencies without justification; LangChain4J/Spring AI providers are `compileOnly` (optional) — keep them optional. +- Do not hard-code environment-specific values. +- Do not weaken, skip, or delete tests to force a change through. +- Keep the **public API stable** — this is a published library (`com.redis:redisvl`). Flag breaking signature changes rather than making them silently. +- Add Javadoc to public types and methods (the build runs doclint). +- Update docs under `docs/` when changing user-visible behavior. +- **This repo has no Maven wrapper.** Use `./gradlew` only. +- Do not commit, push, or open PRs unless explicitly asked. + +## Known Inconsistencies to Avoid Repeating + +- **Java version**: source/target compatibility is **Java 17** and consumers need Java 17+, but the Gradle toolchain and CI build with **JDK 21**. Build with JDK 21; do not use APIs newer than Java 17. +- **VCR is experimental** (so labeled in the README) — treat its surface as unstable unless told otherwise. +- Demo modules are intentionally held to **relaxed** build standards (the root build skips strict rules for `rag-` demos). Don't copy demo-grade patterns into `core`. +- Feature maturity varies; docs still mention planned gaps in advanced topics. + +## When To Ask + +Ask for clarification when: + +- a requirement is ambiguous on a critical point +- a decision affects scope, security, or public API / user experience +- multiple valid approaches have different architectural consequences +- the proposed change conflicts with the spec or existing conventions + +## Verification + +Run before every commit or push that touches source code: + +```bash +./gradlew spotlessApply # fix formatting +./gradlew spotlessCheck build -S # must be fully green +``` + +Do not commit or push if tests are failing or formatting is dirty. If verification cannot +run (e.g., no Docker available for Testcontainers), say so explicitly — do not skip +silently. + +## Build Essentials + +```bash +# Fix formatting (ALWAYS before finishing) +./gradlew spotlessApply + +# Full build + tests + SpotBugs +./gradlew build -S + +# Run a specific test class +./gradlew :core:test --tests "com.redis.vl.." + +# Tagged suites (excluded from the default build) +./gradlew :core:integrationTest +./gradlew :core:slowTest + +# Replay AI-model tests without an API key +VCR_MODE=PLAYBACK ./gradlew test + +# Build without tests +./gradlew assemble -S +``` + +The build is strict: `-Xlint:all -Werror`, plus Spotless (google-java-format), SpotBugs +(main code only), and a JaCoCo 80% coverage rule. + +## Current Technical Baseline + +- Language: **Java 17** source/target; **JDK 21** toolchain (`build.gradle.kts`) +- Redis client: **Jedis 7.3.0** (public `api` dependency) +- AI integrations (optional, `compileOnly`): **LangChain4J 0.36.2**, **Spring AI 1.1.0** +- Local models: **ONNX Runtime 1.16.3**, DJL HuggingFace tokenizers 0.30.0 +- Build: Gradle (Kotlin DSL) — wrapper version and library versions in build files / `gradle.properties` +- Current version: see `gradle.properties` + +## Test Strategy + +- Unit tests, Testcontainers-backed Redis tests, integration-style tests, slow tests, and + VCR-based deterministic tests for LLM/embedding flows. +- **All tests live in `core/src/test/`** (colocated with the library, not a separate + module). +- The default `:core:test` task **excludes** `slow` and `integration` tags; dedicated + `integrationTest` and `slowTest` Gradle tasks run them. The PR build therefore does not + exercise every path — run the tagged suites when relevant. +- VCR cassettes live in `core/src/test/resources/vcr-data/`; `VCR_MODE=PLAYBACK` replays + them with no API key. Use `VCR_MODE=RECORD` (with a real key) only when you intentionally + need new cassettes, and commit the result. + +## Documentation System + +Built with [Antora](https://antora.org/). Source lives under `docs/`. + +- Javadocs are generated during the docs build (`aggregateJavadoc`) and included in the + Antora site. +- Published to GitHub Pages via `.github/workflows/docs.yml`. +- Docs are a first-class deliverable — update them when changing user-visible behavior. + +## CI Workflows + +| File | Trigger | Purpose | +|---|---|---| +| `.github/workflows/build.yml` | Pull request | `spotlessCheck` + `build` (JDK 21); uploads test reports on failure | +| `.github/workflows/early-access.yml` | Push to `main` | Snapshot publish via JReleaser (appends `-SNAPSHOT` unless already prerelease/tagged) | +| `.github/workflows/release.yml` | Manual `workflow_dispatch` | Official release: bumps `gradle.properties`, publishes to Maven Central, triggers docs | +| `.github/workflows/docs.yml` | Manual / dispatch | Docs site publish to GitHub Pages | + +Releasing is operator-driven via `workflow_dispatch` and depends on secrets (GitHub token, +GPG signing keys, Maven Central/Sonatype credentials) — **do not bump the +`gradle.properties` version or trigger releases unless explicitly asked.** + +## Spec Workflow + +Use `specs/` for feature work. Each feature gets its own folder, named after the tracker +slug (or a plain slug if none): + +```text +specs/848-add-agents-contributing/ # Jira/GH ticket slug +specs/maxdistance-precision/ # no tracker slug +└── each folder contains: spec.md, plan.md, tasks.md +``` + +The slug is the branch name minus the `feat/` or `fix/` prefix. `specs/` is **gitignored** +(local-only working material), so spec files are not committed. + +## Important Links + +- GitHub: https://github.com/redis/redis-vl-java +- Docs: https://redis.github.io/redis-vl-java/redisvl/current/ +- Maven Central: https://central.sonatype.com/artifact/com.redis/redisvl +- Issues: https://github.com/redis/redis-vl-java/issues + +## Recent Changes + + + +- add-agents-contributing: added AGENTS.md and CONTRIBUTING.md; documented architecture, build, test, and release model diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e66530a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,319 @@ +# Contributing to RedisVL Java + +Thank you for your interest in contributing to the Redis Vector Library for Java (RedisVL)! We welcome contributions from the community — bug fixes, new features, documentation improvements, increased test coverage, and demo additions are all appreciated. + +## Table of Contents + +- [Getting Started](#getting-started) +- [Development Setup](#development-setup) +- [Project Architecture](#project-architecture) +- [Development Workflow](#development-workflow) +- [Testing](#testing) +- [Code Style](#code-style) +- [Adding a Demo](#adding-a-demo) +- [Submitting Changes](#submitting-changes) +- [Reporting Issues](#reporting-issues) +- [Additional Resources](#additional-resources) +- [Getting Help](#getting-help) +- [License](#license) + +## Getting Started + +Before contributing, please: + +1. Read the [README.md](README.md) to understand the project and its public API. +2. Check existing [issues](https://github.com/redis/redis-vl-java/issues) and [pull requests](https://github.com/redis/redis-vl-java/pulls) to avoid duplicate work. +3. For significant changes, open an issue first to discuss your approach. + +## Development Setup + +### Prerequisites + +- **JDK 21** — the build uses a Gradle toolchain that compiles with JDK 21 while targeting Java 17 bytecode. (CI uses the Zulu distribution.) +- **Docker** — required to run the test suite (Testcontainers spins up Redis Stack). +- **Gradle wrapper** — no global Gradle install needed; always use `./gradlew`. + +### Clone and Build + +```bash +git clone https://github.com/redis/redis-vl-java.git +cd redis-vl-java +./gradlew build +``` + +### Start Redis + +Most tests use [Testcontainers](https://testcontainers.com/) and start Redis Stack automatically — you just need Docker running. To run a Redis instance manually (for demos, notebooks, or ad-hoc testing): + +```bash +docker run -d --name redis -p 6379:6379 -p 8001:8001 redis:latest +``` + +RedisVL requires **Redis 8.0+** (built-in search and vector capabilities). Native `FT.HYBRID` support requires **Redis 8.4+**. + +## Project Architecture + +This is a multi-module Gradle (Kotlin DSL) project: + +``` +redis-vl-java/ +├── core/ # The main library, published as com.redis:redisvl (the deliverable) +├── docs/ # Antora documentation site + generated Javadocs +├── demos/ # Runnable example applications +│ ├── rag-multimodal/ # JavaFX multimodal RAG demo +│ ├── langchain4j-vcr/ # Record/replay testing with LangChain4J +│ └── spring-ai-vcr/ # Record/replay testing with Spring AI +└── notebooks/ # Jupyter notebooks for interactive walkthroughs +``` + +### Core Library + +Key packages inside `core/src/main/java/com/redis/vl/`: + +- **`index/`** — index creation, loading, querying, and fetch operations (`SearchIndex` is the main entry point) +- **`schema/`** — schema and field definitions +- **`query/`** — vector, text, count, aggregation, and hybrid query objects +- **`storage/`** — Redis Hash and Redis JSON storage behavior +- **`langchain4j/`** — LangChain4J adapters (embedding store, retriever, chat memory, document store) +- **`extensions/cache/`** — semantic cache and embeddings cache +- **`extensions/router/`** — semantic router +- **`extensions/messagehistory/`** — message history and semantic message history +- **`utils/vectorize/`** — vectorizer integrations (LangChain4J and local ONNX models) +- **`utils/rerank/`** — reranking utilities +- **`test/vcr/`** — VCR-style record/replay support for LLM-related tests + +The library is built on [Jedis](https://github.com/redis/jedis) (the public Redis client dependency). LangChain4J and Spring AI integrations are optional compile-time dependencies — consumers include only what they need. + +## Development Workflow + +### 1. Create a Branch + +```bash +git checkout -b fix/short-description +# or +git checkout -b feat/short-description +``` + +### 2. Make Your Changes + +Edit source files under `core/src/`. Build the module: + +```bash +./gradlew :core:build +``` + +The build is strict: compilation uses `-Xlint:all -Werror`, so warnings fail the build. + +### 3. Format Code + +Apply the project's code style (Spotless + google-java-format) before committing: + +```bash +./gradlew spotlessApply +``` + +To check without modifying files: + +```bash +./gradlew spotlessCheck +``` + +### 4. Run Tests + +```bash +# Default suite (requires Docker; excludes slow + integration tests) +./gradlew :core:test + +# A specific test class +./gradlew :core:test --tests "com.redis.vl.index.SearchIndexTest" + +# Tests with verbose output +./gradlew :core:test --info +``` + +### 5. Common Commands + +| Command | Description | +|---------|-------------| +| `./gradlew build` | Compile, run code-style check, tests, and SpotBugs across modules | +| `./gradlew :core:test` | Run the default core test suite (excludes `slow`/`integration`) | +| `./gradlew :core:integrationTest` | Run tests tagged `integration` | +| `./gradlew :core:slowTest` | Run tests tagged `slow` | +| `./gradlew spotlessApply` | Auto-format all source files | +| `./gradlew spotlessCheck` | Check formatting without modifying (what CI runs) | +| `./gradlew :core:jacocoTestReport` | Generate a coverage report | +| `./gradlew publishToMavenLocal` | Publish a snapshot to `~/.m2` for local testing | + +## Testing + +The test stack uses **JUnit 5**, **AssertJ**, **Mockito**, and **Testcontainers** (with `testcontainers-redis`). Make sure Docker is running before invoking the tests. + +### Running Tests + +```bash +# Default suite (unit + Testcontainers; excludes slow + integration) +./gradlew :core:test + +# One test class +./gradlew :core:test --tests "*.VectorQueryTest" + +# Tagged suites +./gradlew :core:integrationTest +./gradlew :core:slowTest +``` + +> **Note:** the default `test` task **excludes** tests tagged `slow` and `integration` (configured in `core/build.gradle.kts`). The PR build does not cover every behavior path — run `integrationTest`/`slowTest` explicitly when your change touches those areas. + +### Writing Tests + +New features and bug fixes **must** include tests. Place test classes under: + +``` +core/src/test/java/com/redis/vl/ +``` + +Guidelines: + +- Use JUnit 5 + AssertJ assertions; use Mockito for collaborators. +- Use Testcontainers for tests that require a live Redis — don't assume a locally running instance. +- Name test methods clearly (a descriptive name or `givenX_whenY_thenZ`). +- Test both the happy path and edge cases (empty results, null fields, large payloads). +- Tag long-running tests `@Tag("slow")` and live-service/integration tests `@Tag("integration")` so they're excluded from the default build. + +### VCR Testing (AI model calls) + +Tests that exercise embedding/chat models use a VCR (record/replay) mechanism so they can run without live API keys. Control the mode with the `VCR_MODE` environment variable: + +```bash +# Replay recorded cassettes only — no API key needed (this is what CI uses) +VCR_MODE=PLAYBACK ./gradlew test + +# Record new cassettes (requires a real API key) +VCR_MODE=RECORD OPENAI_API_KEY=your-key ./gradlew test +``` + +Cassettes are stored under `core/src/test/resources/vcr-data/`. If you add a test that calls an external model, record its cassette and commit it so CI can replay it. See the [VCR testing docs](https://redis.github.io/redis-vl-java/redisvl/current/vcr-testing.html). Note that VCR is currently labeled **experimental**. + +### Test Coverage + +The project is configured with [JaCoCo](https://www.jacoco.org/), including an 80% coverage verification rule in the root build. Generate a report locally with: + +```bash +./gradlew :core:jacocoTestReport +# HTML report: core/build/reports/jacoco/test/html/index.html +``` + +New public APIs should have corresponding tests. + +## Code Style + +This project uses the **Spotless** Gradle plugin with [google-java-format](https://github.com/google/google-java-format). Key conventions (enforced automatically by the formatter): + +- **2-space indentation** +- **100-character line length** +- **No wildcard imports**; imports are sorted and unused imports are removed +- Trailing whitespace trimmed; files end with a newline + +Always run `./gradlew spotlessApply` before pushing — CI runs `spotlessCheck` and will fail on formatting violations. + +Additional guidelines: + +- The build compiles with `-Xlint:all -Werror`; fix warnings rather than suppressing them. +- Add Javadoc to all public types and methods — at minimum a one-line summary (the build runs doclint). +- [SpotBugs](https://spotbugs.github.io/) runs on main code (exclusions in `spotbugs-exclude.xml`) and is disabled for test code. +- Avoid raw types and unchecked casts; use `@SuppressWarnings` only when genuinely necessary and add a comment explaining why. +- Keep the **public API stable** — this is a published library; flag breaking signature changes rather than making them silently. + +## Adding a Demo + +Demos live in the `demos/` directory as independent modules. + +1. Create a new subdirectory: `demos//`. +2. Add a `build.gradle.kts` — copy an existing one (e.g., `demos/langchain4j-vcr/build.gradle.kts`) as a starting point. +3. Register it in the root `settings.gradle.kts`: + ```kotlin + include("demos:") + project(":demos:").projectDir = file("demos/") + ``` +4. Add a `README.md` inside the demo directory describing what it demonstrates, prerequisites (env vars, data files), and how to run it. +5. Demos are not held to the same strict build standards as `core` — but keep them runnable and documented. + +## Submitting Changes + +### Pull Request Checklist + +- [ ] Branch is based on `main` +- [ ] All tests pass: `./gradlew :core:test` +- [ ] Code is formatted: `./gradlew spotlessApply` +- [ ] New/changed public APIs have Javadoc +- [ ] Tests added for new behavior (with appropriate `@Tag`s) +- [ ] VCR cassettes committed for any new external-model tests + +### Pull Request Description + +- Use a clear, descriptive title referencing the issue if applicable (e.g., `fix(query): preserve maxDistance precision in VECTOR_RANGE query (#123)`). +- Describe **what** changed and **why**. +- Include before/after examples for API changes. + +### Commit Messages + +Follow the [Conventional Commits](https://www.conventionalcommits.org/) style: + +``` +(): + +[optional body] +``` + +Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore` + +Examples: +``` +feat(query): add MultiVectorQuery support +fix(index): preserve maxDistance precision in VECTOR_RANGE query +docs: document count(), ChatRole, and MultiVectorQuery +test: add integration tests for message history +refactor(messagehistory): deduplicate count() into base class +``` + +Keep the first line under 72 characters. Reference issues with `(#123)` at the end. Commit messages feed the release changelog (via JReleaser), so keep them clean. + +## Reporting Issues + +### Bug Reports + +Please include: + +1. **Environment**: Java version, RedisVL version, Redis server version, OS +2. **Minimal reproducible example** — the smaller, the better +3. **Expected vs. actual behavior** +4. **Full stack trace** + +### Feature Requests + +Describe: + +- The use case you're solving +- How you envision the API looking (code example) +- Any alternatives you considered + +## Additional Resources + +- [RedisVL Java Documentation](https://redis.github.io/redis-vl-java/redisvl/current/) +- [API Reference (Javadoc)](https://redis.github.io/redis-vl-java/redisvl/current/_attachments/javadoc/aggregate/index.html) +- [Redis Vector / Search Documentation](https://redis.io/docs/latest/develop/interact/search-and-query/) +- [Jedis](https://github.com/redis/jedis) +- [LangChain4J](https://github.com/langchain4j/langchain4j) +- [Testcontainers](https://testcontainers.com/) +- [Redis AI Recipes](https://github.com/redis-developer/redis-ai-resources) + +## Getting Help + +- **GitHub Issues**: [redis/redis-vl-java/issues](https://github.com/redis/redis-vl-java/issues) +- **Discord**: [Redis Discord Server](https://discord.gg/redis) + +## License + +By contributing to RedisVL Java you agree that your contributions will be licensed under the [MIT License](https://opensource.org/licenses/MIT). + +Thank you for helping make RedisVL Java better for everyone! diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..97c06d2 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025, Redis, inc. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index b895595..2a9e9d6 100644 --- a/README.md +++ b/README.md @@ -527,6 +527,73 @@ Enter [Redis](https://redis.io) – a cornerstone of the NoSQL world, renowned f The Redis Vector Library bridges the gap between the AI-native developer ecosystem and Redis's robust capabilities. With a lightweight, elegant, and intuitive interface, RedisVL makes it easy to leverage Redis's power. Built on the [Jedis](https://github.com/redis/jedis) client, RedisVL transforms Redis's features into a grammar perfectly aligned with the needs of today's AI/ML Engineers and Data Scientists. +RedisVL is more than a low-level client wrapper — it's an SDK plus a set of patterns, examples, and docs for AI-native Redis usage. At a high level it helps Java teams: + +- Define Redis search/index schemas in YAML or Java +- Create and manage Redis-backed search indices +- Store documents, metadata, and embeddings in Redis +- Run vector, text, filter, and hybrid queries +- Integrate Redis into LangChain4J-based RAG systems +- Add semantic cache, message history, reranking, and routing patterns + +## 🧱 Core Use Cases + +RedisVL is positioned around these primary use cases: + +- Vector similarity search +- Hybrid text + vector search +- RAG retrieval backends +- LLM semantic caching +- Embedding generation workflows +- Reranking search results +- Semantic routing +- LLM chat/message history persistence + +In practice, adoption tends to fall into three buckets, which maps to how you should pick APIs: + +| You are… | Use… | +|----------|------| +| Building a Java vector-search layer directly on Redis | The basic `schema` / `index` / `query` APIs | +| Building a RAG assistant or retrieval chain with LangChain4J | The `com.redis.vl.langchain4j` adapters | +| Looking for reusable AI infrastructure patterns | The `extensions` (cache, router, message history) | + +The main entry point is **`SearchIndex`**, which holds the schema and Redis connection behavior and exposes index lifecycle and query operations. Treat the demos and notebooks as reference implementations, not production architecture templates. + +## 🗂️ Repository Structure + +This is a multi-module Gradle (Kotlin DSL) project: + +| Module | Description | +|--------|-------------| +| **`core/`** | The main product code, published as the `com.redis:redisvl` Maven artifact. This is the customer-facing deliverable. | +| **`docs/`** | A dedicated [Antora](https://antora.org/) documentation site (not just a README supplement), including generated Javadocs. Treated as a maintained, first-class artifact and part of the delivery pipeline. | +| **`demos/`** | Sample applications: `rag-multimodal` (JavaFX multimodal RAG demo), `langchain4j-vcr`, and `spring-ai-vcr` (record/replay testing demos). Important for adoption and validation, but not shipped artifacts. | +| **`notebooks/`** | Jupyter notebooks for interactive walkthroughs — enablement and onboarding material for developers evaluating the library. | + +Key package areas inside `core` (`com.redis.vl.*`): + +- `index` — index creation, loading, querying, and fetch operations +- `schema` — schema and field definitions +- `query` — vector, text, count, aggregation, and hybrid query objects +- `storage` — Redis Hash and Redis JSON storage behavior +- `langchain4j` — LangChain4J adapters for embedding store, retriever, chat memory, and document store +- `extensions.cache` — semantic cache and embeddings cache +- `extensions.router` — semantic router +- `extensions.messagehistory` — message history and semantic message history +- `utils.vectorize` — vectorizer integrations for LangChain4J and local ONNX models +- `utils.rerank` — reranking utilities +- `test.vcr` — VCR-style record/replay support for LLM-related tests + +## ⚙️ Dependency & Runtime Model + +- Java **source/target compatibility is 17**; the Gradle toolchain builds with Java **21**. +- **Jedis** is the underlying — and public — Redis client dependency. RedisVL layers higher-level abstractions on top of it. +- **LangChain4J** integrations are mostly optional, compile-time integrations (`compileOnly`) — include only the providers you need. +- **ONNX Runtime** is bundled for local embedding and reranking support. +- **Spring AI** support is present mainly for VCR testing compatibility. + +This means you can use RedisVL in a basic Redis/vector-search mode without adopting every AI integration, while still being able to opt into richer AI-framework integrations when needed. + ## 📚 Examples and Notebooks Check out the [notebooks](notebooks/) directory for interactive Jupyter notebook examples: