alexklibisz/elastiknn
60.5
Adequate · 6 November 2026
4.4k
lines of production code
Scala
with Java, Python
4
measurements over time
What this system is
Features
Add HashFieldType for Lucene integration
Introduces a new HashFieldType class within the elastiknn-lucene module to define how hash-based fields are indexed in Lucene. This type configures fields to be non-tokenized, index document and frequency information, omit norms, and is frozen for performance, enabling the library to properly store and retrieve hash vectors in the search index.
elastiknn-lucene/src/main/java/com/klibisz/elastiknn/lucene · high confidence
Add SIMD-accelerated vector operations via Project Panama
The library now includes a new \PanamaFloatVectorOps\ implementation that uses JDK incubator vector APIs (Project Panama/SIMD) to accelerate dense float vector calculations. This provides high-performance alternatives for dot product, L1/L2 distance, and cosine similarity, utilizing parallel accumulators and vector unrolling to maximize throughput. A \DefaultFloatVectorOps\ fallback and a \FloatVectorOps\ interface are also introduced to support this pluggable architecture, alongside a new \BooleanVectorOps\ class for efficient sorted integer intersection counting.
elastiknn-models/src/main/java/com/klibisz/elastiknn/vectors · high confidence
Add ann-benchmarks integration for performance testing
Adds a new integration directory for the ann-benchmarks tool, enabling users to benchmark Elastiknn's approximate nearest neighbor search performance. This includes a README with setup instructions and Task recipes for running benchmarks (e.g., Fashion MNIST), a submodule reference to the ann-benchmarks repository, a configuration file defining Elastiknn-specific algorithms (exact and L2LSH), a Python script to parse and format benchmark results into tables, and a shell script to scrape Docker container metrics during testing.
ann-benchmarks · high confidence
Added AWS development environment setup
Developers can now provision a remote development instance in AWS using Terraform. The new \development/aws\ directory contains the infrastructure configuration (EC2 instance, security groups, SSH keys) and a setup script that installs required tools (Docker, SBT, Task, Java, Python) and compiles the project, providing an alternative to local development for benchmarking and testing.
development · high confidence
Added SBT build infrastructure and Elasticsearch plugin development support
The project has migrated its build system to SBT (version 1.12.11), introducing a new \project\ directory with \build.properties\ and \plugins.sbt\ (including sbt-jmh, sbt-tpolecat, and sbt-scalafmt). A custom \ElasticsearchPluginPlugin\ was added to streamline development, providing tasks to download the Elasticsearch distribution, bundle the project into an installable plugin zip, and run or debug a local Elasticsearch node with the plugin installed.
project · high confidence
Initial release of the ElastiKnn Python client package
This change introduces the initial packaging structure for the ElastiKnn Python client, enabling users to install and use the library via standard Python tools. The diff establishes the \setup.py\ configuration, \MANIFEST.in\ to include \.pyi\ type hint files and \.proto\ definitions, and a \.gitignore\ to manage build artifacts. This provides the foundational distribution mechanism for the Python client, which implements queries against the ElastiKnn Elasticsearch plugin.
client-python · high confidence
Initial release of the Elastiknn Python client
Introduces the \elastiknn\ Python package, providing a high-level interface for interacting with the Elastiknn Elasticsearch plugin. The package includes an \ElastiknnClient\ for managing index mappings, indexing vector data, and executing nearest-neighbor queries, as well as an \ElastiknnModel\ class that offers a scikit-learn-compatible API (with \fit\ and \kneighbors\ methods) for training and querying vector models using exact and LSH algorithms.
client-python/elastiknn · high confidence
Introduce Docker-based Elasticsearch environment with JDK vector support
This change adds a new Docker setup for running Elasticsearch with the Elastiknn plugin, including a Dockerfile that installs the plugin into Elasticsearch 9.4.1, a health-check script, and Docker Compose files for benchmarking and testing. The benchmarking configuration enables the optional JDK incubator vector module (Project Panama/SIMD) for faster dense float vector operations and exposes JMX ports for monitoring, while the testing configuration sets up a multi-node cluster (master and data nodes) with similar vector support enabled.
docker · high confidence
Introduce elastiknn-api4s subproject with vector search API definitions
This change introduces the new \elastiknn-api4s\ subproject, which defines the core Scala data models and JSON serialization logic for the plugin's vector search capabilities. It adds case classes for vector types (\Vec.DenseFloat\, \Vec.SparseBool\, \Vec.Indexed\), similarity metrics (\Similarity\), and mapping configurations (\Mapping\), along with query structures (\NearestNeighborsQuery\) supporting exact and approximate (LSH) search modes. The subproject also includes Java utility buffers (\FloatArrayBuffer\, \IntArrayBuffer\) for efficient vector handling and an \XContentCodec\ to serialize these types to/from Elasticsearch's XContent format.
elastiknn-api4s/src/main · high confidence
Introduce new Elastic4s-based Scala client for vector operations
The elastiknn-client-elastic4s module now provides a dedicated Scala client built on the elastic4s library, enabling developers to interact with Elasticsearch for vector search tasks using idiomatic Scala patterns. This new client introduces \ElastiknnClient\ and \ElastiknnFutureClient\ abstractions that wrap elastic4s \ElasticClient\ to handle indexing vectors, creating indices with optimized mappings, and executing nearest-neighbor searches. It includes \ElastiknnRequests\ for constructing high-performance requests (such as storing document IDs as doc values for faster retrieval) and \Elastic4sCompatibility\ to seamlessly convert elastiknn query objects into elastic4s \Query\ types. Users can now instantiate the client from an existing Elasticsearch \RestClient\ or directly via host/port, with an optional \strictFailure\ mode to ensure non-2xx responses or bulk errors are raised as exceptions. Also in this area: Introduce elastiknn-api4s subproject with vector search API definitions; Introduce Java-based elastiknn-models module with LSH and similarity implementations.
repository · high confidence
Introduce score functions for nearest-neighbor queries
The plugin now supports using nearest-neighbor similarity as a scoring function within Elasticsearch's function\_score queries. This allows users to re-rank or boost documents based on vector similarity (e.g., cosine, L2, L1) alongside other scoring signals. The implementation adds specific query builders and score function parsers for both exact and approximate (LSH) vector searches, enabling hybrid search scenarios where vector proximity influences the final document ranking.
elastiknn-plugin/src/main/scala/com/klibisz/elastiknn/query · high confidence
Introduction of Elastiknn plugin with SIMD vector optimization support
The Elastiknn plugin is now available, providing Elasticsearch with specialized mappers for dense float and sparse boolean vectors, a custom query builder, and a score function for nearest-neighbor search. A key capability is the optional use of JDK incubator vector (Project Panama/SIMD) for accelerated dense float vector operations, controlled via the \elastiknn.jdk-incubator-vector.enabled\ setting. The plugin also introduces a unified \ElastiknnException\ hierarchy for error handling and registers the necessary components (queries, mappers, score functions) within the Elasticsearch plugin lifecycle.
elastiknn-plugin/src/main/scala/com/klibisz/elastiknn · high confidence
Introduction of VectorMapper for sparse boolean and dense float vector indexing
This change introduces the VectorMapper class and its specific implementations (SparseBoolVectorMapper and DenseFloatVectorMapper) within the elastiknn plugin. These components handle the parsing, validation, and Lucene field creation for sparse boolean and dense float vector types, supporting exact search and various LSH (Locality Sensitive Hashing) mappings like Jaccard, Hamming, Cosine, L2, and Permutation. The implementation includes a custom FieldType that returns an empty list from the ValueFetcher and utilizes x-content for decoding vectors, ensuring compatibility with Elasticsearch's mapping system while adhering to security constraints by avoiding unsafe runtime dependencies.
elastiknn-plugin/src/main/scala/com/klibisz/elastiknn/mapper · high confidence
Introduction of core model abstractions and caching for vector similarity
This change introduces the foundational Scala abstractions for the plugin's similarity models, specifically adding the \ExactSimilarityFunction\ trait and its implementations for Jaccard, Hamming, L1, L2, and Cosine similarities, alongside the \HashingFunction\ trait and a \ModelCache\ for managing LSH model instances. For users, this establishes the internal structure for how exact and approximate vector similarities are computed and cached within the plugin, supporting the various distance metrics available in the API.
elastiknn-plugin/src/main/scala/com/klibisz/elastiknn/models · high confidence
New MatchHashesAndScoreQuery for approximate vector search
Introduces the MatchHashesAndScoreQuery class, which enables approximate nearest neighbor search by matching document hashes and applying a configurable scoring function. This query supports limiting the number of candidate results, provides detailed explanations for similarity scores, and includes performance optimizations such as specialized handling for single-frequency hashes and efficient hit counting.
elastiknn-lucene/src/main/java/org · high confidence
New multimodal search tutorial for Amazon products
Added a new Jupyter notebook tutorial in the \examples/tutorial-notebooks\ directory that demonstrates multimodal search on the Amazon Products dataset. The tutorial uses Elasticsearch 7.9.2 with the Elastiknn plugin to index product metadata and 4096-dimensional image vectors, enabling combined keyword and nearest-neighbor (image similarity) searches. Supporting files include a Dockerfile, docker-compose configuration, and Python utility scripts to facilitate running the demo locally.
examples · high confidence
New vector storage abstraction and reader
The plugin introduces a new internal storage layer for vectors, decoupling the API representation from the physical storage format. This includes a \StoredVec\ trait hierarchy (supporting sparse boolean and dense float types) with typeclass-based codecs for encoding and decoding, and a \StoredVecReader\ class that efficiently retrieves these vectors from Lucene's binary doc values. This change provides a foundation for future optimizations, such as switching serialization methods or supporting streaming reads, without altering the public API.
elastiknn-plugin/src/main/scala/com/klibisz/elastiknn/storage · high confidence
Behavioural changes
1 commit (0 fixes) modifying .agents, .claude
A change to existing behaviour in .agents, .claude — 1 commit, 2 files: “Make repository guidance and skills agent-agnostic (\#871)” (refs \#871).
.agents · low confidence · unverified
1 commit (0 fixes) modifying elastiknn-plugin
A change to existing behaviour in elastiknn-plugin — 1 commit, 2 files: “Dependencies: upgrade Elasticsearch to 9.5.0 (\#884)” (refs \#884).
elastiknn-plugin/src/test/scala/com/klibisz/elastiknn · medium confidence · unverified
12 commits (0 fixes) modifying elastiknn-client-elastic4s
A change to existing behaviour in elastiknn-client-elastic4s — 12 commits, 3 files: “Build: use sbt-tpolecat plugin for stricter compilation (\#589)”; “Plugin, client: switch to x-content for JSON codecs to reduce plugin size (\#321)”; “Dependency upgrades: Elasticsearch 7.13.0, Lucene 8.8.2, Elastic4s 7.12.2 (\#269)”; and 9 more (refs \#589, \#321, \#269, \#129, \#682, …).
elastiknn-client-elastic4s · medium confidence · unverified
3 commits (0 fixes) modifying .claude
A change to existing behaviour in .claude — 3 commits, 2 files: “Dependencies: upgrade Elasticsearch to 8.18.5 (\#834)”; “Add Claude Code setup (\#833)”; “Make repository guidance and skills agent-agnostic (\#871)” (refs \#834, \#833, \#871).
.claude · medium confidence · unverified
8 commits (0 fixes) modifying elastiknn-models/src/main/java/com/klibisz/elastiknn/models
A change to existing behaviour in elastiknn-models/src/main/java/com/klibisz/elastiknn/models — 8 commits, 6 files: “Feature: add ability to optionally use jdk.incubator.vector (aka Project Panama, aka SIMD) for faster dense float vector operations (\#496)”; “Renaming "Angular" to "Cosine" in Plugin and Scala client (Re \#277) (\#294)”; “Flip dependencies so that lucene depends on models (\#194)”; and 5 more (refs \#496, \#277, \#294, \#194, \#173, …).
elastiknn-models/src/main/java/com/klibisz/elastiknn/models · medium confidence · unverified
Added backward-compatible codec wrappers for Lucene 8.4–8.8
The plugin now includes new codec classes (Elastiknn84Codec, Elastiknn86Codec, Elastiknn87Codec, and Elastiknn88Codec) that wrap the corresponding Lucene backward codecs. These are provided for backward compatibility with older index formats, though they are noted as no longer used in Elasticsearch 8.
elastiknn-plugin/src/main/scala/com/klibisz/elastiknn/codec · high confidence
Plugin security policy tightened and utility class added
The plugin's security policy has been restricted by removing the getClassLoader permission, ensuring a more secure execution environment. Additionally, a new utility class, VectorMapperUtil, was introduced to provide a shared empty array constant for FieldMapper parameters, supporting consistent vector mapping configurations.
elastiknn-plugin/src/main/plugin-metadata · high confidence
Refactored hit counting internals with optimized ArrayHitCounter
The search module now uses a new \HitCounter\ interface to abstract document hit counting, replacing previous inline implementations. The primary implementation, \ArrayHitCounter\, introduces a specialized \kthGreatest\ algorithm that computes the k-th highest hit count in linear time, enabling more efficient retrieval of top-k results via a custom \DocIdSetIterator\. An \EmptyHitCounter\ is also provided for cases with zero matches. These changes simplify query internals and optimize performance for scenarios where hash matches are sparse or unique.
elastiknn-lucene/src/main/java/com/klibisz/elastiknn/search · high confidence
Registration of Elastiknn codecs for Lucene 8.4–8.8
The plugin now registers four specific Lucene codecs (Elastiknn84Codec, Elastiknn86Codec, Elastiknn87Codec, and Elastiknn88Codec) via the standard Java SPI mechanism. This enables the plugin to support indexing and searching with these Lucene codec versions, ensuring compatibility with the underlying search engine's storage format.
elastiknn-plugin/src/main/resources · high confidence
Test coverage
Added JMH benchmarks for vector operations, serialization, and hit counting; Added Python client and model tests; Added elastiknn integration tests; Added performance benchmarking tests for HashingQuery; Added tests for ArrayHitCounter and Lucene test utilities; Added tests for MatchHashesAndScoreQuery behavior; Added tests for Panama SIMD vector operations; Added tests for XContentCodec serialization and deserialization; Added tests for exact similarity functions and Permutation LSH model determinism; Added tests for storage serialization components; Added unit tests for elastiknn LSH models.
Dependencies
Upgrade to Elasticsearch 9.4.1 and Scala 3.3.7
The build configuration has been updated to use Elasticsearch 9.4.1, Scala 3.3.7, and Lucene 10.4.0. This upgrade includes corresponding updates to the elastic4s client (9.3.0), Circe (0.14.15), Guava (33.6.0-jre), and Eclipse Collections (13.0.0). The Python client dependencies have also been refreshed to align with the new Elasticsearch version.
(dependencies) · high confidence
Housekeeping
Initial repository structure and configuration
The repository has been initialized with the core project configuration files, including the version file (set to 9.4.1.0), build tool settings (SBT, scalafmt), and CI/CD task definitions (Taskfile.yaml). This includes the addition of .gitignore, .gitattributes, and .tool-versions to manage development environment consistency, as well as the replacement of the placeholder readme.md with a comprehensive README.md detailing the project's purpose as an Elasticsearch plugin for similarity search.
(repo-wide) · high confidence
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
This is the PUBLIC form of this artifact. Findings are listed in full, but the details of SECURITY findings — which rule fired, in which file, on which line, and how to fix it — are deliberately withheld, and any secret-scanner results are excluded entirely. Where detail is absent here it was REMOVED FOR PUBLICATION; it is not missing from the analysis. The complete artifact is available from the repository owner.
Score
- CAI 52 → 60 (+8.2)
- Rubric changed (rubric-2026.10.5 → rubric-2026.11.2) — scores are not directly comparable.
Lenses
- Code Health 59 → 59 (+0.0)
- Architecture 92 → 92 (+0.0)
- Maturity 40 → 60 (+19.6)
- Readiness 56 → 66 (+9.8)
- Security 69 → 56 (-12.4)
- Performance 89 → 89 (+0.0)
Resolved (4)
- High: security finding (details withheld)
- Medium CVE: PYSEC-2026-1976 (client-python/requirements.txt)
- No dependency advisory monitoring
- Redundant builder method across multiple query types. The with_vec method appears on Base and is duplicated on every specific query type (JaccardLsh, HammingLsh, etc.). Since these query types likely inherit from or wrap Base, this creates a confusing API surface where the same operation is available via inheritance and explicit repetition, or suggests a lack of a unified builder pattern.
New (4)
- Documentation: no build, run or usage example (README.md)
- High: security finding (details withheld)
- High: security finding (details withheld)
- High: security finding (details withheld)
Changes since last survey
- 50 commits — 47 feature/other, 3 fixes
By area
- (root) — 27 commits
- .github/workflows — 7 commits
- docs/Gemfile.lock — 7 commits
- project/plugins.sbt — 3 commits
- project/build.properties — 2 commits
- .github/dependabot.yml — 1 commit
- client-python/requirements.txt — 1 commit
- elastiknn-models/src — 1 commit
- elastiknn-plugin/src — 1 commit
Notable commits
- fix: Fix Python releases skipped by PyPI webpage check (#917)
- fix: Fix Scala Steward Java runtime (#894)
- fix: Loosen PanamaFloatVectorOpsSpec dotProduct tolerance to fix flaky test (#893)
- change: Add backport release option to release workflow (#872)
- change: Bump actions/deploy-pages from 4 to 5 (#906)
- change: Bump actions/setup-java from 4 to 6 (#904)
- change: Bump actions/setup-python from 5 to 7 (#901)
- change: Bump actions/upload-pages-artifact from 3 to 5 (#903)
- change: Bump addressable from 2.8.0 to 2.9.0 in /docs (#912)
- change: Bump arduino/setup-task from 2 to 3 (#899)
- change: Bump concurrent-ruby from 1.3.5 to 1.3.7 in /docs (#911)
- change: Bump faraday from 2.13.1 to 2.14.3 in /docs (#909)
- change: Bump json from 2.12.2 to 2.19.9 in /docs (#913)
- change: Bump rexml from 3.4.1 to 3.4.2 in /docs (#910)
- change: Bump tqdm from 4.61.1 to 4.66.3 in /client-python (#915)
- change: Bump uri from 1.0.3 to 1.0.4 in /docs (#908)
- change: Bump webrick from 1.7.0 to 1.8.2 in /docs (#914)
- change: Configure monthly Dependabot updates for GitHub Actions (#895)
- change: Dependencies: Update circe-generic, circe-parser from 0.14.15 to 0.14.16 (#865)
- change: Dependencies: Update circe-generic, circe-parser from 0.14.16 to 0.14.17 (#898)
- …and 30 more
Architecture
- Unchanged — 0 containers · 1 contexts · 0 edges
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
alexklibisz/elastiknn was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.
About this page
- The score is its most recent published measurement, taken on 6 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit 93d24141caf4843bac83719798476be3789a4dbf — the exact code this score is about.
- Scored under rubric-2026.11.2 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.3+preprod-60d1b390edf0.