### Start Vane Application Source: https://github.com/itzcrazykns/vane/blob/master/README.md Starts the Vane application after building. Open http://localhost:3000 to complete setup and configure settings. ```bash npm run start ``` -------------------------------- ### POST /api/config/setup-complete Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/endpoints.md Marks the setup as complete. ```APIDOC ## POST `/api/config/setup-complete` ### Description Marks the setup as complete. ### Method POST ### Endpoint /api/config/setup-complete ### Response #### Success Response (200) { "message": "Setup marked as complete." } #### Error Response (500) Internal server error. ``` -------------------------------- ### ActionRegistry usage example Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/researcher-actions.md Shows basic usage of ActionRegistry to get available action tools, create tool calls, and execute them. Also demonstrates error handling when executing an action with a stale tool name, catching the error and logging a message. ```typescript // basic — what the researcher does each turn const tools = ActionRegistry.getAvailableActionTools(config); const toolCalls: ToolCall[] = [{ id, name: 'web_search', arguments: { queries: ['A', 'B'] } }]; const outputs = await ActionRegistry.executeAll(toolCalls, additionalConfig); // error handling — a stale tool name try { await ActionRegistry.execute('gone_tool', {}, additionalConfig); } catch (e) { // 'Action with name gone_tool not found' } ``` -------------------------------- ### markSetupComplete Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/config-manager.md Marks the setup as complete and saves the configuration. ```APIDOC ## markSetupComplete ### Description Marks the setup as complete and saves the configuration. ### Method POST ### Endpoint N/A (class method) ### Parameters None ### Request Example ```ts configManager.markSetupComplete(); ``` ### Response #### Success Response (200) No return value. ``` -------------------------------- ### isSetupComplete Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/config-manager.md Returns whether the setup has been completed. ```APIDOC ## isSetupComplete ### Description Returns whether the setup has been completed. ### Method GET ### Endpoint N/A (class method) ### Parameters None ### Request Example ```ts const complete = configManager.isSetupComplete(); ``` ### Response #### Success Response (200) - **complete** (boolean) - `true` if setup is complete, `false` otherwise. ``` -------------------------------- ### createProviderInstance usage examples Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/base-model-classes.md Usage examples for createProviderInstance: basic creation with OpenAIProvider and error handling with OllamaProvider when raw config is invalid. The error message shown is 'Invalid config provided. Base URL must be provided'. ```ts // basic — replicate ModelRegistry's instance creation const provider = createProviderInstance(OpenAIProvider, id, 'OpenAI', { apiKey: 'sk-...', baseURL: 'https://api.openai.com/v1', }); const models = await provider.getModelList(); // error handling — invalid raw config propagates the provider's error try { createProviderInstance(OllamaProvider, id, 'Ollama', {}); } catch (e) { // 'Invalid config provided. Base URL must be provided' } ``` -------------------------------- ### BaseLLM usage examples Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/base-model-classes.md Usage examples for the BaseLLM methods. The first shows object generation with a schema and messages. The second demonstrates streaming text with tool calls, yielding content and tool call chunks until done. ```ts // basic — object generation (classifier pattern) const output = await llm.generateObject({ schema, messages: [{ role: 'system', content: prompt }, { role: 'user', content: query }], }); // advanced — stream text with tool calls const stream = llm.streamText({ messages, tools: [tool] }); for await (const chunk of stream) { console.log(chunk.contentChunk, chunk.toolCallChunk); if (chunk.done) break; } ``` -------------------------------- ### Install Dependencies Source: https://github.com/itzcrazykns/vane/blob/master/README.md Installs the project dependencies for a non-Docker installation. ```bash npm i ``` -------------------------------- ### history parameter example Source: https://github.com/itzcrazykns/vane/blob/master/docs/API/SEARCH.md Example of the history parameter for POST /api/search. Each pair consists of a role ('human' or 'assistant') and the message content. ```json [ ["human", "What is Vane?"], ["assistant", "Vane is an AI-powered search engine..."] ] ``` -------------------------------- ### addProvider usage example Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/model-registry.md Shows how to add an OpenAI provider with an API key and base URL, then log the provider ID and embedding model keys. ```typescript // basic — add an OpenAI provider (POST /api/providers) const provider = await new ModelRegistry().addProvider('openai', 'OpenAI', { apiKey: process.env.OPENAI_API_KEY, baseURL: 'https://api.openai.com/v1', }); console.log(provider.id, provider.embeddingModels.map(m => m.key)); ``` -------------------------------- ### Build Vane Application Source: https://github.com/itzcrazykns/vane/blob/master/README.md Builds the application for a non-Docker installation. ```bash npm run build ``` -------------------------------- ### ActionRegistry Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/researcher-actions.md Documentation for the ActionRegistry static class, including all methods, parameters, and usage examples. ```APIDOC ## ActionRegistry ### Description Static registry for research actions. Register, look up, and execute actions, and get available actions/tools/descriptions based on configuration. ### Methods #### register(action) - **Signature**: `static register(action: ResearchAction): void` - **Description**: Registers an action in the registry, keyed by `action.name`. - **Parameters**: - `action` (ResearchAction) - Required - The action to register. #### get(name) - **Signature**: `static get(name: string): ResearchAction | undefined` - **Description**: Retrieves a registered action by name. - **Parameters**: - `name` (string) - Required - The name of the action. - **Returns**: The action if found, otherwise `undefined`. #### getAvailableActions(config) - **Signature**: `static getAvailableActions(config: {...}): ResearchAction[]` - **Description**: Returns all actions that are enabled for the given configuration. - **Parameters**: - `config` (object) - Required - Configuration object with shape `{ classification: ClassifierOutput; fileIds: string[]; mode: SearchAgentConfig['mode']; sources: SearchSources[] }`. - **Returns**: Array of enabled actions. #### getAvailableActionTools(config) - **Signature**: `static getAvailableActionTools(config: {...}): Tool[]` - **Description**: Converts available actions into tool objects with name, description, and schema. - **Parameters**: - `config` (object) - Required - Same shape as above. - **Returns**: Array of `Tool` objects. #### getAvailableActionsDescriptions(config) - **Signature**: `static getAvailableActionsDescriptions(config: {...}): string` - **Description**: Returns a string of tool descriptions formatted as `\n\n` joined together. - **Parameters**: - `config` (object) - Required - Same shape as above. - **Returns**: String of tool descriptions. #### execute(name, params, additionalConfig) - **Signature**: `static async execute(name: string, params: any, additionalConfig: AdditionalConfig & { researchBlockId: string; fileIds: string[]; mode: SearchAgentConfig['mode'] }): Promise` - **Description**: Executes a registered action by name with given parameters and additional configuration. Throws an error if the action is not found. - **Parameters**: - `name` (string) - Required - Name of the action to execute. - `params` (any) - Required - Parameters to pass to the action. - `additionalConfig` (object) - Required - Additional configuration including `researchBlockId`, `fileIds`, and `mode`. - **Returns**: Promise resolving to `ActionOutput`. - **Throws**: `Error('Action with name not found')` if action is not registered. #### executeAll(actions, additionalConfig) - **Signature**: `static async executeAll(actions: ToolCall[], additionalConfig: AdditionalConfig & { researchBlockId: string; fileIds: string[]; mode: SearchAgentConfig['mode'] }): Promise` - **Description**: Executes multiple actions concurrently using `Promise.all`. Order of results is not guaranteed. - **Parameters**: - `actions` (ToolCall[]) - Required - Array of tool calls to execute. - `additionalConfig` (object) - Required - Same shape as above. - **Returns**: Promise resolving to an array of `ActionOutput`. ### Example Usage ```ts // basic — what the researcher does each turn const tools = ActionRegistry.getAvailableActionTools(config); const toolCalls: ToolCall[] = [{ id, name: 'web_search', arguments: { queries: ['A', 'B'] } }]; const outputs = await ActionRegistry.executeAll(toolCalls, additionalConfig); // error handling — a stale tool name try { await ActionRegistry.execute('gone_tool', {}, additionalConfig); } catch (e) { // 'Action with name gone_tool not found' } ``` ``` -------------------------------- ### isSetupComplete and markSetupComplete method signatures Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/config-manager.md Signatures for isSetupComplete and markSetupComplete methods. They check and set the setup completion status. ```typescript public isSetupComplete() public markSetupComplete() ``` -------------------------------- ### GET /api/providers response example Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/endpoints.md Example response body for the GET /api/providers endpoint. Shows the structure of a provider object with id, name, chatModels, and embeddingModels. The id and keys are used as chatModel.providerId/key in other endpoints. ```json { "providers": [ { "id": "uuid", "name": "OpenAI", "chatModels": [{"name": "GPT 4 omni mini", "key": "gpt-4o-mini"}], "embeddingModels": [{"name": "Text Embedding 3 Small", "key": "text-embedding-3-small"}] } ] } ``` -------------------------------- ### GET /api/providers response example Source: https://github.com/itzcrazykns/vane/blob/master/docs/API/SEARCH.md Response from GET /api/providers. Use the id field as providerId and the key field from the models arrays when making search requests. ```json { "providers": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "OpenAI", "chatModels": [ { "name": "GPT 4 Omni Mini", "key": "gpt-4o-mini" }, { "name": "GPT 4 Omni", "key": "gpt-4o" } ], "embeddingModels": [ { "name": "Text Embedding 3 Large", "key": "text-embedding-3-large" } ] } ] } ``` -------------------------------- ### updateProvider usage example Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/model-registry.md Demonstrates updating a provider's credentials and handling an unknown ID error. ```typescript // advanced — replace an existing provider's credentials const registry = new ModelRegistry(); const updated = await registry.updateProvider(id, 'OpenAI', { apiKey: newKey, baseURL }); // error handling: unknown id -> 'Provider not found' from configManager ``` -------------------------------- ### GET /api/discover Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/endpoints.md Fetches blog results from SearXNG with configurable mode and topic. ```APIDOC ## GET /api/discover?mode=&topic= ### Description Retrieves blogs based on mode and topic. ### Method GET ### Endpoint /api/discover?mode=&topic= ### Parameters #### Query Parameters - **mode** (string) - Optional - 'normal' or 'preview' (default 'normal') - **topic** (string) - Optional - 'tech', 'finance', 'art', 'sports', or 'entertainment' (default 'tech') ### Response #### Success Response (200) - **blogs** (array) - SearxngSearchResult[] #### Response Example { "blogs": [] } #### Error Response (500) - **message** (string) - 'An error has occurred' ``` -------------------------------- ### Clone and Enter Vane Directory Source: https://github.com/itzcrazykns/vane/blob/master/README.md Clones the Vane repository and navigates into the project directory for a non-Docker installation. ```bash git clone https://github.com/ItzCrazyKns/Vane.git cd Vane ``` -------------------------------- ### Run Vane with Docker (Recommended) Source: https://github.com/itzcrazykns/vane/blob/master/README.md Starts the Vane container with the bundled SearxNG search engine. The -v flag creates a persistent volume for data and uploaded files. After running, open http://localhost:3000 to configure settings. ```bash docker run -d -p 3000:3000 -v vane-data:/home/vane/data --name vane itzcrazykns1337/vane:latest ``` -------------------------------- ### Using splitText, getTokenCount, and computeSimilarity Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/utilities.md Example usage of the file/text utilities: `splitText` with custom overlap, `getTokenCount` for token counting, and `computeSimilarity` with error handling for length mismatch. ```ts // basic — chunk + embed a document const chunks = splitText(fullText, 512, 128); const tokens = getTokenCount(fullText); // error handling try { computeSimilarity(a, b); } catch (e) { if ((e as Error).message === 'Vectors must be of the same length') { /* pad/trim */ } } ``` -------------------------------- ### ConfigManager class definition Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/config-manager.md Defines the ConfigManager class with properties for config path, version, current config, and UI sections. The constructor initializes the config. The class exposes methods for getting, updating, and managing providers and models, as well as setup completion and UI sections. The singleton is created and exported at the end. ```typescript class ConfigManager { configPath: string = path.join( process.env.DATA_DIR || process.cwd(), '/data/config.json', ); configVersion = 1; currentConfig: Config = { ... }; uiConfigSections: UIConfigSections = { ... }; constructor() { this.initialize(); } private initialize() { ... } private saveConfig() { ... } private initializeConfig() { ... } private migrateConfig(config: Config): Config { return config; } private initializeFromEnv() { ... } public getConfig(key: string, defaultValue?: any): any public updateConfig(key: string, val: any) public addModelProvider(type: string, name: string, config: any) public removeModelProvider(id: string) public async updateModelProvider(id: string, name: string, config: any) public addProviderModel(providerId: string, type: 'embedding' | 'chat', model: any) public removeProviderModel(providerId: string, type: 'embedding' | 'chat', modelKey: string) public isSetupComplete() public markSetupComplete() public getUIConfigSections(): UIConfigSections public getCurrentConfig(): Config } const configManager = new ConfigManager(); export default configManager; ``` -------------------------------- ### Build and Run Vane from Source Source: https://github.com/itzcrazykns/vane/blob/master/README.md Builds the Vane Docker image and runs the container. After the containers are built, Vane can be started directly from Docker without opening a terminal. ```bash docker build -t vane . docker run -d -p 3000:3000 -v vane-data:/home/vane/data --name vane vane ``` -------------------------------- ### embedText usage examples Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/base-model-classes.md Usage examples for the embedText method. The basic example embeds two strings; the advanced example embeds a single query string and takes the first vector for a semantic store query, referencing uploads.md for more details. ```ts // basic const vectors = await embedding.embedText(['What is Vane?', 'search engine']); // advanced — semantic store query (see uploads.md) const queryVector = (await embedding.embedText([query]))[0]; ``` -------------------------------- ### getActiveProviders usage example Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/model-registry.md Shows how to call getActiveProviders and handle providers that fail to load models. A failed provider appears with a chat model having key 'error'. ```typescript // basic — list what a client may use const registry = new ModelRegistry(); const providers = await registry.getActiveProviders(); const first = providers[0]; console.log(first.id, first.chatModels.map(m => m.key)); // error handling: a failed provider shows up as a chat model with key 'error' const broken = providers.filter(p => p.chatModels.some(m => m.key === 'error')); ``` -------------------------------- ### addProviderModel and removeProviderModel usage example Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/model-registry.md Shows how to add a custom chat model to a provider and then remove it by key. ```typescript // basic — add a custom model key to a provider await registry.addProviderModel(providerId, 'chat', { name: 'My model', key: 'my-model' }); await registry.removeProviderModel(providerId, 'chat', 'my-model'); ``` -------------------------------- ### POST /api/search request body example Source: https://github.com/itzcrazykns/vane/blob/master/docs/API/SEARCH.md Request body for POST /api/search. The providerId must be a valid UUID from /api/providers; the example uses a sample UUID. The stream field defaults to false. ```json { "chatModel": { "providerId": "550e8400-e29b-41d4-a716-446655440000", "key": "gpt-4o-mini" }, "embeddingModel": { "providerId": "550e8400-e29b-41d4-a716-446655440000", "key": "text-embedding-3-large" }, "optimizationMode": "speed", "sources": ["web"], "query": "What is Vane", "history": [ ["human", "Hi, how are you?"], ["assistant", "I am doing well, how can I help you today?"] ], "systemInstructions": "Focus on providing technical details about Vane's architecture.", "stream": false } ``` -------------------------------- ### Clone Vane Repository Source: https://github.com/itzcrazykns/vane/blob/master/README.md Clones the Vane repository for building from source. Requires Docker to be installed and running. ```bash git clone https://github.com/ItzCrazyKns/Vane.git ``` -------------------------------- ### Basic object generation with generateObject Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/openai-provider.md Shows how to call generateObject with a schema and messages to get a structured object. The response is typed as the schema type. ```typescript // basic — generate object const res = await llm.generateObject({ schema: mySchema, messages: [{ role: 'user', content: 'What is the capital of France?' }], }); ``` -------------------------------- ### Basic usage of searchVideos Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/classifier-suggestions-media.md Basic usage example for the searchVideos function, showing a POST to /api/videos with a chatHistory and query. The function returns a Promise. ```ts // basic (POST /api/videos) const videos = await searchVideos({ chatHistory, query: 'how to use Next.js' }, llm); ``` -------------------------------- ### Basic usage of getSuggestions and getApproxLocation Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/utilities.md Basic usage example for the client HTTP actions: calls getSuggestions with a chat history array and getApproxLocation, destructuring the returned location fields. ```ts // basic const suggestions = await getSuggestions([['human', 'What is Vane?']]); const { latitude, longitude, city } = await getApproxLocation(); ``` -------------------------------- ### loadChatModel and loadEmbeddingModel usage example Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/model-registry.md Demonstrates loading both a chat and embedding model in parallel and handling errors from invalid provider IDs or model keys. ```typescript // basic — POST /api/search loads both models in parallel const registry = new ModelRegistry(); const [llm, embedding] = await Promise.all([ registry.loadChatModel(body.chatModel.providerId, body.chatModel.key), registry.loadEmbeddingModel(body.embeddingModel.providerId, body.embeddingModel.key), ]); // error handling — surface unmapped ids/keys try { await registry.loadChatModel(providerId, modelKey); } catch (e) { console.error('model load failed:', (e as Error).message); } ``` -------------------------------- ### Use `classify` with basic and error-handling examples Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/classifier-suggestions-media.md Shows basic usage and error handling for `classify`. On provider-level 'Error parsing response from ...' errors, fall back to `skipSearch=false` defaults. ```ts // basic const output = await classify({ llm, enabledSources: ['web'], query, chatHistory }); if (output.classification.skipSearch) { /* answer without research */ } // error handling try { await classify({ llm, enabledSources: ['web'], query, chatHistory }); } catch (e) { // provider-level 'Error parsing response from ...' — fall back to // skipSearch=false defaults } ``` -------------------------------- ### Scraper.scrape usage examples Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/searxng-scraper.md Shows basic usage of Scraper.scrape to fetch and extract content, and error handling with .catch() to handle failures gracefully. ```typescript // basic — scrape + extract (as used by grep in quality mode / scrape_url) const page = await Scraper.scrape('https://example.com/article'); console.log(page.title); // error handling — callers use .catch(); failure page is a structured fallback const data = await Scraper.scrape(badUrl).catch((err) => { console.error('scrape failed', err); return { title: 'error', content: 'unavailable' }; }); ``` -------------------------------- ### Update Vane with Docker pre-built image (latest) Source: https://github.com/itzcrazykns/vane/blob/master/docs/installation/UPDATING.md Pulls the latest Vane image, stops and removes the existing container, and starts a new one with the same volume to preserve settings. After running, verify at http://localhost:3000. ```bash docker pull itzcrazykns1337/vane:latest docker stop vane docker rm vane docker run -d -p 3000:3000 -v vane-data:/home/vane/data --name vane itzcrazykns1337/vane:latest ``` -------------------------------- ### APISearchAgent.searchAsync Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/search-agent.md Documentation for the APISearchAgent.searchAsync method, including its signature, parameters, behavior, emitted events, and an example usage. ```APIDOC ## APISearchAgent.searchAsync ### Description Performs an asynchronous search using the APISearchAgent. It does not persist to the database and generates its own session for the researcher. It emits search results, research completion, response chunks, and an end event. ### Method searchAsync ### Signature ```ts async searchAsync(session: SessionManager, input: SearchAgentInput): Promise ``` ### Parameters - **session** (SessionManager) - Required - The session manager used for event subscription and session creation. - **input** (SearchAgentInput) - Required - The input object containing chat history, follow-up query, config, chatId, and messageId. ### Behavior - `chatId` and `messageId` from `input` are ignored for persistence; the caller passes `crypto.randomUUID()` for both. - The researcher runs with its own session created via `SessionManager.createSession()`, which the top-level session never sees. - Widget failures are caught per-widget inside `executeAll`; additionally, the whole widget promise is `.catch(...)` returning `[]`. ### Events Emitted - `{ type: 'searchResults', data: }` - Emitted when search results are available. - `{ type: 'response', data: }` - Emitted for each writer chunk. - `'researchComplete'` - Emitted when research is complete. - `'end'` - Emitted when the operation finishes. ### Example Usage ```ts // basic — non-streaming consumer (POST /api/search, stream: false) const agent = new APISearchAgent(); agent.searchAsync(session, { chatHistory, followUp: body.query, config, chatId: crypto.randomUUID(), messageId: crypto.randomUUID() }); let message = ''; let sources: any[] = []; session.subscribe((event, data) => { if (event === 'data' && data.type === 'response') message += data.data; if (event === 'data' && data.type === 'searchResults') sources = data.data; if (event === 'end') resolve(Response.json({ message, sources }, { status: 200 })); if (event === 'error') reject(Response.json({ message: 'Search error', error: data }, { status: 500 })); }); ``` ``` -------------------------------- ### OpenAIProvider Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/openai-provider.md The OpenAIProvider class is the main entry point for interacting with OpenAI-compatible APIs. It provides methods to get default models, load chat and embedding models, and validate configuration. ```APIDOC ## OpenAIProvider ### Description The OpenAIProvider class is the main entry point for interacting with OpenAI-compatible APIs. It provides methods to get default models, load chat and embedding models, and validate configuration. ### Constructor - **id** (string) - The provider ID. - **name** (string) - The provider name. - **config** (OpenAIConfig) - Configuration object with `apiKey` and `baseURL`. ### Methods #### getDefaultModels() - **Description**: Returns the static default chat and embedding model lists if the baseURL is `https://api.openai.com/v1`; otherwise returns empty lists. - **Returns**: Promise #### getModelList() - **Description**: Returns the default models plus any persisted custom chat and embedding models. - **Returns**: Promise #### loadChatModel(key) - **Description**: Loads a chat model by key. Validates the key exists and returns a new `OpenAILLM` instance. - **Parameters**: - **key** (string) - The model key. - **Returns**: Promise> - **Throws**: Error if the model key is invalid. #### loadEmbeddingModel(key) - **Description**: Loads an embedding model by key. Validates the key exists and returns a new `OpenAIEmbedding` instance. - **Parameters**: - **key** (string) - The model key. - **Returns**: Promise> - **Throws**: Error if the model key is invalid. #### parseAndValidate(raw) - **Description**: Validates and coerces the raw configuration object. Requires `apiKey` and `baseURL`. - **Parameters**: - **raw** (any) - The raw configuration object. - **Returns**: OpenAIConfig - **Throws**: Error if the configuration is invalid. #### getProviderConfigFields() - **Description**: Returns the configuration fields for the provider. - **Returns**: UIConfigField[] #### getProviderMetadata() - **Description**: Returns the provider metadata. - **Returns**: ProviderMetadata ### Configuration Fields - **apiKey** (password) - Required - The API key. Environment variable: `OPENAI_API_KEY`. - **baseURL** (string) - Required - The base URL. Default: `https://api.openai.com/v1`. Environment variable: `OPENAI_BASE_URL`. ### Example ```ts import { createProviderInstance } from '@/lib/models/base/provider'; import OpenAIProvider from '@/lib/models/providers/openai'; const provider = createProviderInstance(OpenAIProvider, id, 'OpenAI', { apiKey: 'sk-...', baseURL: 'https://api.openai.com/v1', }); const llm = await provider.loadChatModel('gpt-4o-mini'); ``` ### Error Handling - Invalid model key: `'Error Loading OpenAI Chat Model. Invalid Model Selected'` ``` -------------------------------- ### Update Vane with Docker pre-built image (slim-latest) Source: https://github.com/itzcrazykns/vane/blob/master/docs/installation/UPDATING.md Updates to the slim variant of Vane, which requires the SEARXNG_API_URL environment variable. Stops and removes the old container, then starts a new one with the same volume. ```bash docker pull itzcrazykns1337/vane:slim-latest docker stop vane docker rm vane docker run -d -p 3000:3000 -e SEARXNG_API_URL=http://your-searxng-url:8080 -v vane-data:/home/vane/data --name vane itzcrazykns1337/vane:slim-latest ``` -------------------------------- ### Usage examples for embedText and embedChunks Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/openai-provider.md Shows basic usage of embedText with a simple string array and advanced usage of embedChunks with a Chunk object. Both methods return a promise of number arrays (vectors). ```ts // basic const vectors = await emb.embedText(['document text']); // advanced — embed chunks straight from the Chunk type const vectors = await emb.embedChunks([{ content: '...', metadata: {} }]); ``` -------------------------------- ### OllamaLLM.constructor Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/ollama-provider.md Initializes a new OllamaLLM instance with the provided configuration, setting up the Ollama client with the base URL. ```APIDOC ## [CONSTRUCTOR] OllamaLLM.constructor ### Description Creates a new OllamaLLM instance, initializing the internal Ollama client with the specified base URL (defaults to http://localhost:11434). ### Method CONSTRUCTOR ### Endpoint OllamaLLM.constructor(config: OllamaConfig) ### Parameters #### Constructor Parameters - **config** (OllamaConfig) - Required - Configuration object for the Ollama provider. - **baseURL** (string) - Required - The base URL of the Ollama server. - **model** (string) - Required - The model name to use. - **options** (GenerateOptions) - Optional - Additional generation options. ### Request Example { "baseURL": "http://localhost:11434", "model": "llama3.1" } ### Response #### Success Response (200) No return value. The instance is initialized with the Ollama client. #### Response Example {} ``` -------------------------------- ### Create provider instance and load chat model Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/openai-provider.md Shows how to create an OpenAIProvider instance via the factory and load a chat model. Includes error handling for an invalid model key, which throws 'Error Loading OpenAI Chat Model. Invalid Model Selected'. ```typescript // basic — create an instance through the factory import { createProviderInstance } from '@/lib/models/base/provider'; import OpenAIProvider from '@/lib/models/providers/openai'; const provider = createProviderInstance(OpenAIProvider, id, 'OpenAI', { apiKey: 'sk-...', baseURL: 'https://api.openai.com/v1', }); const llm = await provider.loadChatModel('gpt-4o-mini'); // error handling — invalid model key try { await provider.loadChatModel('does-not-exist'); } catch (e) { // 'Error Loading OpenAI Chat Model. Invalid Model Selected' } ``` -------------------------------- ### Execute widgets and handle errors Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/widgets.md Demonstrates basic usage of executeAll with a sample input and shows how to filter for widget errors. executeAll never throws; errors appear in the output data. ```ts // basic — run every applicable widget const outputs = await WidgetExecutorDefault.executeAll({ classification, chatHistory, followUp: 'What is the weather in Berlin?', llm, }); // outputs -> [{ type: 'weatherWidget', llmContext, data }] // error handling — executeAll never throws; widget errors surface in the output data const failed = outputs.filter(o => o.data && (o.data as any).error); ``` -------------------------------- ### OllamaLLM class definition with OllamaConfig and reasoningModels Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/ollama-provider.md Defines the OllamaConfig type, a list of reasoning models, and the OllamaLLM class extending BaseLLM. The constructor initializes an Ollama client with the provided baseURL or defaults to 'http://localhost:11434'. Method signatures are shown but implementations are omitted. ```ts type OllamaConfig = { baseURL: string; model: string; options?: GenerateOptions; }; const reasoningModels = [ 'gpt-oss', 'deepseek-r1', 'qwen3', 'deepseek-v3.1', 'magistral', 'nemotron-3', 'nemotron-cascade-2', 'glm-4.7-flash', ]; class OllamaLLM extends BaseLLM { ollamaClient: Ollama; constructor(protected config: OllamaConfig) { super(config); this.ollamaClient = new Ollama({ host: this.config.baseURL || 'http://localhost:11434' }); } convertToOllamaMessages(messages: Message[]): OllamaMessage[] { ... } async generateText(input: GenerateTextInput): Promise { ... } async *streamText(input: GenerateTextInput): AsyncGenerator { ... } async generateObject(input: GenerateObjectInput): Promise { ... } async *streamObject(input: GenerateObjectInput): AsyncGenerator { ... } } ``` -------------------------------- ### GET /api/providers Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/endpoints.md Retrieves the list of active providers and their models. ```APIDOC ## GET /api/providers ### Description Returns all active providers with their chat and embedding models. ### Method GET ### Endpoint /api/providers ### Response #### Success Response (200) - **providers** (array) - Array of provider objects with id, name, chatModels, and embeddingModels. #### Response Example { "providers": [ { "id": "uuid", "name": "OpenAI", "chatModels": [ { "name": "GPT 4 omni mini", "key": "gpt-4o-mini" } ], "embeddingModels": [ { "name": "Text Embedding 3 Small", "key": "text-embedding-3-small" } ] } ] } #### Error Response (500) - **message** (string) - Error message ``` -------------------------------- ### GET /api/chats Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/endpoints.md Retrieves a list of all chats, with the newest first. ```APIDOC ## GET `/api/chats` ### Description Retrieves a list of all chats, with the newest first. ### Method GET ### Endpoint /api/chats ### Response #### Success Response (200) - **chats** (ChatRow[]) - Array of chat records, reversed (newest-first). Each row contains id, title, createdAt, sources, files. #### Response Example { "chats": [] } #### Error Response (500) Internal server error. ``` -------------------------------- ### OllamaProvider Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/ollama-provider.md Documentation for the OllamaProvider class, including its configuration, methods, and usage examples. ```APIDOC ## OllamaProvider ### Description OllamaProvider is Vane's local-first provider that communicates with the Ollama HTTP API. It converts zod schemas to JSON-schema `format` for structured output, synthesizes tool-call IDs locally, forwards thinking tokens, and disables thinking for known reasoning models. ### Constructor `new OllamaProvider(id: string, name: string, config: OllamaConfig)` ### Configuration - **baseURL** (string) - Required - The base URL of the Ollama server. ### Methods #### `getDefaultModels()` - **Description**: Fetches the list of available models from the Ollama API. - **HTTP Request**: `GET {baseURL}/api/tags` - **Returns**: `Promise` - Maps each entry to `{ name: m.name, key: m.model }` in both `chat` and `embedding` lists. - **Errors**: Throws `'Error connecting to Ollama API. Please ensure the base URL is correct and the Ollama server is running.'` on network errors (TypeError). #### `getModelList()` - **Description**: Returns the default models plus any custom persisted models. - **Returns**: `Promise` #### `loadChatModel(key: string)` - **Description**: Loads a chat model by key. - **Parameters**: - `key` (string) - Required - The model key. - **Returns**: `Promise>` - Returns an `OllamaLLM` instance. - **Errors**: Throws `'Error Loading Ollama Chat Model. Invalid Model Selected'` if the key is invalid. #### `loadEmbeddingModel(key: string)` - **Description**: Loads an embedding model by key. - **Parameters**: - `key` (string) - Required - The model key. - **Returns**: `Promise>` - Returns an `OllamaEmbedding` instance. - **Errors**: Throws `'Error Loading Ollama Embedding Model. Invalid Model Selected.'` if the key is invalid. #### `parseAndValidate(raw: any)` - **Description**: Validates and coerces the raw config. - **Parameters**: - `raw` (any) - Required - The raw config object. - **Returns**: `OllamaConfig` - The validated config. - **Errors**: Throws `'Invalid config provided. Base URL must be provided'` if the config is invalid. #### `getProviderConfigFields()` - **Description**: Returns the UI configuration fields for the provider. - **Returns**: `UIConfigField[]` - Contains a single string field for `baseURL` with placeholder `http://localhost:11434` (or `http://host.docker.internal:11434` in Docker), env `OLLAMA_BASE_URL`, and scope `server`. #### `getProviderMetadata()` - **Description**: Returns provider metadata. - **Returns**: `ProviderMetadata` - `{ key: 'ollama', name: 'Ollama' }` ### Example Usage ```ts import { createProviderInstance } from '@/lib/models/base/provider'; const provider = createProviderInstance(OllamaProvider, id, 'Ollama', { baseURL: 'http://localhost:11434', }); const llm = await provider.loadChatModel('llama3.1:latest'); try { await provider.getDefaultModels(); } catch (e) { // 'Error connecting to Ollama API. Please ensure the base URL is correct...' } ``` ``` -------------------------------- ### GET /api/chats/[id] Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/endpoints.md Fetches a specific chat by its ID, along with its messages. ```APIDOC ## GET `/api/chats/[id]` ### Description Fetches a specific chat by its ID, along with its messages. ### Method GET ### Endpoint /api/chats/[id] ### Parameters #### Path Parameters - **id** (string) - Required - The ID of the chat to retrieve. ### Response #### Success Response (200) - **chat** (ChatRow) - The chat record. - **messages** (MessageRow[]) - Array of message records, each containing messageId, chatId, backendId, query, createdAt, responseBlocks (Block[]), status. #### Response Example { "chat": {}, "messages": [] } #### Error Response (404) { "message": "Chat not found" } #### Error Response (500) Internal server error. ``` -------------------------------- ### Run Vane with Own SearxNG Instance Source: https://github.com/itzcrazykns/vane/blob/master/README.md Runs the slim Vane image with an external SearxNG instance. Requires your SearxNG to have JSON format enabled and Wolfram Alpha search engine enabled. Replace the placeholder URL with your actual SearxNG URL. ```bash docker run -d -p 3000:3000 -e SEARXNG_API_URL=http://your-searxng-url:8080 -v vane-data:/home/vane/data --name vane itzcrazykns1337/vane:slim-latest ``` -------------------------------- ### getCurrentConfig and getUIConfigSections together Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/config-manager.md Usage of getCurrentConfig and getUIConfigSections together to serve a GET /api/config endpoint. ```typescript // both together — serves GET /api/config const values = configManager.getCurrentConfig(); const fields = configManager.getUIConfigSections(); return NextResponse.json({ values, fields }); ``` -------------------------------- ### Basic usage and error handling for OllamaProvider Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/ollama-provider.md Shows basic usage of the Ollama provider: creating an instance with a base URL and loading a chat model. Also demonstrates error handling when the Ollama server is offline, which surfaces as a model-list fetch error. ```ts // basic import { createProviderInstance } from '@/lib/models/base/provider'; const provider = createProviderInstance(OllamaProvider, id, 'Ollama', { baseURL: 'http://localhost:11434', }); const llm = await provider.loadChatModel('llama3.1:latest'); // error handling — offline server surfaces as a model-list fetch error try { await provider.getDefaultModels(); } catch (e) { // 'Error connecting to Ollama API. Please ensure the base URL is correct...' } ``` -------------------------------- ### Configure Ollama on Linux with OLLAMA_HOST Source: https://github.com/itzcrazykns/vane/blob/master/README.md For Linux users, add the OLLAMA_HOST environment variable to /etc/systemd/system/ollama.service to expose Ollama to the network, then reload systemd and restart Ollama. Change the port number if using a different one. ```ini Environment="OLLAMA_HOST=0.0.0.0:11434" ``` ```bash systemctl daemon-reload ``` ```bash systemctl restart ollama ``` -------------------------------- ### Import db and schema Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/database.md Imports the default `db` instance and the `chats` and `messages` tables from the schema module. ```typescript import db from '@/lib/db'; // src/lib/db/index.ts (default export) import { chats, messages } from '@/lib/db/schema'; // src/lib/db/schema.ts ``` -------------------------------- ### Client HTTP actions: getSuggestions and getApproxLocation Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/utilities.md Client HTTP action signatures. getSuggestions posts chat history to /api/suggestions and returns Promise from data.suggestions; getApproxLocation fetches from https://free.freeipapi.com/api/json and returns Promise<{ latitude: number; longitude: number; city: string }>. ```ts export const getSuggestions = async (chatHistory: [string, string][]) => { ... }; export const getApproxLocation = async () => { ... }; ``` -------------------------------- ### Client config helpers Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/utilities.md Client-side configuration helpers that read from localStorage. ```APIDOC ## getTheme() ### Description Reads the theme configuration from localStorage with a default of 'dark'. ### Method N/A (client-side helper) ### Endpoint N/A ### Parameters None ### Returns - **string** - The theme value ('dark' by default) ### Example ```ts const theme = getTheme(); ``` ``` ```APIDOC ## getAutoMediaSearch() ### Description Reads the autoMediaSearch configuration from localStorage and returns a boolean. Defaults to true. ### Method N/A (client-side helper) ### Endpoint N/A ### Parameters None ### Returns - **boolean** - true if autoMediaSearch is enabled (default true) ### Example ```ts const autoMediaSearch = getAutoMediaSearch(); ``` ``` -------------------------------- ### updateConfig basic and error handling Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/config-manager.md Basic usage of updateConfig to set a configuration value, and an error handling example showing validation before calling updateConfig. ```typescript // basic configManager.updateConfig('search.searxngURL', 'http://localhost:4000'); // error handling: value asserted by POST /api/config route if (!key || !value) throw new Error('Key and value are required.'); configManager.updateConfig(key, value); ``` -------------------------------- ### Import UploadManager and UploadStore Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/uploads.md Import the UploadManager and UploadStore classes from their respective modules. The comments indicate the file paths and class line numbers. ```ts import UploadManager from '@/lib/uploads/manager'; // manager.ts, class line 32 import UploadStore from '@/lib/uploads/store'; // store.ts, class line 19 ``` -------------------------------- ### List chats newest-first Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/database.md Basic usage for listing chats newest-first in GET /api/chats. Uses db.query.chats.findMany() and reverses the result before returning a JSON response. ```typescript let all = await db.query.chats.findMany(); all = all.reverse(); return Response.json({ chats: all }, { status: 200 }); ``` -------------------------------- ### Basic TransformerEmbedding usage Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/other-providers.md Basic usage example: instantiate TransformerEmbedding with a local model and embed a text array. The embedText method returns a promise of number[][]. ```ts // basic — embed with a local model const emb = new TransformerEmbedding({ model: 'Xenova/all-MiniLM-L6-v2' }); const vectors = await emb.embedText(['hello world']); ``` -------------------------------- ### GET /api/config Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/endpoints.md Returns both the persisted configuration values and the UI field schema. The model provider values are merged with live model lists from a fresh ModelRegistry. ```APIDOC ## GET `/api/config` ### Description Returns both the persisted configuration values and the UI field schema. The model provider values are merged with live model lists from a fresh ModelRegistry. ### Method GET ### Endpoint /api/config ### Response #### Success Response (200) - **values** (Config) - Persisted configuration values. - **fields** (UIConfigSections) - UI field schema. #### Response Example { "values": {}, "fields": {} } #### Error Response (500) Internal server error. ``` -------------------------------- ### Execute stockWidget to compare two stocks Source: https://github.com/itzcrazykns/vane/blob/master/_autodocs/api-reference/widgets.md Shows how to execute the stockWidget with a follow-up to compare two stocks. The output contains comparisonData with chart data for each compared stock. The code logs the name and chart keys for each comparison entry. ```typescript // advanced — compare two stocks const output = await stockWidget.execute({ classification, chatHistory, followUp: 'Compare Apple and Microsoft stock', llm, }); if (output && output.data) { (output.data as any).comparisonData?.forEach(c => console.log(c.name, Object.keys(c.chartData))); } ```