@exulu/backend 1.66.0 → 1.67.0

package/dist/index.d.cts

@@ -184,7 +184,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 +236,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 +257,7 @@ declare class ExuluTool {
             default?: string | boolean | number;
         }[];
         needsApproval?: boolean;
+        oauth?: ExuluOauthConfig;
         execute: (inputs: any, options?: any) => Promise<{
             result?: string;
             job?: string;
@@ -475,6 +517,70 @@ 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;
+    /** 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. */
+    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,6 +597,12 @@ 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;
@@ -579,8 +691,14 @@ 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, processor, active, fields, queryRewriter, resultReranker, configuration, entities, sources, }: {
         id: string;
         name: string;
         fields: ExuluContextFieldDefinition[];
@@ -607,6 +725,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 +752,7 @@ declare class ExuluContext {
             before?: number;
             after?: number;
         };
+        entityFilter?: EntityFilter;
     }) => Promise<{
         itemFilters: SearchFilters;
         chunkFilters: SearchFilters;
@@ -645,6 +765,7 @@ declare class ExuluContext {
             embedder: string;
         };
         chunks: VectorSearchChunkResult[];
+        entityInsights?: EntityInsights;
     }>;
     deleteAll: () => Promise<{
         count: number;
@@ -697,6 +818,30 @@ 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;
+        }>;
+        /** Remove all entities (and their mentions via cascade) of a given type. */
+        purgeType: (typeName: string) => Promise<{
+            removed: number;
+        }>;
+    };
     createItemsTable: () => Promise<void>;
     createChunksTable: () => Promise<void>;
 }
@@ -2221,4 +2366,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 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 };

package/dist/index.d.ts

@@ -184,7 +184,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 +236,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 +257,7 @@ declare class ExuluTool {
             default?: string | boolean | number;
         }[];
         needsApproval?: boolean;
+        oauth?: ExuluOauthConfig;
         execute: (inputs: any, options?: any) => Promise<{
             result?: string;
             job?: string;
@@ -475,6 +517,70 @@ 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;
+    /** 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. */
+    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,6 +597,12 @@ 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;
@@ -579,8 +691,14 @@ 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, processor, active, fields, queryRewriter, resultReranker, configuration, entities, sources, }: {
         id: string;
         name: string;
         fields: ExuluContextFieldDefinition[];
@@ -607,6 +725,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 +752,7 @@ declare class ExuluContext {
             before?: number;
             after?: number;
         };
+        entityFilter?: EntityFilter;
     }) => Promise<{
         itemFilters: SearchFilters;
         chunkFilters: SearchFilters;
@@ -645,6 +765,7 @@ declare class ExuluContext {
             embedder: string;
         };
         chunks: VectorSearchChunkResult[];
+        entityInsights?: EntityInsights;
     }>;
     deleteAll: () => Promise<{
         count: number;
@@ -697,6 +818,30 @@ 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;
+        }>;
+        /** Remove all entities (and their mentions via cascade) of a given type. */
+        purgeType: (typeName: string) => Promise<{
+            removed: number;
+        }>;
+    };
     createItemsTable: () => Promise<void>;
     createChunksTable: () => Promise<void>;
 }
@@ -2221,4 +2366,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 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 };