hazo_files 1.4.2 → 1.4.3

package/dist/server/index.d.mts

@@ -185,6 +185,8 @@ interface FileMetadataInput {
     uploaded_by?: string;
     /** Original filename at upload time (V2) */
     original_filename?: string;
+    /** Content tag classifying the document type (V3) */
+    content_tag?: string;
 }
 /**
  * Input for updating an existing metadata record
@@ -258,6 +260,23 @@ interface RemoveExtractionOptions {
     /** Merge strategy to use when recalculating (default: 'shallow') */
     mergeStrategy?: 'shallow' | 'deep';
 }
+/**
+ * Configuration for LLM-based content tagging.
+ * When enabled, calls the LLM with a specific prompt and writes
+ * the extracted field value to the content_tag column.
+ */
+interface ContentTagConfig {
+    /** Whether to enable LLM-based content tagging */
+    content_tag_set_by_llm: boolean;
+    /** Prompt area for hazo_llm_api lookup */
+    content_tag_prompt_area: string;
+    /** Prompt key within the area */
+    content_tag_prompt_key: string;
+    /** Optional variables to substitute in the prompt template */
+    content_tag_prompt_variables?: Record<string, string>;
+    /** Field name to extract from the LLM response as the content tag */
+    content_tag_prompt_return_fieldname: string;
+}
 
 /**
  * Naming convention types for hazo_files
@@ -412,6 +431,8 @@ interface FileMetadataRecordV2 extends FileMetadataRecord {
     storage_verified_at?: string | null;
     /** ISO timestamp when file was soft-deleted */
     deleted_at?: string | null;
+    /** Content tag classifying the document type (V3) */
+    content_tag?: string | null;
 }
 /**
  * Options for adding a reference to a file
@@ -1004,7 +1025,7 @@ declare class FileMetadataService {
     /**
      * Update specific V2 fields on a record
      */
-    updateFields(fileId: string, fields: Partial<Pick<FileMetadataRecordV2, 'scope_id' | 'uploaded_by' | 'original_filename' | 'storage_verified_at' | 'status'>>): Promise<boolean>;
+    updateFields(fileId: string, fields: Partial<Pick<FileMetadataRecordV2, 'scope_id' | 'uploaded_by' | 'original_filename' | 'storage_verified_at' | 'status' | 'content_tag'>>): Promise<boolean>;
     /**
      * Find orphaned files (zero references)
      */
@@ -1532,6 +1553,11 @@ interface UploadExtractOptions extends TrackedUploadOptions {
      * Whether to create the folder path if it doesn't exist
      */
     createFolders?: boolean;
+    /**
+     * Content tag configuration for this upload.
+     * Overrides the default config set on the service.
+     */
+    contentTagConfig?: ContentTagConfig;
 }
 /**
  * Result of upload with extraction
@@ -1551,6 +1577,8 @@ interface UploadExtractResult {
     generatedFolderPath?: string;
     /** Original file name before renaming */
     originalFileName?: string;
+    /** Content tag assigned by LLM (if content tagging was performed) */
+    contentTag?: string;
 }
 /**
  * Options for creating folders from naming convention
@@ -1608,7 +1636,8 @@ declare class UploadExtractService {
     private fileManager;
     private namingService?;
     private extractionService?;
-    constructor(fileManager: TrackedFileManager, namingService?: NamingConventionService, extractionService?: LLMExtractionService);
+    private defaultContentTagConfig?;
+    constructor(fileManager: TrackedFileManager, namingService?: NamingConventionService, extractionService?: LLMExtractionService, defaultContentTagConfig?: ContentTagConfig);
     /**
      * Upload a file with optional extraction and naming convention
      */
@@ -1633,6 +1662,21 @@ declare class UploadExtractService {
         fullPath?: string;
         folderPath?: string;
     }>;
+    /**
+     * Perform content tagging via LLM extraction.
+     * Calls the LLM with the configured prompt, extracts the specified field,
+     * and writes it to the content_tag column.
+     */
+    private performContentTagging;
+    /**
+     * Manually tag a file's content via LLM.
+     * Works with existing DB records, resolving the file path internally.
+     *
+     * @param fileId - Database record ID of the file
+     * @param config - Content tag config (falls back to default if not provided)
+     * @returns OperationResult with the tag value
+     */
+    tagFileContent(fileId: string, config?: ContentTagConfig): Promise<OperationResult<string>>;
     /**
      * Get the file manager
      */
@@ -1649,7 +1693,7 @@ declare class UploadExtractService {
 /**
  * Create an UploadExtractService instance
  */
-declare function createUploadExtractService(fileManager: TrackedFileManager, namingService?: NamingConventionService, extractionService?: LLMExtractionService): UploadExtractService;
+declare function createUploadExtractService(fileManager: TrackedFileManager, namingService?: NamingConventionService, extractionService?: LLMExtractionService, defaultContentTagConfig?: ContentTagConfig): UploadExtractService;
 
 /**
  * Server Factory
@@ -1723,6 +1767,11 @@ interface HazoFilesServerOptions {
      * Track download/access operations
      */
     trackDownloads?: boolean;
+    /**
+     * Default content tag configuration for LLM-based content classification.
+     * When set, uploads can automatically classify document content.
+     */
+    defaultContentTagConfig?: ContentTagConfig;
 }
 /**
  * Result of createHazoFilesServer
@@ -1863,6 +1912,8 @@ interface HazoFilesColumnDefinitions {
     deleted_at: 'TEXT' | 'TIMESTAMP';
     /** Original filename at upload time (V2) */
     original_filename: 'TEXT';
