@vellumai/plugin-api 0.11.0-dev.202607310515.26a4155 → 0.11.0-dev.202607311245.e354912

package/index.d.ts

@@ -3756,7 +3756,7 @@ export declare interface AssistantEventSubscription {
     readonly connectionId: string;
 }
 
-declare interface AudioEmbeddingInput {
+export declare interface AudioEmbeddingInput {
     type: "audio";
     data: Buffer;
     mimeType: string;
@@ -4068,28 +4068,30 @@ declare type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Om
  */
 export declare function doesSupportVision(modelOrProfile: ModelProfileInfo | string): boolean;
 
+/**
+ * Embed an input and return the raw dense vector (provider, model, and
+ * dimensions included), with no persistence.
+ */
+export declare function embed(input: EmbeddingInput): Promise<EmbedResult>;
+
 /** Embed a target and upsert its vector into the vector store. */
 export declare function embedAndUpsert(targetType: EmbeddingTargetType, targetId: string, input: EmbeddingInput, extraPayload?: Record<string, unknown>): Promise<void>;
 
 declare function embedAndUpsert_2(config: AssistantConfig, targetType: "segment" | "item" | "summary" | "media" | "graph_node" | "pkb_file", targetId: string, input: EmbeddingInput, extraPayload?: Record<string, unknown>): Promise<void>;
 
 /** Accepts raw strings as shorthand for text inputs. */
-declare type EmbeddingInput = string | MultimodalEmbeddingInput;
+export declare type EmbeddingInput = string | MultimodalEmbeddingInput;
 
-/**
- * Plugin-facing facade over the embeddings subsystem: self-contained
- * operations that resolve the live workspace config internally, so callers
- * (plugins importing via `@vellumai/plugin-api`) hold no host config.
- *
- * The operations are loaded via dynamic `import()` inside each wrapper so
- * that importing this module — which every `@vellumai/plugin-api` consumer
- * does transitively — does not eagerly pull the embed/vector import graph
- * (`job-utils`, `embedding-backend`). An eager pull would force those
- * modules' named exports to resolve at instantiation, which breaks the
- * intentional partial module mocks in tests.
- */
 declare type EmbeddingTargetType = Parameters<embedAndUpsert_2>[1];
 
+/** A computed embedding with the provider/model that produced it. */
+export declare interface EmbedResult {
+    vector: number[];
+    provider: string;
+    model: string;
+    dimensions: number;
+}
+
 export declare function extractTextFromStoredMessageContent(raw: string | ContentBlock[]): string;
 
 export declare interface FileContent {
@@ -4107,6 +4109,12 @@ export declare interface FileContent {
     _attachmentId?: string;
 }
 
+/**
+ * Generate the sparse (lexical) vector for a text using the host's shared
+ * encoder. Pure and local: no backend call, no persistence.
+ */
+export declare function generateSparseEmbedding(text: string): Promise<SparseEmbedding>;
+
 /** Read the assistant's name from IDENTITY.md for personalized responses. */
 export declare function getAssistantName(): string | null;
 
@@ -4129,6 +4137,9 @@ export declare function getConversation(id: string): Promise<ConversationRow | n
  */
 export declare function getConversationDirPath(id: string, createdAtMs: number): Promise<string>;
 
+/** Fetch one document from the calling plugin's index, or null. */
+export declare function getDocument(documentId: string): Promise<IndexedDocument | null>;
+
 /** All messages of a conversation in insertion order. */
 export declare function getMessages(conversationId: string): Promise<MessageRow[]>;
 
@@ -4275,12 +4286,57 @@ export declare interface ImageContent {
     source: MediaSource_2;
 }
 
-declare interface ImageEmbeddingInput {
+export declare interface ImageEmbeddingInput {
     type: "image";
     data: Buffer;
     mimeType: string;
 }
 
+/**
+ * Embed and upsert a document into the calling plugin's private index (not
+ * agent recall). Returns the document id. Pass `opts.documentId` to overwrite
+ * an existing document in place.
+ */
+export declare function indexDocument(input: EmbeddingInput, opts?: IndexDocumentOptions): Promise<IndexDocumentResult>;
+
+export declare interface IndexDocumentOptions {
+    /**
+     * Reuse a caller-owned id to upsert a document in place (the update path:
+     * same id, overwrite). Omit to have the host mint a fresh document id.
+     */
+    documentId?: string;
+    /**
+     * Opaque provenance carried with the document (e.g. `{ rowId, fileId }`).
+     * Round-tripped verbatim on query/get; never interpreted by the host.
+     */
+    metadata?: Record<string, unknown>;
+    /** Override the stored creation timestamp (defaults to now). */
+    createdAt?: number;
+}
+
+export declare interface IndexDocumentResult {
+    documentId: string;
+    provider: string;
+    model: string;
+    dimensions: number;
+}
+
+export declare interface IndexedDocument {
+    documentId: string;
+    text: string;
+    modality: "text" | "image" | "audio" | "video";
+    metadata?: Record<string, unknown>;
+    createdAt: number;
+}
+
+export declare interface IndexHit {
+    documentId: string;
+    score: number;
+    text: string;
+    modality: "text" | "image" | "audio" | "video";
+    metadata?: Record<string, unknown>;
+}
+
 /**
  * Context passed to `Plugin.init()` during bootstrap. Carries the resolved
  * config, a pino-compatible logger scoped to the plugin, a per-plugin
@@ -4861,7 +4917,7 @@ export declare interface ModelProfileInfo {
     readonly isMix: boolean;
 }
 
-declare type MultimodalEmbeddingInput = TextEmbeddingInput | ImageEmbeddingInput | AudioEmbeddingInput | VideoEmbeddingInput;
+export declare type MultimodalEmbeddingInput = TextEmbeddingInput | ImageEmbeddingInput | AudioEmbeddingInput | VideoEmbeddingInput;
 
 /**
  * Open a streaming transcription session against the configured STT provider
@@ -5413,6 +5469,16 @@ export declare function quarantineRefusedExchanges(messages: Message[]): {
     droppedExchanges: number;
 };
 
+/** Hybrid semantic search over the calling plugin's index only. */
+export declare function queryIndex(query: EmbeddingInput, opts?: QueryIndexOptions): Promise<IndexHit[]>;
+
+export declare interface QueryIndexOptions {
+    /** Max hits to return. Defaults to 10. */
+    limit?: number;
+    /** Per-branch prefetch depth for the hybrid fusion. */
+    prefetchLimit?: number;
+}
+
 export declare interface RedactedThinkingContent {
     type: "redacted_thinking";
     data: string;
@@ -5431,6 +5497,9 @@ export declare interface RedactedThinkingContent {
  */
 export declare const REFUSAL_FALLBACK_TEXT = "Sorry \u2014 I wasn't able to generate a response to that. Please try rephrasing or asking in a different way.";
 
+/** Remove one document from the calling plugin's index. */
+export declare function removeDocument(documentId: string): Promise<void>;
+
 declare type ResolutionFallbackReason = "missing" | "disabled" | "incomplete";
 
 /**
@@ -5935,6 +6004,12 @@ declare interface SkillInstallMeta {
  */
 declare type SkillSource = "bundled" | "managed" | "workspace" | "extra" | "plugin";
 
+/** Sparse vector representation: parallel arrays of term indices and weights. */
+export declare interface SparseEmbedding {
+    indices: number[];
+    values: number[];
+}
+
 /**
  * The full `stop` context a hook receives — the dispatching call site's
  * {@link StopInputContext} plus the pipeline-stamped {@link BaseHookContext}
@@ -6233,7 +6308,7 @@ export declare interface TextContent {
     text: string;
 }
 
-declare interface TextEmbeddingInput {
+export declare interface TextEmbeddingInput {
     type: "text";
     text: string;
 }
@@ -6896,7 +6971,7 @@ declare interface UserPromptSubmitInputContext {
     latestMessages: Message[];
 }
 
-declare interface VideoEmbeddingInput {
+export declare interface VideoEmbeddingInput {
     type: "video";
     data: Buffer;
     mimeType: string;

package/index.js

@@ -13,16 +13,20 @@ export const buildMessageExcerpt = api.buildMessageExcerpt;
 export const createLiveVoiceConnection = api.createLiveVoiceConnection;
 export const deleteConversation = api.deleteConversation;
 export const doesSupportVision = api.doesSupportVision;
+export const embed = api.embed;
 export const embedAndUpsert = api.embedAndUpsert;
 export const extractTextFromStoredMessageContent = api.extractTextFromStoredMessageContent;
+export const generateSparseEmbedding = api.generateSparseEmbedding;
 export const getAssistantName = api.getAssistantName;
 export const getConfiguredProvider = api.getConfiguredProvider;
 export const getConversation = api.getConversation;
 export const getConversationDirPath = api.getConversationDirPath;
+export const getDocument = api.getDocument;
 export const getMessages = api.getMessages;
 export const getModelProfiles = api.getModelProfiles;
 export const getWorkspaceDir = api.getWorkspaceDir;
 export const hasLexicalTokens = api.hasLexicalTokens;
+export const indexDocument = api.indexDocument;
 export const isConversationProcessing = api.isConversationProcessing;
 export const isMaxTokensStopReason = api.isMaxTokensStopReason;
 export const isToolResultMessage = api.isToolResultMessage;
@@ -35,6 +39,8 @@ export const openTranscriptionSession = api.openTranscriptionSession;
 export const parseMessageMetadata = api.parseMessageMetadata;
 export const publishEvent = api.publishEvent;
 export const quarantineRefusedExchanges = api.quarantineRefusedExchanges;
+export const queryIndex = api.queryIndex;
+export const removeDocument = api.removeDocument;
 export const resolveCredential = api.resolveCredential;
 export const resolveMediaSourceData = api.resolveMediaSourceData;
 export const resolveUserName = api.resolveUserName;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/plugin-api",
-  "version": "0.11.0-dev.202607310515.26a4155",
+  "version": "0.11.0-dev.202607311245.e354912",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",