@exulu/backend 1.67.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.
@@ -350,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;
@@ -373,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
  */
@@ -536,8 +552,6 @@ type ExuluEntitiesConfig = {
     types?: EntityTypeDefinition[];
     /** models.id used for extraction. Resolved via resolveModel(). Falls back to a platform default. */
     model?: string;
-    /** Where to extract from. "chunks" (default) locates each mention to a chunk. */
-    extractFrom?: "chunks" | "document";
     /** 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. */
@@ -609,6 +623,18 @@ type VectorSearchChunkResult = {
     };
 };
 
+/**
+ * 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;
@@ -651,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;
@@ -669,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;
@@ -698,12 +730,13 @@ declare class ExuluContext {
      */
     entities?: ExuluEntitiesConfig;
     sources: ExuluContextSource[];
-    constructor({ id, name, description, embedder, processor, active, fields, queryRewriter, resultReranker, configuration, entities, 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;
@@ -837,6 +870,18 @@ declare class ExuluContext {
             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;
@@ -846,26 +891,6 @@ declare class ExuluContext {
     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;
@@ -944,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;
@@ -962,7 +987,6 @@ declare class ExuluProvider {
         providerapikey?: string | undefined;
         languageModel: LanguageModel;
         contexts?: ExuluContext[] | undefined;
-        rerankers?: ExuluReranker[] | undefined;
         exuluConfig?: ExuluConfig;
         instructions?: string;
         onTokenUsage?: (usage: {
@@ -978,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;
@@ -993,7 +1017,6 @@ declare class ExuluProvider {
         providerapikey?: string | undefined;
         languageModel: LanguageModel;
         contexts?: ExuluContext[] | undefined;
-        rerankers?: ExuluReranker[] | undefined;
         exuluConfig?: ExuluConfig;
         instructions?: string;
         req?: Request;
@@ -1099,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>;
@@ -2208,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;
     };
@@ -2235,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.
  *
@@ -2244,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;
@@ -2326,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;
@@ -2366,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, type ExuluOauthConfig, type ExuluOauthToolContext, 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 };