+    /** Content tag classifying the document type (V3) */
+    content_tag: 'TEXT';
 }
 /**
  * Schema definition for a specific database type
@@ -2045,6 +2096,46 @@ declare const HAZO_FILES_NAMING_TABLE_SCHEMA: HazoFilesNamingTableSchema;
  * Get DDL for a custom naming table name
  */
 declare function getNamingSchemaForTable(tableName: string, dbType: 'sqlite' | 'postgres'): DatabaseSchemaDefinition;
+/**
+ * Migration schema for adding V3 content tagging column to existing tables.
+ * Idempotent — safe to run multiple times.
+ *
+ * @example
+ * ```typescript
+ * import { HAZO_FILES_MIGRATION_V3 } from 'hazo_files';
+ *
+ * // SQLite
+ * for (const stmt of HAZO_FILES_MIGRATION_V3.sqlite.alterStatements) {
+ *   try { await db.run(stmt); } catch { /* column already exists *\/ }
+ * }
+ * for (const idx of HAZO_FILES_MIGRATION_V3.sqlite.indexes) {
+ *   await db.run(idx);
+ * }
+ *
+ * // PostgreSQL
+ * for (const stmt of HAZO_FILES_MIGRATION_V3.postgres.alterStatements) {
+ *   await client.query(stmt);
+ * }
+ * for (const idx of HAZO_FILES_MIGRATION_V3.postgres.indexes) {
+ *   await client.query(idx);
+ * }
+ * ```
+ */
+interface HazoFilesMigrationV3 {
+    /** Default table name */
+    tableName: string;
+    /** SQLite migration statements */
+    sqlite: MigrationSchemaDefinition;
+    /** PostgreSQL migration statements */
+    postgres: MigrationSchemaDefinition;
+    /** New column names added in V3 */
+    newColumns: readonly string[];
+}
+declare const HAZO_FILES_MIGRATION_V3: HazoFilesMigrationV3;
+/**
+ * Get V3 migration statements for a custom table name
+ */
+declare function getMigrationV3ForTable(tableName: string, dbType: 'sqlite' | 'postgres'): MigrationSchemaDefinition;
 
 /**
  * Migration: Add Reference Tracking (V2)
@@ -2087,6 +2178,33 @@ declare function migrateToV2(executor: MigrationExecutor, dbType: 'sqlite' | 'po
  */
 declare function backfillV2Defaults(executor: MigrationExecutor, dbType: 'sqlite' | 'postgres', tableName?: string): Promise<void>;
 
+/**
+ * Migration: Add Content Tag (V3)
+ *
+ * Adds content_tag column to an existing hazo_files table.
+ * Idempotent — safe to run multiple times.
+ */
+
+/**
+ * Run the V3 migration: add content_tag column and index.
+ *
+ * @param executor - Object with a `run(sql)` method
+ * @param dbType - Database type ('sqlite' | 'postgres')
+ * @param tableName - Custom table name (defaults to 'hazo_files')
+ *
+ * @example
+ * ```typescript
+ * import { migrateToV3 } from 'hazo_files';
+ *
+ * // SQLite with better-sqlite3
+ * await migrateToV3({ run: (sql) => db.exec(sql) }, 'sqlite');
+ *
+ * // PostgreSQL with pg
+ * await migrateToV3({ run: (sql) => client.query(sql) }, 'postgres');
+ * ```
+ */
+declare function migrateToV3(executor: MigrationExecutor, dbType: 'sqlite' | 'postgres', tableName?: string): Promise<void>;
+
 /**
  * Common utility functions
  */
@@ -2929,4 +3047,4 @@ declare function toV2Record(record: FileMetadataRecord): FileMetadataRecordV2;
  */
 declare function buildFileWithStatus(record: FileMetadataRecord): FileWithStatus;
 
