LangChain.js Integration

FoxNoseRetriever, FoxNoseLoader, and createFoxNoseTool — full LangChain.js integration backed by FoxNose Flux search. Drop into any TypeScript RAG pipeline for text, vector, or hybrid retrieval.

@foxnose/langchain GitHub

Version:LatestLicense:Apache 2.0

Overview

@foxnose/langchain provides three LangChain.js components that connect to the FoxNose Flux API:

FoxNoseRetriever — a BaseRetriever for search-based document retrieval
FoxNoseLoader — a BaseDocumentLoader for bulk-loading folder contents with cursor-based pagination
createFoxNoseTool — a factory that wraps retrieval as a DynamicStructuredTool for LLM agents

Features

4 search modes — text, vector, hybrid, and vector-boosted retrieval
Content mapping — single field, multiple fields, or a custom mapper function to build Document.pageContent
Metadata control — whitelist, blacklist, or toggle system metadata on returned documents
Lazy loading — loadLazy() async generator for memory-efficient processing of large folders
Structured filtering — pass a where parameter to filter results before ranking
Agent-ready — createFoxNoseTool wraps retrieval as a tool with zod schema validation
Dual output — ESM and CommonJS with full TypeScript declarations

Installation

npm install @foxnose/langchain @foxnose/sdk @langchain/core

Quick Start

import { FluxClient, SimpleKeyAuth } from '@foxnose/sdk';
import { FoxNoseRetriever } from '@foxnose/langchain';

const client = new FluxClient({
  baseUrl: 'https://your-env.fxns.io',
  apiPrefix: 'content',
  auth: new SimpleKeyAuth('YOUR_PUBLIC_KEY', 'YOUR_SECRET_KEY'),
});

const retriever = new FoxNoseRetriever({
  client,
  folderPath: 'knowledge-base',
  pageContentField: 'body',
  searchMode: 'hybrid',
  topK: 5,
});

const docs = await retriever.invoke('how to build AI applications');
for (const doc of docs) {
  console.log(doc.pageContent.slice(0, 200));
}

Usage Examples

Vector search

const retriever = new FoxNoseRetriever({
  client,
  folderPath: 'articles',
  pageContentField: 'body',
  searchMode: 'vector',
  topK: 5,
  similarityThreshold: 0.7,
});

const docs = await retriever.invoke('latest developments in machine learning');

Hybrid search with custom weights

const retriever = new FoxNoseRetriever({
  client,
  folderPath: 'articles',
  pageContentField: 'body',
  searchMode: 'hybrid',
  hybridConfig: {
    vectorWeight: 0.7,
    textWeight: 0.3,
    rerankResults: true,
  },
});

const docs = await retriever.invoke('quantum computing breakthroughs');

Filtered retrieval

const retriever = new FoxNoseRetriever({
  client,
  folderPath: 'articles',
  pageContentField: 'body',
  searchMode: 'hybrid',
  where: {
    $: {
      all_of: [
        { status__eq: 'published' },
        { category__in: ['tech', 'science'] },
      ],
    },
  },
});

const docs = await retriever.invoke('renewable energy');

RetrievalQA chain

import { ChatOpenAI } from '@langchain/openai';
import { RetrievalQAChain } from 'langchain/chains';
import { FoxNoseRetriever } from '@foxnose/langchain';

const retriever = new FoxNoseRetriever({
  client,
  folderPath: 'articles',
  pageContentField: 'body',
  searchMode: 'hybrid',
});

const qa = RetrievalQAChain.fromLLM(
  new ChatOpenAI({ model: 'gpt-4o' }),
  retriever,
);

const result = await qa.invoke({ query: 'What are the best practices for API design?' });
console.log(result.text);

Bulk document loading

import { FoxNoseLoader } from '@foxnose/langchain';

const loader = new FoxNoseLoader({
  client,
  folderPath: 'knowledge-base',
  pageContentField: 'body',
  batchSize: 100,
});

// Load all documents at once
const docs = await loader.load();

// Or lazily iterate page-by-page
for await (const batch of loader.loadLazy()) {
  await vectorStore.addDocuments(batch);
}

Agent tool

import { createFoxNoseTool } from '@foxnose/langchain';

const tool = createFoxNoseTool({
  client,
  folderPath: 'knowledge-base',
  pageContentField: 'body',
  searchMode: 'hybrid',
  name: 'search_knowledge_base',
  description: 'Search the knowledge base for relevant articles.',
});

// Use with any LangChain agent
const result = await tool.invoke({ query: 'how to reset password' });

Resources

GitHub Repository — Source code and issues
npm Package — Package downloads
Build a RAG Pipeline with JavaScript / Node.js — Step-by-step RAG tutorial
Python LangChain Integration — Python equivalent
Flux API Reference — Content delivery API docs