@vectorize-io/hindsight-client 0.4.22 → 0.5.0

package/dist/index.d.mts

@@ -366,6 +366,258 @@ type BankStatsResponse = {
      */
     total_observations?: number;
 };
+/**
+ * BankTemplateConfig
+ *
+ * Bank configuration fields within a template manifest.
+ *
+ * Only includes configurable (per-bank) fields. Credential fields
+ * (API keys, base URLs) are intentionally excluded for security.
+ */
+type BankTemplateConfig = {
+    /**
+     * Reflect Mission
+     *
+     * Mission/context for Reflect operations
+     */
+    reflect_mission?: string | null;
+    /**
+     * Retain Mission
+     *
+     * Steers what gets extracted during retain
+     */
+    retain_mission?: string | null;
+    /**
+     * Retain Extraction Mode
+     *
+     * Fact extraction mode: 'concise' (default), 'verbose', or 'custom'
+     */
+    retain_extraction_mode?: string | null;
+    /**
+     * Retain Custom Instructions
+     *
+     * Custom extraction prompt (when mode='custom')
+     */
+    retain_custom_instructions?: string | null;
+    /**
+     * Retain Chunk Size
+     *
+     * Max token size for each content chunk
+     */
+    retain_chunk_size?: number | null;
+    /**
+     * Enable Observations
+     *
+     * Toggle observation consolidation
+     */
+    enable_observations?: boolean | null;
+    /**
+     * Observations Mission
+     *
+     * Controls what gets synthesised
+     */
+    observations_mission?: string | null;
+    /**
+     * Disposition Skepticism
+     *
+     * Skepticism trait (1-5)
+     */
+    disposition_skepticism?: number | null;
+    /**
+     * Disposition Literalism
+     *
+     * Literalism trait (1-5)
+     */
+    disposition_literalism?: number | null;
+    /**
+     * Disposition Empathy
+     *
+     * Empathy trait (1-5)
+     */
+    disposition_empathy?: number | null;
+    /**
+     * Entity Labels
+     *
+     * Controlled vocabulary for entity labels
+     */
+    entity_labels?: Array<{
+        [key: string]: unknown;
+    }> | null;
+    /**
+     * Entities Allow Free Form
+     *
+     * Allow entities outside the label vocabulary
+     */
+    entities_allow_free_form?: boolean | null;
+};
+/**
+ * BankTemplateDirective
+ *
+ * A directive definition within a bank template manifest.
+ *
+ * Directives are matched by name on re-import: existing directives
+ * with the same name are updated, new ones are created.
+ */
+type BankTemplateDirective = {
+    /**
+     * Name
+     *
+     * Human-readable name for the directive (used as match key on re-import)
+     */
+    name: string;
+    /**
+     * Content
+     *
+     * The directive text to inject into prompts
+     */
+    content: string;
+    /**
+     * Priority
+     *
+     * Higher priority directives are injected first
+     */
+    priority?: number;
+    /**
+     * Is Active
+     *
+     * Whether this directive is active
+     */
+    is_active?: boolean;
+    /**
+     * Tags
+     *
+     * Tags for filtering
+     */
+    tags?: Array<string>;
+};
+/**
+ * BankTemplateImportResponse
+ *
+ * Response model for the bank template import endpoint.
+ */
+type BankTemplateImportResponse = {
+    /**
+     * Bank Id
+     *
+     * Bank that was imported into
+     */
+    bank_id: string;
+    /**
+     * Config Applied
+     *
+     * Whether bank config was updated
+     */
+    config_applied: boolean;
+    /**
+     * Mental Models Created
+     *
+     * IDs of newly created mental models
+     */
+    mental_models_created?: Array<string>;
+    /**
+     * Mental Models Updated
+     *
+     * IDs of updated mental models
+     */
+    mental_models_updated?: Array<string>;
+    /**
+     * Directives Created
+     *
+     * Names of newly created directives
+     */
+    directives_created?: Array<string>;
+    /**
+     * Directives Updated
+     *
+     * Names of updated directives
+     */
+    directives_updated?: Array<string>;
+    /**
+     * Operation Ids
+     *
+     * Operation IDs for mental model content generation (async)
+     */
+    operation_ids?: Array<string>;
+    /**
+     * Dry Run
+     *
+     * True if this was a validation-only run
+     */
+    dry_run?: boolean;
+};
+/**
+ * BankTemplateManifest
+ *
+ * A bank template manifest for import/export.
+ *
+ * Version field enables forward-compatible schema evolution: the API
+ * auto-upgrades older manifest versions to the current schema on import.
+ */
+type BankTemplateManifest = {
+    /**
+     * Version
+     *
+     * Manifest schema version (currently '1')
+     */
+    version: string;
+    /**
+     * Bank configuration to apply. Omit to leave config unchanged.
+     */
+    bank?: BankTemplateConfig | null;
+    /**
+     * Mental Models
+     *
+     * Mental models to create or update (matched by id). Omit to leave unchanged.
+     */
+    mental_models?: Array<BankTemplateMentalModel> | null;
+    /**
+     * Directives
+     *
+     * Directives to create or update (matched by name). Omit to leave unchanged.
+     */
+    directives?: Array<BankTemplateDirective> | null;
+};
+/**
+ * BankTemplateMentalModel
+ *
+ * A mental model definition within a bank template manifest.
+ */
+type BankTemplateMentalModel = {
+    /**
+     * Id
+     *
+     * Unique ID for the mental model (alphanumeric lowercase with hyphens)
+     */
+    id: string;
+    /**
+     * Name
+     *
+     * Human-readable name for the mental model
+     */
+    name: string;
+    /**
+     * Source Query
+     *
+     * The query to run to generate content
+     */
+    source_query: string;
+    /**
+     * Tags
+     *
+     * Tags for scoped visibility
+     */
+    tags?: Array<string>;
+    /**
+     * Max Tokens
+     *
+     * Maximum tokens for generated content
+     */
+    max_tokens?: number;
+    /**
+     * Trigger settings
+     */
+    trigger?: MentalModelTriggerOutput;
+};
 /**
  * Body_file_retain
  */