-export { ALL_SYSTEM_VARIABLES, type AddExtractionOptions, type AddRefOptions, type AuthCallbacks, AuthenticationError, type CleanupOrphanedOptions, ConfigurationError, type CreateFolderOptions, type CrudServiceLike, DEFAULT_DATE_FORMATS, type DatabaseSchemaDefinition, type DatabaseTrackingConfig, DirectoryExistsError, DirectoryNotEmptyError, DirectoryNotFoundError, type DownloadOptions, type ExtractionData, type ExtractionOptions, type ExtractionResult, type FileBrowserState, type FileDataStructure, FileExistsError, type FileInfo, type FileItem, FileManager, type FileManagerOptions, type FileMetadataInput, type FileMetadataRecord, type FileMetadataRecordV2, FileMetadataService, type FileMetadataServiceOptions, type FileMetadataUpdate, FileNotFoundError, type FileRef, type FileRefVisibility, type FileStatus, type FileSystemItem, FileTooLargeError, type FileWithStatus, type FindOrphanedOptions, type FolderItem, type GeneratedNameResult, type GoogleAuthConfig, GoogleDriveAuth, type GoogleDriveConfig, GoogleDriveModule, HAZO_FILES_DEFAULT_TABLE_NAME, HAZO_FILES_MIGRATION_V2, HAZO_FILES_NAMING_DEFAULT_TABLE_NAME, HAZO_FILES_NAMING_TABLE_SCHEMA, HAZO_FILES_TABLE_SCHEMA, type HazoFilesColumnDefinitions, type HazoFilesConfig, HazoFilesError, type HazoFilesMigrationV2, type HazoFilesNamingColumnDefinitions, type HazoFilesNamingTableSchema, type HazoFilesServerInstance, type HazoFilesServerOptions, type HazoFilesTableSchema, type HazoLLMInstance, type HazoLogger, InvalidExtensionError, InvalidPathError, LLMExtractionService, type LLMFactory, type LLMProvider, type ListNamingConventionsOptions, type ListOptions, type LocalStorageConfig, LocalStorageModule, type MetadataLogger, type MigrationExecutor, type MigrationSchemaDefinition, type MoveOptions, type NameGenerationOptions, type NamingConventionInput, type NamingConventionRecord, NamingConventionService, type NamingConventionServiceOptions, type NamingConventionType, type NamingConventionUpdate, type NamingRuleConfiguratorProps, type NamingRuleHistoryEntry, type NamingRuleSchema, type NamingVariable, OperationError, type OperationResult, type ParsedNamingConvention, type PatternSegment, PermissionDeniedError, type ProgressCallback, type RemoveExtractionOptions, type RemoveRefsCriteria, type RenameOptions, SYSTEM_COUNTER_VARIABLES, SYSTEM_DATE_VARIABLES, SYSTEM_FILE_VARIABLES, type StorageModule, type StorageProvider, type TokenData, TrackedFileManager, type TrackedFileManagerFullOptions, type TrackedFileManagerOptions, type TrackedUploadOptions, type TreeNode, type UploadExtractOptions, type UploadExtractResult, UploadExtractService, type UploadOptions, type UploadWithRefOptions, type UseNamingRuleActions, type UseNamingRuleReturn, type UseNamingRuleState, type VariableCategory, addExtractionToFileData, backfillV2Defaults, buildFileWithStatus, clearExtractions, clonePattern, computeFileHash, computeFileHashFromStream, computeFileHashSync, computeFileInfo, createAndInitializeModule, createBasicFileManager, createEmptyFileDataStructure, createEmptyNamingRuleSchema, createFileItem, createFileManager, createFileMetadataService, createFileRef, createFolderItem, createGoogleDriveAuth, createGoogleDriveModule, createHazoFilesServer, createInitializedFileManager, createInitializedTrackedFileManager, createLLMExtractionService, createLiteralSegment, createLocalModule, createModule, createNamingConventionService, createTrackedFileManager, createUploadExtractService, createVariableSegment, deepMerge, errorResult, filterItems, formatBytes, formatCounter, formatDateToken, generateExtractionId, generateId, generatePreviewName, generateRefId, generateSampleConfig, generateSegmentId, getBaseName, getBreadcrumbs, getDirName, getExtension, getExtensionFromMime, getExtractionById, getExtractionCount, getExtractions, getFileCategory, getFileMetadataValues, getMergedData, getMigrationForTable, getMimeType, getNameWithoutExtension, getNamingSchemaForTable, getParentPath, getPathSegments, getRegisteredProviders, getRelativePath, getSchemaForTable, getSystemVariablePreviewValues, hasExtension, hasExtractionStructure, hasFileContentChanged, hashesEqual, hazo_files_generate_file_name, hazo_files_generate_folder_name, isAudio, isChildPath, isCounterVariable, isDateVariable, isDocument, isFile, isFileMetadataVariable, isFolder, isImage, isPreviewable, isProviderRegistered, isText, isVideo, joinPath, loadConfig, loadConfigAsync, migrateToV2, normalizePath, parseConfig, parseFileData, parseFileRefs, parsePatternString, patternToString, recalculateMergedData, registerModule, removeExtractionById, removeExtractionByIndex, removeRefFromArray, removeRefsByCriteriaFromArray, sanitizeFilename, saveConfig, sortItems, stringifyFileData, stringifyFileRefs, successResult, toV2Record, updateExtractionById, validateExtractionData, validateFileDataStructure, validateNamingRuleSchema, validatePath };
+export { ALL_SYSTEM_VARIABLES, type AddExtractionOptions, type AddRefOptions, type AuthCallbacks, AuthenticationError, type CleanupOrphanedOptions, ConfigurationError, type ContentTagConfig, type CreateFolderOptions, type CrudServiceLike, DEFAULT_DATE_FORMATS, type DatabaseSchemaDefinition, type DatabaseTrackingConfig, DirectoryExistsError, DirectoryNotEmptyError, DirectoryNotFoundError, type DownloadOptions, type ExtractionData, type ExtractionOptions, type ExtractionResult, type FileBrowserState, type FileDataStructure, FileExistsError, type FileInfo, type FileItem, FileManager, type FileManagerOptions, type FileMetadataInput, type FileMetadataRecord, type FileMetadataRecordV2, FileMetadataService, type FileMetadataServiceOptions, type FileMetadataUpdate, FileNotFoundError, type FileRef, type FileRefVisibility, type FileStatus, type FileSystemItem, FileTooLargeError, type FileWithStatus, type FindOrphanedOptions, type FolderItem, type GeneratedNameResult, type GoogleAuthConfig, GoogleDriveAuth, type GoogleDriveConfig, GoogleDriveModule, HAZO_FILES_DEFAULT_TABLE_NAME, HAZO_FILES_MIGRATION_V2, HAZO_FILES_MIGRATION_V3, HAZO_FILES_NAMING_DEFAULT_TABLE_NAME, HAZO_FILES_NAMING_TABLE_SCHEMA, HAZO_FILES_TABLE_SCHEMA, type HazoFilesColumnDefinitions, type HazoFilesConfig, HazoFilesError, type HazoFilesMigrationV2, type HazoFilesMigrationV3, type HazoFilesNamingColumnDefinitions, type HazoFilesNamingTableSchema, type HazoFilesServerInstance, type HazoFilesServerOptions, type HazoFilesTableSchema, type HazoLLMInstance, type HazoLogger, InvalidExtensionError, InvalidPathError, LLMExtractionService, type LLMFactory, type LLMProvider, type ListNamingConventionsOptions, type ListOptions, type LocalStorageConfig, LocalStorageModule, type MetadataLogger, type MigrationExecutor, type MigrationSchemaDefinition, type MoveOptions, type NameGenerationOptions, type NamingConventionInput, type NamingConventionRecord, NamingConventionService, type NamingConventionServiceOptions, type NamingConventionType, type NamingConventionUpdate, type NamingRuleConfiguratorProps, type NamingRuleHistoryEntry, type NamingRuleSchema, type NamingVariable, OperationError, type OperationResult, type ParsedNamingConvention, type PatternSegment, PermissionDeniedError, type ProgressCallback, type RemoveExtractionOptions, type RemoveRefsCriteria, type RenameOptions, SYSTEM_COUNTER_VARIABLES, SYSTEM_DATE_VARIABLES, SYSTEM_FILE_VARIABLES, type StorageModule, type StorageProvider, type TokenData, TrackedFileManager, type TrackedFileManagerFullOptions, type TrackedFileManagerOptions, type TrackedUploadOptions, type TreeNode, type UploadExtractOptions, type UploadExtractResult, UploadExtractService, type UploadOptions, type UploadWithRefOptions, type UseNamingRuleActions, type UseNamingRuleReturn, type UseNamingRuleState, type VariableCategory, addExtractionToFileData, backfillV2Defaults, buildFileWithStatus, clearExtractions, clonePattern, computeFileHash, computeFileHashFromStream, computeFileHashSync, computeFileInfo, createAndInitializeModule, createBasicFileManager, createEmptyFileDataStructure, createEmptyNamingRuleSchema, createFileItem, createFileManager, createFileMetadataService, createFileRef, createFolderItem, createGoogleDriveAuth, createGoogleDriveModule, createHazoFilesServer, createInitializedFileManager, createInitializedTrackedFileManager, createLLMExtractionService, createLiteralSegment, createLocalModule, createModule, createNamingConventionService, createTrackedFileManager, createUploadExtractService, createVariableSegment, deepMerge, errorResult, filterItems, formatBytes, formatCounter, formatDateToken, generateExtractionId, generateId, generatePreviewName, generateRefId, generateSampleConfig, generateSegmentId, getBaseName, getBreadcrumbs, getDirName, getExtension, getExtensionFromMime, getExtractionById, getExtractionCount, getExtractions, getFileCategory, getFileMetadataValues, getMergedData, getMigrationForTable, getMigrationV3ForTable, getMimeType, getNameWithoutExtension, getNamingSchemaForTable, getParentPath, getPathSegments, getRegisteredProviders, getRelativePath, getSchemaForTable, getSystemVariablePreviewValues, hasExtension, hasExtractionStructure, hasFileContentChanged, hashesEqual, hazo_files_generate_file_name, hazo_files_generate_folder_name, isAudio, isChildPath, isCounterVariable, isDateVariable, isDocument, isFile, isFileMetadataVariable, isFolder, isImage, isPreviewable, isProviderRegistered, isText, isVideo, joinPath, loadConfig, loadConfigAsync, migrateToV2, migrateToV3, normalizePath, parseConfig, parseFileData, parseFileRefs, parsePatternString, patternToString, recalculateMergedData, registerModule, removeExtractionById, removeExtractionByIndex, removeRefFromArray, removeRefsByCriteriaFromArray, sanitizeFilename, saveConfig, sortItems, stringifyFileData, stringifyFileRefs, successResult, toV2Record, updateExtractionById, validateExtractionData, validateFileDataStructure, validateNamingRuleSchema, validatePath };

