Skip to content

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. "https://<env_key>.fxns.io").

required
api_prefix str

Flux API prefix.

required
auth Any

An :class:~foxnose_sdk.auth.AuthStrategy instance.

required
collection_path str | None

Collection path to search. Required (or pass the deprecated folder_path alias).

None
folder_path str | None

Deprecated alias for collection_path. Emits a DeprecationWarning via the constructor's model_validator and will be removed in 1.0.

None
async_mode bool

If True, create an AsyncFluxClient instead.

False
timeout float

HTTP timeout in seconds.

15.0
**kwargs Any

Additional arguments passed to :class:FoxNoseRetriever.

{}

Returns:

Type Description
FoxNoseRetriever

A configured :class:FoxNoseRetriever instance.

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 _search response.

required
page_content_field str | None

Single data field to use as page_content.

None
page_content_fields list[str] | None

Multiple data fields concatenated with separator.

None
page_content_separator str

Separator when using page_content_fields.

'\n\n'
page_content_mapper Callable[[dict[str, Any]], str] | None

Custom callable (result) -> str for full control.

None
metadata_fields list[str] | None

Whitelist of data fields to include in metadata.

None
exclude_metadata_fields list[str] | None

Blacklist of data fields to exclude from metadata.

None
include_sys_metadata bool

Whether to include _sys fields in metadata.

True

Returns:

Type Description
list[Document]

A list of :class:langchain_core.documents.Document objects.