API Reference¶
langchain_foxnose.FoxNoseRetriever
¶
Bases: BaseRetriever
LangChain retriever backed by FoxNose Flux search.
Uses the FoxNose _search endpoint to retrieve documents with support
for text, vector, hybrid, and vector-boosted search modes.
Example
.. code-block:: python
from foxnose_sdk.flux import FluxClient
from foxnose_sdk.auth import SimpleKeyAuth
from langchain_foxnose import FoxNoseRetriever
client = FluxClient(
base_url="https://<env_key>.fxns.io",
api_prefix="my_api",
auth=SimpleKeyAuth("pk", "sk"),
)
retriever = FoxNoseRetriever(
client=client,
folder_path="knowledge-base",
page_content_field="body",
search_mode="hybrid",
top_k=5,
)
docs = retriever.invoke("How do I reset my password?")
Attributes¶
client = None
class-attribute
instance-attribute
¶
Synchronous :class:~foxnose_sdk.flux.FluxClient instance.
async_client = None
class-attribute
instance-attribute
¶
Asynchronous :class:~foxnose_sdk.flux.AsyncFluxClient instance.
folder_path
instance-attribute
¶
Folder path in FoxNose (e.g. "knowledge-base").
page_content_field = None
class-attribute
instance-attribute
¶
Single data field whose value becomes page_content.
page_content_fields = None
class-attribute
instance-attribute
¶
Multiple data fields concatenated into page_content.
page_content_separator = '\n\n'
class-attribute
instance-attribute
¶
Separator used when concatenating page_content_fields.
page_content_mapper = None
class-attribute
instance-attribute
¶
Custom callable (result_dict) -> str for full control over
page_content extraction.
metadata_fields = None
class-attribute
instance-attribute
¶
Whitelist of data fields to include in document metadata.
Mutually exclusive with exclude_metadata_fields.
exclude_metadata_fields = None
class-attribute
instance-attribute
¶
Blacklist of data fields to exclude from document metadata.
Mutually exclusive with metadata_fields.
include_sys_metadata = True
class-attribute
instance-attribute
¶
Whether to include _sys fields (key, folder, created_at, updated_at)
in document metadata.
search_mode = 'hybrid'
class-attribute
instance-attribute
¶
Search mode: "text", "vector", "hybrid", or "vector_boosted".
search_fields = None
class-attribute
instance-attribute
¶
Fields for text search (find_text.fields).
text_threshold = None
class-attribute
instance-attribute
¶
Typo-tolerance threshold for text search (find_text.threshold, 0-1).
vector_fields = None
class-attribute
instance-attribute
¶
Fields for vector search with auto-generated embeddings
(vector_search.fields). Mutually exclusive with vector_field.
similarity_threshold = None
class-attribute
instance-attribute
¶
Minimum cosine similarity for vector search (0-1).
top_k = 5
class-attribute
instance-attribute
¶
Maximum number of results to return. Must be >= 1.
where = None
class-attribute
instance-attribute
¶
Persistent structured filter applied to every search.
hybrid_config = None
class-attribute
instance-attribute
¶
Hybrid mode configuration (vector_weight, text_weight, rerank_results).
vector_boost_config = None
class-attribute
instance-attribute
¶
Vector-boosted mode configuration (boost_factor, similarity_threshold,
max_boost_results).
sort = None
class-attribute
instance-attribute
¶
Sort fields (prefix with - for descending).
search_kwargs = Field(default_factory=dict)
class-attribute
instance-attribute
¶
Extra parameters merged into the search request.
Known keys like limit and offset are extracted as named
parameters; the rest are passed through **extra_body to the
SDK convenience methods.
.. note::
Keys that conflict with ``SearchRequest`` fields (e.g.
``"search_mode"``, ``"vector_search"``) are rejected at
validation time.
embeddings = None
class-attribute
instance-attribute
¶
Optional LangChain Embeddings model. When set together with
vector_field, the retriever converts the query text into a vector
at query time via embeddings.embed_query().
.. warning::
The query text may be sent to a third-party embedding provider
(e.g. OpenAI) depending on the Embeddings implementation.
query_vector = Field(default=None, repr=False)
class-attribute
instance-attribute
¶
Pre-computed query vector for vector_field_search. When set
together with vector_field, this static vector is used on every
search invocation. Mutually exclusive with embeddings.
vector_field = None
class-attribute
instance-attribute
¶
Single field name for custom-embedding vector search
(vector_field_search). Required when embeddings or
query_vector is provided. Mutually exclusive with vector_fields.
Functions¶
from_client_params(*, base_url, api_prefix, auth, folder_path, async_mode=False, timeout=15.0, **kwargs)
classmethod
¶
Create a retriever by constructing the Flux client internally.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
base_url
|
str
|
FoxNose environment URL (e.g. |
required |
api_prefix
|
str
|
Flux API prefix. |
required |
auth
|
Any
|
An :class: |
required |
folder_path
|
str
|
Folder path to search. |
required |
async_mode
|
bool
|
If |
False
|
timeout
|
float
|
HTTP timeout in seconds. |
15.0
|
**kwargs
|
Any
|
Additional arguments passed to :class: |
{}
|
Returns:
| Type | Description |
|---|---|
FoxNoseRetriever
|
A configured :class: |
langchain_foxnose._search.build_search_body(query, *, search_mode='hybrid', top_k=5, search_fields=None, text_threshold=None, vector_fields=None, similarity_threshold=None, where=None, hybrid_config=None, vector_boost_config=None, sort=None, search_kwargs=None)
¶
Build a search request body for the FoxNose Flux _search endpoint.
.. deprecated:: 0.3.0 This function is deprecated and will be removed in v0.4.0. The retriever now uses SDK convenience methods directly.
This is a pure function with no side effects, making it easy to test independently of any client or retriever logic.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
query
|
str
|
The user's search query text. |
required |
search_mode
|
str
|
One of |
'hybrid'
|
top_k
|
int
|
Maximum number of results to return. |
5
|
search_fields
|
list[str] | None
|
Fields for text search ( |
None
|
text_threshold
|
float | None
|
Typo tolerance for text search ( |
None
|
vector_fields
|
list[str] | None
|
Fields for vector search ( |
None
|
similarity_threshold
|
float | None
|
Minimum cosine similarity ( |
None
|
where
|
dict[str, Any] | None
|
Structured filter object. |
None
|
hybrid_config
|
dict[str, Any] | None
|
Hybrid mode weight/rerank configuration. |
None
|
vector_boost_config
|
dict[str, Any] | None
|
Vector-boosted mode configuration. |
None
|
sort
|
list[str] | None
|
Sort fields (prefix with |
None
|
search_kwargs
|
dict[str, Any] | None
|
Extra parameters merged into the body last (overrides).
Note: overriding |
None
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A dictionary suitable for passing as |
dict[str, Any]
|
|
langchain_foxnose._document_mapper.map_results_to_documents(results, *, page_content_field=None, page_content_fields=None, page_content_separator='\n\n', page_content_mapper=None, metadata_fields=None, exclude_metadata_fields=None, include_sys_metadata=True)
¶
Convert FoxNose search results into LangChain Documents.
This is a pure function with no side effects.
Each result is expected to have the FoxNose shape::
{"_sys": {"key": "...", ...}, "data": {"title": "...", "body": "...", ...}}
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
results
|
list[dict[str, Any]]
|
List of result dicts from the FoxNose |
required |
page_content_field
|
str | None
|
Single |
None
|
page_content_fields
|
list[str] | None
|
Multiple |
None
|
page_content_separator
|
str
|
Separator when using page_content_fields. |
'\n\n'
|
page_content_mapper
|
Callable[[dict[str, Any]], str] | None
|
Custom callable |
None
|
metadata_fields
|
list[str] | None
|
Whitelist of |
None
|
exclude_metadata_fields
|
list[str] | None
|
Blacklist of |
None
|
include_sys_metadata
|
bool
|
Whether to include |
True
|
Returns:
| Type | Description |
|---|---|
list[Document]
|
A list of :class: |