package/dist/server/index.d.ts

@@ -185,6 +185,8 @@ interface FileMetadataInput {
     uploaded_by?: string;
     /** Original filename at upload time (V2) */
     original_filename?: string;
+    /** Content tag classifying the document type (V3) */
+    content_tag?: string;
 }
 /**
  * Input for updating an existing metadata record
@@ -258,6 +260,23 @@ interface RemoveExtractionOptions {
     /** Merge strategy to use when recalculating (default: 'shallow') */
     mergeStrategy?: 'shallow' | 'deep';
 }
+/**
+ * Configuration for LLM-based content tagging.
+ * When enabled, calls the LLM with a specific prompt and writes
+ * the extracted field value to the content_tag column.
+ */
+interface ContentTagConfig {
+    /** Whether to enable LLM-based content tagging */
+    content_tag_set_by_llm: boolean;
+    /** Prompt area for hazo_llm_api lookup */
+    content_tag_prompt_area: string;
+    /** Prompt key within the area */
+    content_tag_prompt_key: string;
+    /** Optional variables to substitute in the prompt template */
+    content_tag_prompt_variables?: Record<string, string>;
+    /** Field name to extract from the LLM response as the content tag */
+    content_tag_prompt_return_fieldname: string;
+}
 
 /**
  * Naming convention types for hazo_files
@@ -412,6 +431,8 @@ interface FileMetadataRecordV2 extends FileMetadataRecord {
     storage_verified_at?: string | null;
     /** ISO timestamp when file was soft-deleted */
     deleted_at?: string | null;
