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,
collection_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.
collection_path
instance-attribute
¶
Collection path in FoxNose (e.g. "knowledge-base").
Renamed from folder_path in 0.4.0. The legacy folder_path kwarg is
still accepted via :meth:_migrate_folder_path and the read-only
:attr:folder_path property — both will be removed in 1.0.
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, as are query-string keys (``"truncate_text"``,
``"query_params"``) — use the dedicated parameters below.
query_params = None
class-attribute
instance-attribute
¶
Extra query-string parameters forwarded to the FoxNose _search
endpoint (e.g. {"truncate_text": 200}).
These are query parameters, not body fields — passing them through
search_kwargs is rejected at validation time.
truncate_text = None
class-attribute
instance-attribute
¶
Cap the length of every text-typed field in the response, in
characters. Sent as the truncate_text query parameter. Must be >= 1.
Useful for RAG: it bounds the size of page_content server-side instead
of shipping full documents over the wire.
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.
folder_path
property
¶
Deprecated; alias for :attr:collection_path.
Methods:¶
from_client_params(*, base_url, api_prefix, auth, collection_path=None, folder_path=None, 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 |
collection_path
|
str | None
|
Collection path to search. Required (or pass the
deprecated |
None
|
folder_path
|
str | None
|
Deprecated alias for |
None
|
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._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: |