@exulu/backend 1.66.0 → 1.68.0

package/dist/index.d.ts

@@ -10,6 +10,29 @@ import { z } from 'zod';
 import { Tiktoken } from 'tiktoken/lite';
 import models from 'tiktoken/model_to_encoding.json';
 
+interface Project {
+    id: string;
+    name: string;
+    description: string;
+    custom_instructions: string;
+    rights_mode?: 'private' | 'users' | 'roles' | 'public';
+    created_by?: string;
+    project_items?: string[];
+    RBAC?: {
+        type?: string;
+        users?: Array<{
+            id: string;
+            rights: 'read' | 'write';
+        }>;
+        roles?: Array<{
+            id: string;
+            rights: 'read' | 'write';
+        }>;
+    };
+    createdAt?: string;
+    updatedAt?: string;
+}
+
 type ApiKeyScopeMode = "admin" | "agents";
 type User = {
     id: number;
@@ -22,10 +45,20 @@ type User = {
     personal_system_prompt?: string;
     super_admin?: boolean;
     favourite_agents?: string[];
+    /** Per-user favourited data items — global ids ("<contextId>/<itemId>"). */
+    favourite_items?: string[];
+    /** Per-user recently viewed data items — global ids, most-recent first. */
+    recently_viewed_items?: string[];
     scope_mode?: ApiKeyScopeMode;
     agent_ids?: string[];
     role: UserRole;
     team?: ExuluTeam;
+    /**
+     * Optional attribution target (mainly for API keys, type "api"): hydrated
+     * from the `project` uuid column at auth time so buildTags can emit
+     * project_id_ for API-triggered requests.
+     */
+    project?: Project;
     /**
      * Live LiteLLM budget snapshot for the user, attached at context time when
      * the "show user budget in chat" setting is on. Not a Postgres column.
@@ -184,7 +217,47 @@ interface Item {
     [key: string]: any;
 }
 
-declare const PUBLIC_TOOL_TYPES: readonly ["function", "web_search", "skill"];
+/**
+ * OAuth 2.0 configuration for an {@link ExuluTool}. When a tool is constructed
+ * with an `oauth` property, Exulu wraps its `execute` so it only runs when a
+ * valid access token exists for the calling (toolId, userId) pair. When no
+ * valid token exists the tool short-circuits and returns an authorization URL
+ * the agent can show the user; the generic /oauth/callback route completes the
+ * flow and persists the tokens.
+ *
+ * Only the standard authorization-code grant is supported. All values are
+ * declared in code (source them from env vars or however you like) — none of
+ * them are exposed as admin-configurable tool config.
+ */
+type ExuluOauthConfig = {
+    /** The provider's authorization endpoint, e.g. https://app.hubspot.com/oauth/authorize */
+    authorizationUrl: string;
+    /** The provider's token endpoint, e.g. https://api.hubapi.com/oauth/v1/token */
+    tokenUrl: string;
+    clientId: string;
+    /** Never leaves the server: used only in the server-side token exchange. */
+    clientSecret: string;
+    /** Scopes to request; joined with spaces in the authorization URL. */
+    scopes: string[];
+    /** PKCE (S256). Defaults to true; set false for providers that reject PKCE. */
+    pkce?: boolean;
+    /**
+     * Extra query params appended to the authorization URL, e.g.
+     * `{ access_type: "offline", prompt: "consent" }` to make Google return a
+     * refresh token.
+     */
+    extraAuthParams?: Record<string, string>;
+};
+/** The oauth context injected into an oauth-enabled tool's execute inputs. */
+type ExuluOauthToolContext = {
+    accessToken: string;
+    /** null when the provider did not report an expiry. */
+    expiresAt: Date | null;
+    /** Space-joined scopes the token was granted, when reported by the provider. */
+    scopes: string | null;
+};
+
+declare const PUBLIC_TOOL_TYPES: readonly ["function", "web_search", "skill", "context"];
 type PublicToolType = (typeof PUBLIC_TOOL_TYPES)[number];
 type ToolType = PublicToolType | "agent" | "context";
 declare class ExuluTool {
@@ -196,13 +269,14 @@ declare class ExuluTool {
     type: ToolType;
     tool: Tool;
     needsApproval: boolean;
+    oauth?: ExuluOauthConfig;
     config: {
         name: string;
         description: string;
         type: "boolean" | "string" | "number" | "variable";
         default?: string | boolean | number;
     }[];
-    constructor({ id, name, description, category, inputSchema, type, execute, config, needsApproval, }: {
+    constructor({ id, name, description, category, inputSchema, type, execute, config, needsApproval, oauth, }: {
         id: string;
         name: string;
         description: string;
@@ -216,6 +290,7 @@ declare class ExuluTool {
             default?: string | boolean | number;
         }[];
         needsApproval?: boolean;
+        oauth?: ExuluOauthConfig;
         execute: (inputs: any, options?: any) => Promise<{
             result?: string;
             job?: string;
@@ -308,6 +383,50 @@ type ExuluContextProcessor = {
     };
 };
 
+/**
+ * Chunking is now an ExuluContext concern (it used to live on the removed
+ * ExuluEmbedder class). A context may supply its own `chunker` to control how
+ * an item is split into embeddable chunks; if it doesn't, `defaultChunker`
+ * runs. Embedding generation itself goes through LiteLLM via resolveEmbedder —
+ * the chunker only produces the text segments.
+ */
+type ChunkerResponse = {
+    item: Item & {
+        id: string;
+    };
+    chunks: {
+        content: string;
+        index: number;
+        metadata?: Record<string, unknown>;
+    }[];
+};
+/**
+ * A chunker takes a (fully-hydrated) item and a target max chunk size and
+ * returns the ordered text chunks to embed. `utils.storage` is provided for
+ * chunkers that need to read file contents from object storage.
+ *
+ * Note: unlike the old ExuluEmbedder.chunker, there is no `settings` argument —
+ * the per-context `embedder_settings` config layer was removed. Chunkers that
+ * need configuration should close over it in code.
+ */
+type ChunkerOperation = (item: Item & {
+    id: string;
+}, maxChunkSize: number, utils: {
+    storage: ExuluStorage;
+}) => Promise<ChunkerResponse>;
+/**
+ * Built-in chunker used when a context configures an embedder model but does
+ * not provide its own `chunker`. It runs the standard SentenceChunker (also
+ * exposed as ExuluChunkers.sentence) over the item's primary text — preferring
+ * a `content` field, then `description`, combined with the `name` — so a
+ * context "just works" from a model name alone. `maxChunkSize` is used as the
+ * per-chunk token budget. Contexts with structured or file-backed content
+ * should supply a custom ChunkerOperation.
+ */
+declare const defaultChunker: ChunkerOperation;
+
+type ExuluRightsMode = "private" | "users" | "roles" | "teams" | "public";
+
 type STATISTICS_TYPE = "CONTEXT_RETRIEVE" | "SOURCE_UPDATE" | "EMBEDDER_UPSERT" | "EMBEDDER_GENERATE" | "EMBEDDER_DELETE" | "WORKFLOW_RUN" | "CONTEXT_UPSERT" | "TOOL_CALL" | "AGENT_RUN";
 declare const STATISTICS_TYPE_ENUM: {
     CONTEXT_RETRIEVE: string;
@@ -331,67 +450,6 @@ type ExuluStatistic = {
 };
 type STATISTICS_LABELS = "tool" | "agent" | "flow" | "api" | "claude-code" | "user" | "processor";
 
-type ExuluEmbedderConfig = {
-    name: string;
-    description: string;
-    default?: string;
-};
-type VectorGenerationResponse = Promise<{
-    id: string;
-    chunks: {
-        content: string;
-        index: number;
-        metadata: Record<string, string>;
-        vector: number[];
-    }[];
-}>;
-type VectorGenerateOperation = (inputs: ChunkerResponse, settings: Record<string, string>) => VectorGenerationResponse;
-type ChunkerOperation = (item: Item & {
-    id: string;
-}, maxChunkSize: number, utils: {
-    storage: ExuluStorage;
-}, config: Record<string, string>) => Promise<ChunkerResponse>;
-type ChunkerResponse = {
-    item: Item & {
-        id: string;
-    };
-    chunks: {
-        content: string;
-        index: number;
-    }[];
-};
-declare class ExuluEmbedder {
-    id: string;
-    name: string;
-    slug: string;
-    queue?: Promise<ExuluQueueConfig>;
-    private generateEmbeddings;
-    description: string;
-    vectorDimensions: number;
-    config?: ExuluEmbedderConfig[];
-    maxChunkSize: number;
-    _chunker: ChunkerOperation;
-    constructor({ id, name, description, generateEmbeddings, queue, vectorDimensions, maxChunkSize, chunker, config, }: {
-        id: string;
-        name: string;
-        description: string;
-        config?: ExuluEmbedderConfig[];
-        generateEmbeddings: VectorGenerateOperation;
-        chunker: ChunkerOperation;
-        queue?: Promise<ExuluQueueConfig>;
-        vectorDimensions: number;
-        maxChunkSize: number;
-    });
-    chunker: (context: string, item: Item & {
-        id: string;
-    }, maxChunkSize: number, config: ExuluConfig) => Promise<ChunkerResponse>;
-    private hydrateEmbedderConfig;
-    generateFromQuery(context: string, query: string, statistics?: ExuluStatisticParams, user?: number, role?: string): VectorGenerationResponse;
-    generateFromDocument(context: string, input: Item, config: ExuluConfig, statistics?: ExuluStatisticParams, user?: number, role?: string): VectorGenerationResponse;
-}
-
-type ExuluRightsMode = "private" | "users" | "roles" | "public";
-
 /**
  * Base operator type with comparison operations
  */
@@ -475,6 +533,68 @@ declare const VectorMethodEnum: {
 };
 type VectorMethod = (typeof VectorMethodEnum)[keyof typeof VectorMethodEnum];
 
+/**
+ * A single entity type a context extracts (e.g. { name: "Person", description: "..." }).
+ * Declared in code on the ExuluContext `entities.types`, and/or in the DB via the
+ * `entity_type_settings` admin table. The effective set is the union of both.
+ */
+type EntityTypeDefinition = {
+    name: string;
+    description: string;
+};
+/**
+ * The opt-in entity-layer configuration on an ExuluContext. When this block is
+ * absent (and no admin types exist for the context) the entity layer is OFF and
+ * retrieval/ingestion behave exactly as before.
+ */
+type ExuluEntitiesConfig = {
+    /** Entity types declared in code. Merged (union) with admin-declared types. */
+    types?: EntityTypeDefinition[];
+    /** models.id used for extraction. Resolved via resolveModel(). Falls back to a platform default. */
+    model?: string;
+    /** Weight of the shared-entity boost term in retrieval ranking. Default 0.3. */
+    boostWeight?: number;
+    /** Drop mentions below this extractor confidence (0..1). Default 0.5. */
+    confidenceThreshold?: number;
+    /** Target language for canonical entity names. Default "english". */
+    canonicalLanguage?: string;
+};
+/** A related entity surfaced via derived co-occurrence. */
+type RelatedEntity = {
+    id: string;
+    name: string;
+    type: string;
+    /** Relatedness weight (normalized Jaccard over shared documents). */
+    weight: number;
+};
+/** Entity intelligence for one query entity, returned to the calling agent. */
+type QueryEntityInsight = {
+    id: string;
+    type: string;
+    name: string;
+    /** How many of the returned chunks mention this entity. */
+    matchedInResults: number;
+    /** Distinct documents in the context mentioning this entity (maintained counter). */
+    relatedDocCount: number;
+    /** Top-K co-occurring entities, weighted. */
+    relatedEntities: RelatedEntity[];
+};
+type EntityInsights = {
+    queryEntities: QueryEntityInsight[];
+};
+/** Caller-supplied entity filter for agent-driven exploration. */
+type EntityFilter = {
+    /** Resolve directly by entity id. */
+    entityIds?: string[];
+    /** Or resolve by (type, name) — name is normalized to a canonical key. */
+    entities?: {
+        type: string;
+        name: string;
+    }[];
+    /** "any" (default): chunk mentions at least one. "all": chunk mentions all. */
+    mode?: "any" | "all";
+};
+
 type VectorSearchChunkResult = {
     chunk_content: string;
     chunk_index: number;
@@ -491,12 +611,30 @@ type VectorSearchChunkResult = {
     chunk_cosine_distance?: number;
     chunk_fts_rank?: number;
     chunk_hybrid_score?: number;
+    /** Entities mentioned in this chunk (present only when the entity layer is on). */
+    chunk_entities?: {
+        id: string;
+        name: string;
+        type: string;
+    }[];
     context?: {
         name: string;
         id: string;
     };
 };
 
+/**
+ * A context's embedder is now just a reference to a LiteLLM embedding model
+ * (plus an optional queue), not an ExuluEmbedder instance. Embedding generation
+ * goes through resolveEmbedder; chunking is configured separately via the
+ * context's `chunker` (or the built-in default chunker).
+ */
+type ExuluContextEmbedder = {
+    /** LiteLLM model_name of the embedding model (declared in config.litellm.yaml). */
+    model: string;
+    /** When set, embedding generation runs as a background job on this queue. */
+    queue?: Promise<ExuluQueueConfig>;
+};
 type ExuluContextFieldDefinition = {
     name: string;
     type: ExuluFieldTypes;
@@ -539,14 +677,20 @@ declare class ExuluContext {
     fields: ExuluContextFieldDefinition[];
     processor?: ExuluContextProcessor;
     description: string;
-    embedder?: ExuluEmbedder;
+    embedder?: ExuluContextEmbedder;
+    /**
+     * Splits an item into embeddable chunks. Moved here from the removed
+     * ExuluEmbedder. When omitted, the built-in `defaultChunker` (SentenceChunker)
+     * is used so a context works from just an embedder model name.
+     */
+    chunker?: ChunkerOperation;
     queryRewriter?: (query: string) => Promise<string>;
     resultReranker?: (results: {
         chunk_content: string;
         chunk_index: number;
         chunk_id: string;
         chunk_source: string;
-        chunk_metadata: Record<string, string>;
+        chunk_metadata: Record<string, unknown>;
         chunk_created_at: string;
         chunk_updated_at: string;
         item_id: string;
@@ -557,7 +701,7 @@ declare class ExuluContext {
         chunk_index: number;
         chunk_id: string;
         chunk_source: string;
-        chunk_metadata: Record<string, string>;
+        chunk_metadata: Record<string, unknown>;
         chunk_created_at: string;
         chunk_updated_at: string;
         item_id: string;
@@ -579,13 +723,20 @@ declare class ExuluContext {
         };
         languages?: ("german" | "english")[];
     };
+    /**
+     * Optional entity-layer configuration. When present (or when an admin has
+     * configured entity types for this context) the graph/entity retrieval
+     * features are switched on. Absent → identical behavior to before.
+     */
+    entities?: ExuluEntitiesConfig;
     sources: ExuluContextSource[];
-    constructor({ id, name, description, embedder, processor, active, fields, queryRewriter, resultReranker, configuration, sources, }: {
+    constructor({ id, name, description, embedder, chunker, processor, active, fields, queryRewriter, resultReranker, configuration, entities, sources, }: {
         id: string;
         name: string;
         fields: ExuluContextFieldDefinition[];
         description: string;
-        embedder?: ExuluEmbedder;
+        embedder?: ExuluContextEmbedder;
+        chunker?: ChunkerOperation;
         sources: ExuluContextSource[];
         category?: string;
         active: boolean;
@@ -607,6 +758,7 @@ declare class ExuluContext {
                 hybrid?: number;
             };
         };
+        entities?: ExuluEntitiesConfig;
     });
     processField: (trigger: STATISTICS_LABELS, item: Item, exuluConfig: ExuluConfig, user?: number, role?: string) => Promise<{
         result: Item | undefined;
@@ -633,6 +785,7 @@ declare class ExuluContext {
             before?: number;
             after?: number;
         };
+        entityFilter?: EntityFilter;
     }) => Promise<{
         itemFilters: SearchFilters;
         chunkFilters: SearchFilters;
@@ -645,6 +798,7 @@ declare class ExuluContext {
             embedder: string;
         };
         chunks: VectorSearchChunkResult[];
+        entityInsights?: EntityInsights;
     }>;
     deleteAll: () => Promise<{
         count: number;
@@ -697,30 +851,46 @@ declare class ExuluContext {
             }>;
         };
     };
+    /**
+     * Entity-layer administration: backfill extraction over existing items,
+     * count stale items (for the admin "run backfill?" prompt), and purge a type.
+     */
+    entityLayer: {
+        /** Count items whose entities were extracted with an out-of-date type set. */
+        countStale: () => Promise<number>;
+        /**
+         * Full re-extraction over items. `onlyStale` (default true) limits to items
+         * whose type-set signature is out of date. Runs inline in batches with a
+         * safeguard cap; entity extraction (not re-embedding) is what runs here.
+         */
+        backfill: ({ onlyStale, limit, }?: {
+            onlyStale?: boolean;
+            limit?: number;
+        }) => Promise<{
+            processed: number;
+            skipped: number;
+        }>;
+        /**
+         * Extract + ingest entities for a SINGLE item — powers the item detail
+         * page's "Extract entities" test action. Returns the number of mentions
+         * found so the UI can report the result.
+         */
+        extractItem: (itemId: string) => Promise<{
+            extracted: number;
+        }>;
+        /** Detach all entities from a single item (drops links, prunes orphans). */
+        detachItem: (itemId: string) => Promise<{
+            detached: number;
+        }>;
+        /** Remove all entities (and their mentions via cascade) of a given type. */
+        purgeType: (typeName: string) => Promise<{
+            removed: number;
+        }>;
+    };
     createItemsTable: () => Promise<void>;
     createChunksTable: () => Promise<void>;
 }
 
-declare class ExuluReranker {
-    id: string;
-    name: string;
-    description: string;
-    execute: (params: {
-        query: string;
-        chunks: VectorSearchChunkResult[];
-    }) => Promise<VectorSearchChunkResult[]>;
-    constructor({ id, name, description, execute, }: {
-        id: string;
-        name: string;
-        description: string;
-        execute: (params: {
-            query: string;
-            chunks: VectorSearchChunkResult[];
-        }) => Promise<VectorSearchChunkResult[]>;
-    });
-    run(query: string, chunks: VectorSearchChunkResult[]): Promise<VectorSearchChunkResult[]>;
-}
-
 type ExuluAgentToolConfig = {
     id: string;
     type: string;
@@ -799,8 +969,8 @@ declare class ExuluProvider {
     constructor({ id, name, description, config, capabilities, type, maxContextLength, provider, queue, authenticationInformation, workflows, }: ExuluProviderParams);
     get providerName(): string;
     get modelName(): string;
-    tool: (instance: string, providers: ExuluProvider[], contexts: ExuluContext[], rerankers: ExuluReranker[]) => Promise<ExuluTool | null>;
-    generateSync: ({ prompt, req, user, session, inputMessages, approvedTools, currentTools, currentSkills, allExuluTools, statistics, toolConfigs, providerapikey, languageModel, contexts, rerankers, exuluConfig, agent, instructions, maxStepCount, onTokenUsage }: {
+    tool: (instance: string, providers: ExuluProvider[], contexts: ExuluContext[]) => Promise<ExuluTool | null>;
+    generateSync: ({ prompt, req, user, session, inputMessages, approvedTools, currentTools, currentSkills, allExuluTools, statistics, toolConfigs, providerapikey, languageModel, contexts, exuluConfig, agent, instructions, maxStepCount, onTokenUsage }: {
         prompt?: string;
         user?: User;
         maxStepCount?: number;
@@ -817,7 +987,6 @@ declare class ExuluProvider {
         providerapikey?: string | undefined;
         languageModel: LanguageModel;
         contexts?: ExuluContext[] | undefined;
-        rerankers?: ExuluReranker[] | undefined;
         exuluConfig?: ExuluConfig;
         instructions?: string;
         onTokenUsage?: (usage: {
@@ -833,7 +1002,7 @@ declare class ExuluProvider {
      * - Image files -> image parts (which ARE supported by Responses API)
      */
     private processFilePartsInMessages;
-    generateStream: ({ user, session, agent, message, previousMessages, currentTools, currentSkills, approvedTools, allExuluTools, toolConfigs, providerapikey, languageModel, contexts, rerankers, exuluConfig, instructions, req, maxStepCount }: {
+    generateStream: ({ user, session, agent, message, previousMessages, currentTools, currentSkills, approvedTools, allExuluTools, toolConfigs, providerapikey, languageModel, contexts, exuluConfig, instructions, req, maxStepCount }: {
         user?: User;
         session?: string;
         agent?: ExuluAgent;
@@ -848,7 +1017,6 @@ declare class ExuluProvider {
         providerapikey?: string | undefined;
         languageModel: LanguageModel;
         contexts?: ExuluContext[] | undefined;
-        rerankers?: ExuluReranker[] | undefined;
         exuluConfig?: ExuluConfig;
         instructions?: string;
         req?: Request;
@@ -954,17 +1122,15 @@ declare class ExuluApp {
     private _config?;
     private _evals;
     private _queues;
-    private _rerankers;
     private _contexts?;
     private _tools;
     private _expressApp;
     constructor();
-    create: ({ contexts, providers, config, agents, tools, evals, rerankers, }: {
+    create: ({ contexts, providers, config, agents, tools, evals, }: {
         contexts?: Record<string, ExuluContext>;
         config: ExuluConfig;
         agents?: ExuluAgent[];
         providers?: ExuluProvider[];
-        rerankers?: ExuluReranker[];
         evals?: ExuluEval[];
         tools?: ExuluTool[];
     }) => Promise<ExuluApp>;
@@ -2063,14 +2229,72 @@ declare function validatePythonEnvironment(packageRoot?: string, checkPackages?:
     message: string;
 }>;
 
+/**
+ * resolveOcr — the OCR-side counterpart of resolveEmbedder.
+ *
+ * Like resolveEmbedder, this is LiteLLM-ONLY: OCR always goes through the
+ * spawned LiteLLM proxy's Mistral-compatible `/v1/ocr` endpoint. There is no
+ * in-code provider/SDK fallback — a caller just names a LiteLLM `model` (e.g.
+ * "mistral-ocr", "vertex-ocr") and it works, with cost attribution via tags
+ * (user/role/project/agent/routine/context, when provided — see buildTags()).
+ *
+ * Routing OCR through the proxy means we can cost-control it through the same
+ * tag-based budgets as chat and embeddings, and switch the underlying provider
+ * (mistral / azure_ai / vertex_ai) by editing config.litellm.yaml without
+ * touching this code.
+ *
+ * LiteLLM follows the Mistral OCR request/response shape:
+ *   https://docs.mistral.ai/capabilities/vision/#optical-character-recognition-ocr
+ */
+type ResolveOcrInput = {
+    /** LiteLLM model_name of the OCR model (e.g. "mistral-ocr"). */
+    model: string;
+    /** Context this OCR belongs to — emitted as context_id_/context_name_ tags. */
+    contextId?: string;
+    contextName?: string;
+    user?: User;
+    /** When only a numeric user id is available (background ingestion jobs). */
+    userId?: number;
+    roleId?: string;
+    project?: Project;
+    agent?: ExuluAgent;
+    routine?: {
+        id: string;
+        name: string;
+    };
+};
+
 type DocumentProcessorConfig = {
     vlm?: {
-        model: LanguageModel;
+        /**
+         * LiteLLM model_name for the VLM page-validation pass (declared in
+         * config.litellm.yaml, e.g. "vertex-gemini-2.5-flash"). Resolved via
+         * resolveModel() so the VLM pass shares the same tag-based cost controls
+         * and provider-switching as chat / embeddings / OCR, and the underlying
+         * provider can be swapped without code changes.
+         */
+        model: string;
         concurrency: number;
     };
     processor: {
         name: "docling" | "liteparse" | "mistral" | "officeparser";
+        /**
+         * LiteLLM model_name for the "mistral" OCR processor (declared in
+         * config.litellm.yaml). Defaults to "mistral-ocr". OCR is routed through
+         * the LiteLLM proxy so it shares the same tag-based cost controls as chat
+         * and embeddings, and the underlying provider (mistral / azure_ai /
+         * vertex_ai) can be switched without code changes.
+         */
+        model?: string;
     };
+    /**
+     * Optional cost-attribution context, forwarded to LiteLLM as spend tags
+     * (user / role / project / context) for both the OCR pass (resolveOcr) and
+     * the VLM page-validation pass (resolveModel). Not yet populated by callers;
+     * the wiring is in place so per-user/per-context budgets work the moment
+     * attribution is threaded through.
+     */
+    attribution?: Omit<ResolveOcrInput, "model">;
     debugging?: {
         deleteTempFiles?: boolean;
     };
@@ -2090,6 +2314,81 @@ declare function documentProcessor({ file, name, config }: {
     config?: DocumentProcessorConfig;
 }): Promise<ProcessedDocument | undefined>;
 
+/**
+ * resolveReranker — the rerank-side counterpart of resolveEmbedder / resolveOcr.
+ *
+ * Like those, this is LiteLLM-ONLY: reranking always goes through the spawned
+ * LiteLLM proxy's cohere-compatible `/v1/rerank` endpoint. There is no in-code
+ * provider/SDK fallback — a caller just names a LiteLLM `model` (a model_name
+ * declared in config.litellm.yaml with `model_info.type: reranker`) and it
+ * works, with cost attribution via tags (user/role/project/agent/routine/
+ * context, when provided — see buildTags()).
+ *
+ * Routing rerank through the proxy means we cost-control it through the same
+ * tag-based budgets as chat / embeddings / OCR, and switch the underlying
+ * provider (cohere / vertex_ai / together_ai / ...) by editing
+ * config.litellm.yaml without touching this code.
+ *
+ * `rerank` takes the chunks directly, builds each document as
+ * `item_name + ": " + chunk_content` (the standard retrieval convention), calls
+ * the proxy, and maps the relevance scores back onto the chunks (reordered,
+ * `rerank_score` attached). The item type is constrained structurally
+ * (item_name / chunk_content) so both ChunkResult and VectorSearchChunkResult
+ * work without importing either — no src/exulu → retrieval/GraphQL dependency.
+ *
+ * LiteLLM follows the Cohere rerank request/response shape:
+ *   https://docs.cohere.com/reference/rerank
+ */
+type ResolveRerankerInput = {
+    /** LiteLLM model_name of the reranker (e.g. "rerank-v4.0-pro"). */
+    model: string;
+    /** Context this rerank belongs to — emitted as context_id_/context_name_ tags. */
+    contextId?: string;
+    contextName?: string;
+    user?: User;
+    /** When only a numeric user id is available (background ingestion jobs). */
+    userId?: number;
+    roleId?: string;
+    project?: Project;
+    agent?: ExuluAgent;
+    routine?: {
+        id: string;
+        name: string;
+    };
+};
+/** Minimal chunk shape rerank() needs to build a document. */
+type RerankableChunk = {
+    item_name?: string;
+    chunk_content?: string;
+};
+
+/**
+ * Public, package-facing reranker — the counterpart of
+ * `ExuluDocumentProcessor.process`. A drop-in replacement for a hand-rolled
+ * Cohere / Google reranker: pass `{ query, items, model }` and get the items
+ * back reordered desc by relevance with a `rerank_score` attached.
+ *
+ * `model` is a LiteLLM model_name declared in config.litellm.yaml with
+ * `model_info.type: reranker`, so the SAME call works against any supported
+ * provider (cohere / vertex_ai / together_ai / ...) — switch providers in
+ * config, not in code — and reranking is cost-attributed via the optional
+ * identity/context fields (user / role / project / agent / routine / context).
+ *
+ * Each document is built as `item_name + ": " + chunk_content` (the standard
+ * retrieval convention). Items are constrained structurally, so any chunk shape
+ * carrying `item_name` / `chunk_content` works and the extra fields are
+ * preserved on the returned objects.
+ */
+type ExuluRerankInput<T extends RerankableChunk> = {
+    query: string;
+    items: T[];
+    /** Only score/return the top N items (optional optimization hint). */
+    topN?: number;
+} & ResolveRerankerInput;
+declare function rerank<T extends RerankableChunk>(input: ExuluRerankInput<T>): Promise<(T & {
+    rerank_score: number;
+})[]>;
+
 /**
  * Creates the v3 ExuluTool for agentic context retrieval.
  *
@@ -2099,9 +2398,8 @@ declare function documentProcessor({ file, name, config }: {
  * - Context example records sampled at init and cached
  * - Strategy-specific instructions and tool sets
  */
-declare function createAgenticRetrievalToolV3({ contexts, instructions: adminInstructions, rerankers, user, role, model, preselected, memoryItems }: {
+declare function createAgenticRetrievalToolV3({ contexts, instructions: adminInstructions, user, role, model, preselected, memoryItems }: {
     contexts: ExuluContext[];
-    rerankers: ExuluReranker[];
     user?: User;
     role?: string;
     model?: LanguageModel;
@@ -2181,6 +2479,9 @@ declare const ExuluAuthentication: {
 declare const ExuluDocumentProcessor: {
     process: typeof documentProcessor;
 };
+declare const ExuluReranker: {
+    rerank: typeof rerank;
+};
 declare const ExuluOtel: {
     create: ({ SIGNOZ_ACCESS_TOKEN, SIGNOZ_TRACES_URL, SIGNOZ_LOGS_URL, }: {
         SIGNOZ_ACCESS_TOKEN: string;
@@ -2221,4 +2522,4 @@ declare const ExuluPython: {
     instructions: typeof getPythonSetupInstructions;
 };
 
-export { type JOB_STATUS as EXULU_JOB_STATUS, JOB_STATUS_ENUM as EXULU_JOB_STATUS_ENUM, type STATISTICS_TYPE as EXULU_STATISTICS_TYPE, STATISTICS_TYPE_ENUM as EXULU_STATISTICS_TYPE_ENUM, type ExuluAgent, ExuluApp, ExuluAuthentication, ExuluChunkers, ExuluContext, ExuluDatabase, ExuluDefaultProviders, ExuluDefaultTools, ExuluDocumentProcessor, ExuluEmbedder, ExuluEval, type Item as ExuluItem, ExuluJobs, ExuluOtel, ExuluProvider, ExuluPython, queues as ExuluQueues, ExuluReranker, ExuluTool, trajectoryRegistry as ExuluTrajectoryRegistry, ExuluVariables };
+export { type ChunkerOperation, type ChunkerResponse, type JOB_STATUS as EXULU_JOB_STATUS, JOB_STATUS_ENUM as EXULU_JOB_STATUS_ENUM, type STATISTICS_TYPE as EXULU_STATISTICS_TYPE, STATISTICS_TYPE_ENUM as EXULU_STATISTICS_TYPE_ENUM, type ExuluAgent, ExuluApp, ExuluAuthentication, ExuluChunkers, ExuluContext, type ExuluContextEmbedder, ExuluDatabase, ExuluDefaultProviders, ExuluDefaultTools, ExuluDocumentProcessor, ExuluEval, type Item as ExuluItem, ExuluJobs, type ExuluOauthConfig, type ExuluOauthToolContext, ExuluOtel, ExuluProvider, ExuluPython, queues as ExuluQueues, ExuluReranker, ExuluTool, trajectoryRegistry as ExuluTrajectoryRegistry, ExuluVariables, defaultChunker };