+    /** Content tag classifying the document type (V3) */
+    content_tag?: string | null;
 }
 /**
  * Options for adding a reference to a file
@@ -1004,7 +1025,7 @@ declare class FileMetadataService {
     /**
      * Update specific V2 fields on a record
      */
-    updateFields(fileId: string, fields: Partial<Pick<FileMetadataRecordV2, 'scope_id' | 'uploaded_by' | 'original_filename' | 'storage_verified_at' | 'status'>>): Promise<boolean>;
+    updateFields(fileId: string, fields: Partial<Pick<FileMetadataRecordV2, 'scope_id' | 'uploaded_by' | 'original_filename' | 'storage_verified_at' | 'status' | 'content_tag'>>): Promise<boolean>;
     /**
      * Find orphaned files (zero references)
      */
@@ -1532,6 +1553,11 @@ interface UploadExtractOptions extends TrackedUploadOptions {
      * Whether to create the folder path if it doesn't exist
      */
     createFolders?: boolean;
+    /**
+     * Content tag configuration for this upload.
+     * Overrides the default config set on the service.
+     */
+    contentTagConfig?: ContentTagConfig;
 }
 /**
  * Result of upload with extraction
@@ -1551,6 +1577,8 @@ interface UploadExtractResult {
     generatedFolderPath?: string;
     /** Original file name before renaming */
     originalFileName?: string;
+    /** Content tag assigned by LLM (if content tagging was performed) */
+    contentTag?: string;
 }
 /**
  * Options for creating folders from naming convention
@@ -1608,7 +1636,8 @@ declare class UploadExtractService {
     private fileManager;
     private namingService?;
     private extractionService?;
-    constructor(fileManager: TrackedFileManager, namingService?: NamingConventionService, extractionService?: LLMExtractionService);
+    private defaultContentTagConfig?;
+    constructor(fileManager: TrackedFileManager, namingService?: NamingConventionService, extractionService?: LLMExtractionService, defaultContentTagConfig?: ContentTagConfig);
     /**
      * Upload a file with optional extraction and naming convention
      */
@@ -1633,6 +1662,21 @@ declare class UploadExtractService {
         fullPath?: string;
         folderPath?: string;
     }>;
+    /**
+     * Perform content tagging via LLM extraction.
+     * Calls the LLM with the configured prompt, extracts the specified field,
+     * and writes it to the content_tag column.
+     */
+    private performContentTagging;
+    /**
+     * Manually tag a file's content via LLM.
+     * Works with existing DB records, resolving the file path internally.
+     *
+     * @param fileId - Database record ID of the file
+     * @param config - Content tag config (falls back to default if not provided)
+     * @returns OperationResult with the tag value
+     */
+    tagFileContent(fileId: string, config?: ContentTagConfig): Promise<OperationResult<string>>;
     /**
      * Get the file manager
      */
@@ -1649,7 +1693,7 @@ declare class UploadExtractService {
 /**
  * Create an UploadExtractService instance
  */
-declare function createUploadExtractService(fileManager: TrackedFileManager, namingService?: NamingConventionService, extractionService?: LLMExtractionService): UploadExtractService;
+declare function createUploadExtractService(fileManager: TrackedFileManager, namingService?: NamingConventionService, extractionService?: LLMExtractionService, defaultContentTagConfig?: ContentTagConfig): UploadExtractService;
 
 /**
  * Server Factory
@@ -1723,6 +1767,11 @@ interface HazoFilesServerOptions {
      * Track download/access operations
      */
     trackDownloads?: boolean;
+    /**
+     * Default content tag configuration for LLM-based content classification.
+     * When set, uploads can automatically classify document content.
+     */
+    defaultContentTagConfig?: ContentTagConfig;
 }
 /**
  * Result of createHazoFilesServer
@@ -1863,6 +1912,8 @@ interface HazoFilesColumnDefinitions {
     deleted_at: 'TEXT' | 'TIMESTAMP';
     /** Original filename at upload time (V2) */
     original_filename: 'TEXT';
