Merge pull request #11 from FoxNoseTech/feat/add-vector-fields-support

feat: vector search support for Flux API (v0.5.0)

Author: loookashow

docs/api-reference.md

@@ -34,6 +34,44 @@ Complete API reference for the FoxNose Python SDK.
       heading_level: 3
       members_order: source
 
+## Vector Search Models
+
+::: foxnose_sdk.flux.models.SearchMode
+    options:
+      show_source: false
+      heading_level: 3
+      members: false
+
+::: foxnose_sdk.flux.models.VectorSearch
+    options:
+      show_source: false
+      heading_level: 3
+      members: false
+
+::: foxnose_sdk.flux.models.VectorFieldSearch
+    options:
+      show_source: false
+      heading_level: 3
+      members: false
+
+::: foxnose_sdk.flux.models.VectorBoostConfig
+    options:
+      show_source: false
+      heading_level: 3
+      members: false
+
+::: foxnose_sdk.flux.models.HybridConfig
+    options:
+      show_source: false
+      heading_level: 3
+      members: false
+
+::: foxnose_sdk.flux.models.SearchRequest
+    options:
+      show_source: false
+      heading_level: 3
+      members: false
+
 ## Authentication
 
 ### JWTAuth

docs/changelog.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-03-19
+
+### Added
+
+- **Vector search models** in `foxnose_sdk.flux.models`:
+  - `SearchMode` enum (`text`, `vector`, `vector_boosted`, `hybrid`)
+  - `VectorSearch` — auto-generated embedding search configuration
+  - `VectorFieldSearch` — custom pre-computed embedding search configuration
+  - `VectorBoostConfig` — boost configuration for `vector_boosted` mode
+  - `HybridConfig` — weight configuration for `hybrid` mode
+  - `SearchRequest` — typed search payload with cross-field validation
+- **Convenience methods** on `FluxClient` and `AsyncFluxClient`:
+  - `vector_search()` — semantic search with auto-generated embeddings
+  - `vector_field_search()` — search with custom embedding vectors
+  - `hybrid_search()` — blended text + vector search
+  - `boosted_search()` — keyword search boosted by vector similarity
+- **Vector Search documentation** — dedicated guide covering all search modes
+- All convenience methods support `offset` and `**extra_body` pass-through for additional API parameters (`where`, `sort`, etc.)
+
+### Fixed
+
+- `examples/flux_client.py` search example now uses correct API keys (`find_text` and `results`)
+
 ## [0.4.2] - 2026-03-10
 
 ### Fixed
@@ -99,7 +122,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Error handling guide
 - Code examples
 
-[Unreleased]: https://github.com/foxnose/python-sdk/compare/v0.4.2...HEAD
+[Unreleased]: https://github.com/FoxNoseTech/foxnose-python/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/FoxNoseTech/foxnose-python/compare/v0.4.2...v0.5.0
 [0.4.2]: https://github.com/FoxNoseTech/foxnose-python/compare/v0.4.1...v0.4.2
 [0.4.1]: https://github.com/FoxNoseTech/foxnose-python/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/FoxNoseTech/foxnose-python/compare/v0.3.0...v0.4.0

docs/examples.md

@@ -261,6 +261,33 @@ print(resource["data"]["title"])
 results = client.search("blog-posts", body={"find_text": {"query": "python"}})
 ```
 
+### Vector Search
+
+**File:** `examples/vector_search.py`
+
+Vector search modes and configuration:
+
+- Semantic search with auto-generated embeddings
+- Custom embedding search
+- Hybrid text + vector search
+- Boosted search with vector similarity
+
+```python
+from foxnose_sdk.flux import FluxClient
+
+# Semantic search
+results = client.vector_search("blog-posts", query="machine learning")
+
+# Hybrid search
+results = client.hybrid_search(
+    "blog-posts",
+    query="ML applications",
+    find_text={"query": "machine learning"},
+    vector_weight=0.7,
+    text_weight=0.3,
+)
+```
+
 ## Running Examples
 
 1. Clone the repository:

docs/flux-client.md

@@ -89,6 +89,49 @@ for item in results["results"]:
     print(item["data"]["title"])
 ```
 
+## Vector Search
+
+The Flux API supports multiple vector search modes. See the [Vector Search guide](vector-search.md) for full documentation.
+
+### Quick Examples
+
+```python
+# Semantic search with auto-generated embeddings
+results = client.vector_search(
+    "blog-posts",
+    query="machine learning in healthcare",
+    top_k=10,
+)
+
+# Search with custom embeddings
+results = client.vector_field_search(
+    "speakers",
+    field="speaker_embedding",
+    query_vector=[0.012, -0.034, 0.056, ...],
+)
+
+# Hybrid text + vector search
+results = client.hybrid_search(
+    "blog-posts",
+    query="ML applications",
+    find_text={"query": "machine learning"},
+    vector_weight=0.7,
+    text_weight=0.3,
+)
+
+# Text search boosted by vector similarity
+results = client.boosted_search(
+    "blog-posts",
+    find_text={"query": "python tutorial"},
+    query="beginner programming guide",
+    boost_factor=1.5,
+)
+```
+
+All vector search methods support `offset`, `limit`, and `**extra_body` for additional parameters like `where` and `sort`.
+
+The raw `search()` method continues to work with plain dicts for backward compatibility.
+
 ## Introspection Endpoints
 
 Use Flux introspection to discover available routes and live schema metadata at runtime.