@@ -1340,6 +1592,12 @@ type MemoryItem = {
      * Named retain strategy for this item. Overrides the bank's default strategy for this item only. Strategies are defined in the bank config under 'retain_strategies'.
      */
     strategy?: string | null;
+    /**
+     * Update Mode
+     *
+     * How to handle an existing document with the same document_id. 'replace' (default) deletes old data and reprocesses from scratch. 'append' concatenates new content to the existing document text and reprocesses.
+     */
+    update_mode?: "replace" | "append" | null;
 };
 /**
  * MentalModelListResponse
@@ -1373,13 +1631,13 @@ type MentalModelResponse = {
     /**
      * Source Query
      */
-    source_query: string;
+    source_query?: string | null;
     /**
      * Content
      *
      * The mental model content as well-formatted markdown (auto-generated from reflect endpoint)
      */
-    content: string;
+    content?: string | null;
     /**
      * Tags
      */
@@ -1387,8 +1645,8 @@ type MentalModelResponse = {
     /**
      * Max Tokens
      */
-    max_tokens?: number;
-    trigger?: MentalModelTriggerOutput;
+    max_tokens?: number | null;
+    trigger?: MentalModelTriggerOutput | null;
     /**
      * Last Refreshed At
      */
@@ -3117,6 +3375,12 @@ type ListMentalModelsData = {
          * How to match tags
          */
         tags_match?: "any" | "all" | "exact";
+        /**
+         * Detail
+         *
+         * Detail level: 'metadata' (names/tags only), 'content' (adds content/config), 'full' (includes reflect_response)
+         */
+        detail?: "metadata" | "content" | "full";
         /**
          * Limit
          */
@@ -3220,7 +3484,14 @@ type GetMentalModelData = {
          */
         mental_model_id: string;
     };
-    query?: never;
+    query?: {
+        /**
+         * Detail
+         *
+         * Detail level: 'metadata' (names/tags only), 'content' (adds content/config), 'full' (includes reflect_response)
+         */
+        detail?: "metadata" | "content" | "full";
+    };
     url: "/v1/default/banks/{bank_id}/mental-models/{mental_model_id}";
 };
 type GetMentalModelErrors = {
@@ -4077,6 +4348,83 @@ type CreateOrUpdateBankResponses = {
      */
     200: BankProfileResponse;
 };
+type ImportBankTemplateData = {
+    body?: never;
+    headers?: {
+        /**
+         * Authorization
+         */
+        authorization?: string | null;
+    };
+    path: {
+        /**
+         * Bank Id
+         */
+        bank_id: string;
+    };
+    query?: {
+        /**
+         * Dry Run
+         *
+         * Validate only, do not apply changes
+         */
+        dry_run?: boolean;
+    };
+    url: "/v1/default/banks/{bank_id}/import";
+};
+type ImportBankTemplateErrors = {
+    /**
+     * Validation Error
+     */
+    422: HttpValidationError;
+};
+type ImportBankTemplateResponses = {
+    /**
+     * Successful Response
+     */
+    200: BankTemplateImportResponse;
+};
+type ExportBankTemplateData = {
+    body?: never;
+    headers?: {
+        /**
+         * Authorization
+         */
+        authorization?: string | null;
+    };
+    path: {
+        /**
+         * Bank Id
+         */
+        bank_id: string;
+    };
+    query?: never;
+    url: "/v1/default/banks/{bank_id}/export";
+};
+type ExportBankTemplateErrors = {
+    /**
+     * Validation Error
+     */
+    422: HttpValidationError;
+};
+type ExportBankTemplateResponses = {
+    /**
+     * Successful Response
+     */
+    200: BankTemplateManifest;
+};
+type GetBankTemplateSchemaData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: "/v1/bank-template-schema";
+};
+type GetBankTemplateSchemaResponses = {
+    /**
+     * Successful Response
+     */
+    200: unknown;
+};
 type ClearObservationsData = {
     body?: never;
     headers?: {
@@ -5262,6 +5610,24 @@ declare const updateBank: <ThrowOnError extends boolean = false>(options: Option
  * Create a new agent or update existing agent with disposition and mission. Auto-fills missing fields with defaults.
  */
 declare const createOrUpdateBank: <ThrowOnError extends boolean = false>(options: Options<CreateOrUpdateBankData, ThrowOnError>) => RequestResult<CreateOrUpdateBankResponses, CreateOrUpdateBankErrors, ThrowOnError, "fields">;
+/**
+ * Import bank template
+ *
+ * Import a bank template manifest to create or update a bank's configuration, mental models, and directives. If the bank does not exist it is created. Config fields are applied as per-bank overrides. Mental models are matched by id, directives by name — existing ones are updated, new ones are created. Use dry_run=true to validate the manifest without applying changes.
+ */
+declare const importBankTemplate: <ThrowOnError extends boolean = false>(options: Options<ImportBankTemplateData, ThrowOnError>) => RequestResult<ImportBankTemplateResponses, ImportBankTemplateErrors, ThrowOnError, "fields">;
+/**
+ * Export bank template
+ *
+ * Export a bank's current configuration, mental models, and directives as a template manifest. The exported manifest can be imported into another bank to replicate the setup.
+ */
+declare const exportBankTemplate: <ThrowOnError extends boolean = false>(options: Options<ExportBankTemplateData, ThrowOnError>) => RequestResult<ExportBankTemplateResponses, ExportBankTemplateErrors, ThrowOnError, "fields">;
+/**
+ * Get bank template JSON Schema
+ *
+ * Returns the JSON Schema for the bank template manifest format. Use this to validate template manifests before importing.
+ */
+declare const getBankTemplateSchema: <ThrowOnError extends boolean = false>(options?: Options<GetBankTemplateSchemaData, ThrowOnError>) => RequestResult<GetBankTemplateSchemaResponses, unknown, ThrowOnError, "fields">;
 /**
  * Clear all observations
  *
@@ -5432,10 +5798,12 @@ declare const sdk_gen_deleteDirective: typeof deleteDirective;
 declare const sdk_gen_deleteDocument: typeof deleteDocument;
 declare const sdk_gen_deleteMentalModel: typeof deleteMentalModel;
 declare const sdk_gen_deleteWebhook: typeof deleteWebhook;
+declare const sdk_gen_exportBankTemplate: typeof exportBankTemplate;
 declare const sdk_gen_fileRetain: typeof fileRetain;
 declare const sdk_gen_getAgentStats: typeof getAgentStats;
 declare const sdk_gen_getBankConfig: typeof getBankConfig;
 declare const sdk_gen_getBankProfile: typeof getBankProfile;
+declare const sdk_gen_getBankTemplateSchema: typeof getBankTemplateSchema;
 declare const sdk_gen_getChunk: typeof getChunk;
 declare const sdk_gen_getDirective: typeof getDirective;
 declare const sdk_gen_getDocument: typeof getDocument;
@@ -5448,6 +5816,7 @@ declare const sdk_gen_getObservationHistory: typeof getObservationHistory;
 declare const sdk_gen_getOperationStatus: typeof getOperationStatus;
 declare const sdk_gen_getVersion: typeof getVersion;
 declare const sdk_gen_healthEndpointHealthGet: typeof healthEndpointHealthGet;
+declare const sdk_gen_importBankTemplate: typeof importBankTemplate;
 declare const sdk_gen_listAuditLogs: typeof listAuditLogs;
 declare const sdk_gen_listBanks: typeof listBanks;
 declare const sdk_gen_listDirectives: typeof listDirectives;
@@ -5477,7 +5846,7 @@ declare const sdk_gen_updateDocument: typeof updateDocument;
 declare const sdk_gen_updateMentalModel: typeof updateMentalModel;
 declare const sdk_gen_updateWebhook: typeof updateWebhook;
 declare namespace sdk_gen {
-  export { type sdk_gen_Options as Options, sdk_gen_addBankBackground as addBankBackground, sdk_gen_auditLogStats as auditLogStats, sdk_gen_cancelOperation as cancelOperation, sdk_gen_clearBankMemories as clearBankMemories, sdk_gen_clearMemoryObservations as clearMemoryObservations, sdk_gen_clearObservations as clearObservations, sdk_gen_createDirective as createDirective, sdk_gen_createMentalModel as createMentalModel, sdk_gen_createOrUpdateBank as createOrUpdateBank, sdk_gen_createWebhook as createWebhook, sdk_gen_deleteBank as deleteBank, sdk_gen_deleteDirective as deleteDirective, sdk_gen_deleteDocument as deleteDocument, sdk_gen_deleteMentalModel as deleteMentalModel, sdk_gen_deleteWebhook as deleteWebhook, sdk_gen_fileRetain as fileRetain, sdk_gen_getAgentStats as getAgentStats, sdk_gen_getBankConfig as getBankConfig, sdk_gen_getBankProfile as getBankProfile, sdk_gen_getChunk as getChunk, sdk_gen_getDirective as getDirective, sdk_gen_getDocument as getDocument, sdk_gen_getEntity as getEntity, sdk_gen_getGraph as getGraph, sdk_gen_getMemory as getMemory, sdk_gen_getMentalModel as getMentalModel, sdk_gen_getMentalModelHistory as getMentalModelHistory, sdk_gen_getObservationHistory as getObservationHistory, sdk_gen_getOperationStatus as getOperationStatus, sdk_gen_getVersion as getVersion, sdk_gen_healthEndpointHealthGet as healthEndpointHealthGet, sdk_gen_listAuditLogs as listAuditLogs, sdk_gen_listBanks as listBanks, sdk_gen_listDirectives as listDirectives, sdk_gen_listDocuments as listDocuments, sdk_gen_listEntities as listEntities, sdk_gen_listMemories as listMemories, sdk_gen_listMentalModels as listMentalModels, sdk_gen_listOperations as listOperations, sdk_gen_listTags as listTags, sdk_gen_listWebhookDeliveries as listWebhookDeliveries, sdk_gen_listWebhooks as listWebhooks, sdk_gen_metricsEndpointMetricsGet as metricsEndpointMetricsGet, sdk_gen_recallMemories as recallMemories, sdk_gen_recoverConsolidation as recoverConsolidation, sdk_gen_reflect as reflect, sdk_gen_refreshMentalModel as refreshMentalModel, sdk_gen_regenerateEntityObservations as regenerateEntityObservations, sdk_gen_resetBankConfig as resetBankConfig, sdk_gen_retainMemories as retainMemories, sdk_gen_retryOperation as retryOperation, sdk_gen_triggerConsolidation as triggerConsolidation, sdk_gen_updateBank as updateBank, sdk_gen_updateBankConfig as updateBankConfig, sdk_gen_updateBankDisposition as updateBankDisposition, sdk_gen_updateDirective as updateDirective, sdk_gen_updateDocument as updateDocument, sdk_gen_updateMentalModel as updateMentalModel, sdk_gen_updateWebhook as updateWebhook };
+  export { type sdk_gen_Options as Options, sdk_gen_addBankBackground as addBankBackground, sdk_gen_auditLogStats as auditLogStats, sdk_gen_cancelOperation as cancelOperation, sdk_gen_clearBankMemories as clearBankMemories, sdk_gen_clearMemoryObservations as clearMemoryObservations, sdk_gen_clearObservations as clearObservations, sdk_gen_createDirective as createDirective, sdk_gen_createMentalModel as createMentalModel, sdk_gen_createOrUpdateBank as createOrUpdateBank, sdk_gen_createWebhook as createWebhook, sdk_gen_deleteBank as deleteBank, sdk_gen_deleteDirective as deleteDirective, sdk_gen_deleteDocument as deleteDocument, sdk_gen_deleteMentalModel as deleteMentalModel, sdk_gen_deleteWebhook as deleteWebhook, sdk_gen_exportBankTemplate as exportBankTemplate, sdk_gen_fileRetain as fileRetain, sdk_gen_getAgentStats as getAgentStats, sdk_gen_getBankConfig as getBankConfig, sdk_gen_getBankProfile as getBankProfile, sdk_gen_getBankTemplateSchema as getBankTemplateSchema, sdk_gen_getChunk as getChunk, sdk_gen_getDirective as getDirective, sdk_gen_getDocument as getDocument, sdk_gen_getEntity as getEntity, sdk_gen_getGraph as getGraph, sdk_gen_getMemory as getMemory, sdk_gen_getMentalModel as getMentalModel, sdk_gen_getMentalModelHistory as getMentalModelHistory, sdk_gen_getObservationHistory as getObservationHistory, sdk_gen_getOperationStatus as getOperationStatus, sdk_gen_getVersion as getVersion, sdk_gen_healthEndpointHealthGet as healthEndpointHealthGet, sdk_gen_importBankTemplate as importBankTemplate, sdk_gen_listAuditLogs as listAuditLogs, sdk_gen_listBanks as listBanks, sdk_gen_listDirectives as listDirectives, sdk_gen_listDocuments as listDocuments, sdk_gen_listEntities as listEntities, sdk_gen_listMemories as listMemories, sdk_gen_listMentalModels as listMentalModels, sdk_gen_listOperations as listOperations, sdk_gen_listTags as listTags, sdk_gen_listWebhookDeliveries as listWebhookDeliveries, sdk_gen_listWebhooks as listWebhooks, sdk_gen_metricsEndpointMetricsGet as metricsEndpointMetricsGet, sdk_gen_recallMemories as recallMemories, sdk_gen_recoverConsolidation as recoverConsolidation, sdk_gen_reflect as reflect, sdk_gen_refreshMentalModel as refreshMentalModel, sdk_gen_regenerateEntityObservations as regenerateEntityObservations, sdk_gen_resetBankConfig as resetBankConfig, sdk_gen_retainMemories as retainMemories, sdk_gen_retryOperation as retryOperation, sdk_gen_triggerConsolidation as triggerConsolidation, sdk_gen_updateBank as updateBank, sdk_gen_updateBankConfig as updateBankConfig, sdk_gen_updateBankDisposition as updateBankDisposition, sdk_gen_updateDirective as updateDirective, sdk_gen_updateDocument as updateDocument, sdk_gen_updateMentalModel as updateMentalModel, sdk_gen_updateWebhook as updateWebhook };
 }
 
 /**
@@ -5537,6 +5906,7 @@ interface MemoryItemInput {
     tags?: string[];
     observation_scopes?: "per_tag" | "combined" | "all_combinations" | string[][];
     strategy?: string;
+    update_mode?: "replace" | "append";
 }
 declare class HindsightClient {
     private client;
@@ -5557,6 +5927,8 @@ declare class HindsightClient {
         entities?: EntityInput[];
         /** Optional list of tags for this memory */
         tags?: string[];
+        /** How to handle existing documents: 'replace' (default) or 'append' */
+        updateMode?: "replace" | "append";
     }): Promise<RetainResponse>;
     /**
      * Retain multiple memories in batch.
@@ -5791,5 +6163,16 @@ declare class HindsightClient {
      */
     getMentalModelHistory(bankId: string, mentalModelId: string): Promise<any>;
 }
+/**
+ * Serialize a RecallResponse to a string suitable for LLM prompts.
+ *
+ * Builds a prompt containing:
+ * - Facts: each result as a JSON object with text, context, temporal fields,
+ *   and source_chunk (if the result's chunk_id matches a chunk in the response).
+ * - Entities: entity summaries from observations, formatted as sections.
+ *
+ * Mirrors the format used internally by Hindsight's reflect operation.
+ */
+declare function recallResponseToPromptString(response: RecallResponse): string;
 
-export { type BankConfigResponse, type BankProfileResponse, type Budget, type Client, type CreateBankRequest, type EntityInput, type FileRetainResponse, HindsightClient, type HindsightClientOptions, HindsightError, type ListMemoryUnitsResponse, type MemoryItemInput, type RecallRequest, type RecallResponse, type RecallResult, type ReflectRequest, type ReflectResponse, type RetainRequest, type RetainResponse, createClient, createConfig, sdk_gen as sdk };
+export { type BankConfigResponse, type BankProfileResponse, type Budget, type Client, type CreateBankRequest, type EntityInput, type FileRetainResponse, HindsightClient, type HindsightClientOptions, HindsightError, type ListMemoryUnitsResponse, type MemoryItemInput, type RecallRequest, type RecallResponse, type RecallResult, type ReflectRequest, type ReflectResponse, type RetainRequest, type RetainResponse, createClient, createConfig, recallResponseToPromptString, sdk_gen as sdk };