+    /** Content tag classifying the document type (V3) */
+    content_tag: 'TEXT';
 }
 /**
  * Schema definition for a specific database type
@@ -2045,6 +2096,46 @@ declare const HAZO_FILES_NAMING_TABLE_SCHEMA: HazoFilesNamingTableSchema;
  * Get DDL for a custom naming table name
  */
 declare function getNamingSchemaForTable(tableName: string, dbType: 'sqlite' | 'postgres'): DatabaseSchemaDefinition;
+/**
+ * Migration schema for adding V3 content tagging column to existing tables.
+ * Idempotent — safe to run multiple times.
+ *
+ * @example
+ * ```typescript
+ * import { HAZO_FILES_MIGRATION_V3 } from 'hazo_files';
+ *
+ * // SQLite
+ * for (const stmt of HAZO_FILES_MIGRATION_V3.sqlite.alterStatements) {
+ *   try { await db.run(stmt); } catch { /* column already exists *\/ }
+ * }
+ * for (const idx of HAZO_FILES_MIGRATION_V3.sqlite.indexes) {
+ *   await db.run(idx);
+ * }
+ *
+ * // PostgreSQL
+ * for (const stmt of HAZO_FILES_MIGRATION_V3.postgres.alterStatements) {
+ *   await client.query(stmt);
+ * }
+ * for (const idx of HAZO_FILES_MIGRATION_V3.postgres.indexes) {
+ *   await client.query(idx);
+ * }
+ * ```
+ */
+interface HazoFilesMigrationV3 {
+    /** Default table name */
+    tableName: string;
+    /** SQLite migration statements */
+    sqlite: MigrationSchemaDefinition;
+    /** PostgreSQL migration statements */
+    postgres: MigrationSchemaDefinition;
+    /** New column names added in V3 */
+    newColumns: readonly string[];
+}
+declare const HAZO_FILES_MIGRATION_V3: HazoFilesMigrationV3;
+/**
+ * Get V3 migration statements for a custom table name
+ */
+declare function getMigrationV3ForTable(tableName: string, dbType: 'sqlite' | 'postgres'): MigrationSchemaDefinition;
 
 /**
  * Migration: Add Reference Tracking (V2)
@@ -2087,6 +2178,33 @@ declare function migrateToV2(executor: MigrationExecutor, dbType: 'sqlite' | 'po
  */
 declare function backfillV2Defaults(executor: MigrationExecutor, dbType: 'sqlite' | 'postgres', tableName?: string): Promise<void>;
 
+/**
+ * Migration: Add Content Tag (V3)
+ *
+ * Adds content_tag column to an existing hazo_files table.
+ * Idempotent — safe to run multiple times.
+ */
+
+/**
+ * Run the V3 migration: add content_tag column and index.
+ *
+ * @param executor - Object with a `run(sql)` method
+ * @param dbType - Database type ('sqlite' | 'postgres')
+ * @param tableName - Custom table name (defaults to 'hazo_files')
+ *
+ * @example
+ * ```typescript
+ * import { migrateToV3 } from 'hazo_files';
+ *
+ * // SQLite with better-sqlite3
+ * await migrateToV3({ run: (sql) => db.exec(sql) }, 'sqlite');
+ *
+ * // PostgreSQL with pg
+ * await migrateToV3({ run: (sql) => client.query(sql) }, 'postgres');
+ * ```
+ */
+declare function migrateToV3(executor: MigrationExecutor, dbType: 'sqlite' | 'postgres', tableName?: string): Promise<void>;
+
 /**
  * Common utility functions
  */
@@ -2929,4 +3047,4 @@ declare function toV2Record(record: FileMetadataRecord): FileMetadataRecordV2;
  */
 declare function buildFileWithStatus(record: FileMetadataRecord): FileWithStatus;
 
