v1.2.0

v1.2.0

Release Notes: 1.2.0

This document captures the net change from 1.1.1 to v1.2.0 as of March 27, 2026.
It reflects the current committed master branch after the 1.2.0 version bump and
excludes untracked local workspace files.

Current diff scope:

• 2 commits ahead of 1.1.1
• 3 files changed
• 19 insertions and 13 deletions

Executive Summary

v1.2.0 is a small API-focused release on top of 1.1.1. The net change set exposes
hybrid-search Reciprocal Rank Fusion tuning controls through the search API, aligns
the default ef request behavior with the server setting, and bumps the reported
server version string to 1.2.0.

This release is intended to work with Python Endee client version 0.1.23 or later.

The highest-impact changes for integrators are:

• /api/v1/search now accepts dense_rrf_weight
• /api/v1/search now accepts rrf_rank_constant
• invalid RRF tuning values now fail request validation with HTTP 400

Highlights

1. Hybrid-search RRF tuning is now part of the search API

• main() now accepts optional dense_rrf_weight and rrf_rank_constant in search
  requests.
• dense_rrf_weight must be between 0.0 and 1.0.
• rrf_rank_constant must be greater than 0.0.
• The dense and sparse blend is now derived at search time, with sparse weight
  computed as 1.0 - dense_rrf_weight.
• searchKNN() now receives these values directly instead of relying on local
  hard-coded constants.

Why this matters:

• Clients can tune hybrid ranking behavior per request instead of being locked to the
  previous fixed 0.5 / 0.5 weighting and rank constant 60.
• Integrators now have a stable API surface for experimentation and relevance tuning.
• Invalid tuning values fail early at the API boundary instead of silently falling
  through to search execution.

2. Search defaults are more explicit and centrally aligned

• The request handler now defaults ef to settings::DEFAULT_EF_SEARCH instead of
  passing 0.
• searchKNN() now also uses settings-backed defaults for ef,
  dense_rrf_weight, and rrf_rank_constant.
• settings.hpp now defines DEFAULT_DENSE_RRF_WEIGHT and
  DEFAULT_RRF_RANK_CONSTANT.

Why this matters:

• Search-request defaults now come from one configuration surface instead of being
  split between request parsing and local function constants.
• Future tuning changes are easier to make and audit because the defaults live in
  settings.

3. Versioning and client compatibility

• The backend version string is now 1.2.0.
• The intended minimum compatible Python Endee client version is 0.1.23.

Why this matters:

• Release packaging and runtime version reporting now align with the new release.
• Upgrade guidance is explicit for teams coordinating backend and Python client
  rollouts.

Operator-Facing Changes

Area	What changed in v1.2.0	Why teams should care
Search API	/api/v1/search now accepts dense_rrf_weight and rrf_rank_constant.	Clients can tune hybrid ranking without rebuilding the server.
Request validation	Invalid dense_rrf_weight and invalid rrf_rank_constant now return HTTP 400.	API consumers should validate payloads and update tests for the new contract.
Search defaults	ef now defaults directly to settings::DEFAULT_EF_SEARCH, and RRF defaults are settings-backed.	Request behavior is more explicit and easier to reason about across code paths.
Reported version	The backend version string is now 1.2.0.	Deployment metadata and server-reported version now match the release.
Python client compatibility	v1.2.0 is intended for Python Endee client 0.1.23 and later.	Upgrade plans should treat 0.1.23 as the minimum supported Python client baseline.

Upgrade Notes

1. Client request compatibility

• Existing search clients continue to work without sending the new fields.
• If you choose to send dense_rrf_weight, keep it within 0.0 to 1.0.
• If you choose to send rrf_rank_constant, keep it greater than 0.0.
• Update API tests and client-side validation to cover the new request parameters and
  their validation failures.

2. Staging checks worth doing

• Re-test hybrid search quality using your real dense and sparse workloads.
• Verify that clients depending on fixed hybrid weighting are still producing the
  expected ranking if they continue to use defaults.
• Validate application flows against Python Endee client 0.1.23 or newer before
  broad rollout.

Suggested Release Positioning

v1.2.0 is a focused search-tuning release for teams using hybrid retrieval. It
adds API-level control over RRF weighting and rank constants, makes search defaults
more explicit and settings-backed, sets the backend version to 1.2.0, and targets
Python Endee client 0.1.23 or later.