-export { ALL_SYSTEM_VARIABLES, type AddExtractionOptions, type AddRefOptions, type AuthCallbacks, AuthenticationError, type CleanupOrphanedOptions, ConfigurationError, type CreateFolderOptions, type CrudServiceLike, DEFAULT_DATE_FORMATS, type DatabaseSchemaDefinition, type DatabaseTrackingConfig, DirectoryExistsError, DirectoryNotEmptyError, DirectoryNotFoundError, type DownloadOptions, type ExtractionData, type ExtractionOptions, type ExtractionResult, type FileBrowserState, type FileDataStructure, FileExistsError, type FileInfo, type FileItem, FileManager, type FileManagerOptions, type FileMetadataInput, type FileMetadataRecord, type FileMetadataRecordV2, FileMetadataService, type FileMetadataServiceOptions, type FileMetadataUpdate, FileNotFoundError, type FileRef, type FileRefVisibility, type FileStatus, type FileSystemItem, FileTooLargeError, type FileWithStatus, type FindOrphanedOptions, type FolderItem, type GeneratedNameResult, type GoogleAuthConfig, GoogleDriveAuth, type GoogleDriveConfig, GoogleDriveModule, HAZO_FILES_DEFAULT_TABLE_NAME, HAZO_FILES_MIGRATION_V2, HAZO_FILES_NAMING_DEFAULT_TABLE_NAME, HAZO_FILES_NAMING_TABLE_SCHEMA, HAZO_FILES_TABLE_SCHEMA, type HazoFilesColumnDefinitions, type HazoFilesConfig, HazoFilesError, type HazoFilesMigrationV2, type HazoFilesNamingColumnDefinitions, type HazoFilesNamingTableSchema, type HazoFilesServerInstance, type HazoFilesServerOptions, type HazoFilesTableSchema, type HazoLLMInstance, type HazoLogger, InvalidExtensionError, InvalidPathError, LLMExtractionService, type LLMFactory, type LLMProvider, type ListNamingConventionsOptions, type ListOptions, type LocalStorageConfig, LocalStorageModule, type MetadataLogger, type MigrationExecutor, type MigrationSchemaDefinition, type MoveOptions, type NameGenerationOptions, type NamingConventionInput, type NamingConventionRecord, NamingConventionService, type NamingConventionServiceOptions, type NamingConventionType, type NamingConventionUpdate, type NamingRuleConfiguratorProps, type NamingRuleHistoryEntry, type NamingRuleSchema, type NamingVariable, OperationError, type OperationResult, type ParsedNamingConvention, type PatternSegment, PermissionDeniedError, type ProgressCallback, type RemoveExtractionOptions, type RemoveRefsCriteria, type RenameOptions, SYSTEM_COUNTER_VARIABLES, SYSTEM_DATE_VARIABLES, SYSTEM_FILE_VARIABLES, type StorageModule, type StorageProvider, type TokenData, TrackedFileManager, type TrackedFileManagerFullOptions, type TrackedFileManagerOptions, type TrackedUploadOptions, type TreeNode, type UploadExtractOptions, type UploadExtractResult, UploadExtractService, type UploadOptions, type UploadWithRefOptions, type UseNamingRuleActions, type UseNamingRuleReturn, type UseNamingRuleState, type VariableCategory, addExtractionToFileData, backfillV2Defaults, buildFileWithStatus, clearExtractions, clonePattern, computeFileHash, computeFileHashFromStream, computeFileHashSync, computeFileInfo, createAndInitializeModule, createBasicFileManager, createEmptyFileDataStructure, createEmptyNamingRuleSchema, createFileItem, createFileManager, createFileMetadataService, createFileRef, createFolderItem, createGoogleDriveAuth, createGoogleDriveModule, createHazoFilesServer, createInitializedFileManager, createInitializedTrackedFileManager, createLLMExtractionService, createLiteralSegment, createLocalModule, createModule, createNamingConventionService, createTrackedFileManager, createUploadExtractService, createVariableSegment, deepMerge, errorResult, filterItems, formatBytes, formatCounter, formatDateToken, generateExtractionId, generateId, generatePreviewName, generateRefId, generateSampleConfig, generateSegmentId, getBaseName, getBreadcrumbs, getDirName, getExtension, getExtensionFromMime, getExtractionById, getExtractionCount, getExtractions, getFileCategory, getFileMetadataValues, getMergedData, getMigrationForTable, getMimeType, getNameWithoutExtension, getNamingSchemaForTable, getParentPath, getPathSegments, getRegisteredProviders, getRelativePath, getSchemaForTable, getSystemVariablePreviewValues, hasExtension, hasExtractionStructure, hasFileContentChanged, hashesEqual, hazo_files_generate_file_name, hazo_files_generate_folder_name, isAudio, isChildPath, isCounterVariable, isDateVariable, isDocument, isFile, isFileMetadataVariable, isFolder, isImage, isPreviewable, isProviderRegistered, isText, isVideo, joinPath, loadConfig, loadConfigAsync, migrateToV2, normalizePath, parseConfig, parseFileData, parseFileRefs, parsePatternString, patternToString, recalculateMergedData, registerModule, removeExtractionById, removeExtractionByIndex, removeRefFromArray, removeRefsByCriteriaFromArray, sanitizeFilename, saveConfig, sortItems, stringifyFileData, stringifyFileRefs, successResult, toV2Record, updateExtractionById, validateExtractionData, validateFileDataStructure, validateNamingRuleSchema, validatePath };
+export { ALL_SYSTEM_VARIABLES, type AddExtractionOptions, type AddRefOptions, type AuthCallbacks, AuthenticationError, type CleanupOrphanedOptions, ConfigurationError, type ContentTagConfig, type CreateFolderOptions, type CrudServiceLike, DEFAULT_DATE_FORMATS, type DatabaseSchemaDefinition, type DatabaseTrackingConfig, DirectoryExistsError, DirectoryNotEmptyError, DirectoryNotFoundError, type DownloadOptions, type ExtractionData, type ExtractionOptions, type ExtractionResult, type FileBrowserState, type FileDataStructure, FileExistsError, type FileInfo, type FileItem, FileManager, type FileManagerOptions, type FileMetadataInput, type FileMetadataRecord, type FileMetadataRecordV2, FileMetadataService, type FileMetadataServiceOptions, type FileMetadataUpdate, FileNotFoundError, type FileRef, type FileRefVisibility, type FileStatus, type FileSystemItem, FileTooLargeError, type FileWithStatus, type FindOrphanedOptions, type FolderItem, type GeneratedNameResult, type GoogleAuthConfig, GoogleDriveAuth, type GoogleDriveConfig, GoogleDriveModule, HAZO_FILES_DEFAULT_TABLE_NAME, HAZO_FILES_MIGRATION_V2, HAZO_FILES_MIGRATION_V3, HAZO_FILES_NAMING_DEFAULT_TABLE_NAME, HAZO_FILES_NAMING_TABLE_SCHEMA, HAZO_FILES_TABLE_SCHEMA, type HazoFilesColumnDefinitions, type HazoFilesConfig, HazoFilesError, type HazoFilesMigrationV2, type HazoFilesMigrationV3, type HazoFilesNamingColumnDefinitions, type HazoFilesNamingTableSchema, type HazoFilesServerInstance, type HazoFilesServerOptions, type HazoFilesTableSchema, type HazoLLMInstance, type HazoLogger, InvalidExtensionError, InvalidPathError, LLMExtractionService, type LLMFactory, type LLMProvider, type ListNamingConventionsOptions, type ListOptions, type LocalStorageConfig, LocalStorageModule, type MetadataLogger, type MigrationExecutor, type MigrationSchemaDefinition, type MoveOptions, type NameGenerationOptions, type NamingConventionInput, type NamingConventionRecord, NamingConventionService, type NamingConventionServiceOptions, type NamingConventionType, type NamingConventionUpdate, type NamingRuleConfiguratorProps, type NamingRuleHistoryEntry, type NamingRuleSchema, type NamingVariable, OperationError, type OperationResult, type ParsedNamingConvention, type PatternSegment, PermissionDeniedError, type ProgressCallback, type RemoveExtractionOptions, type RemoveRefsCriteria, type RenameOptions, SYSTEM_COUNTER_VARIABLES, SYSTEM_DATE_VARIABLES, SYSTEM_FILE_VARIABLES, type StorageModule, type StorageProvider, type TokenData, TrackedFileManager, type TrackedFileManagerFullOptions, type TrackedFileManagerOptions, type TrackedUploadOptions, type TreeNode, type UploadExtractOptions, type UploadExtractResult, UploadExtractService, type UploadOptions, type UploadWithRefOptions, type UseNamingRuleActions, type UseNamingRuleReturn, type UseNamingRuleState, type VariableCategory, addExtractionToFileData, backfillV2Defaults, buildFileWithStatus, clearExtractions, clonePattern, computeFileHash, computeFileHashFromStream, computeFileHashSync, computeFileInfo, createAndInitializeModule, createBasicFileManager, createEmptyFileDataStructure, createEmptyNamingRuleSchema, createFileItem, createFileManager, createFileMetadataService, createFileRef, createFolderItem, createGoogleDriveAuth, createGoogleDriveModule, createHazoFilesServer, createInitializedFileManager, createInitializedTrackedFileManager, createLLMExtractionService, createLiteralSegment, createLocalModule, createModule, createNamingConventionService, createTrackedFileManager, createUploadExtractService, createVariableSegment, deepMerge, errorResult, filterItems, formatBytes, formatCounter, formatDateToken, generateExtractionId, generateId, generatePreviewName, generateRefId, generateSampleConfig, generateSegmentId, getBaseName, getBreadcrumbs, getDirName, getExtension, getExtensionFromMime, getExtractionById, getExtractionCount, getExtractions, getFileCategory, getFileMetadataValues, getMergedData, getMigrationForTable, getMigrationV3ForTable, getMimeType, getNameWithoutExtension, getNamingSchemaForTable, getParentPath, getPathSegments, getRegisteredProviders, getRelativePath, getSchemaForTable, getSystemVariablePreviewValues, hasExtension, hasExtractionStructure, hasFileContentChanged, hashesEqual, hazo_files_generate_file_name, hazo_files_generate_folder_name, isAudio, isChildPath, isCounterVariable, isDateVariable, isDocument, isFile, isFileMetadataVariable, isFolder, isImage, isPreviewable, isProviderRegistered, isText, isVideo, joinPath, loadConfig, loadConfigAsync, migrateToV2, migrateToV3, normalizePath, parseConfig, parseFileData, parseFileRefs, parsePatternString, patternToString, recalculateMergedData, registerModule, removeExtractionById, removeExtractionByIndex, removeRefFromArray, removeRefsByCriteriaFromArray, sanitizeFilename, saveConfig, sortItems, stringifyFileData, stringifyFileRefs, successResult, toV2Record, updateExtractionById, validateExtractionData, validateFileDataStructure, validateNamingRuleSchema, validatePath };