hazo_files 1.4.2 → 1.4.3

package/README.md

@@ -18,7 +18,8 @@ A powerful, modular file management package for Node.js and React applications w
 - **Upload + Extract Workflow**: Combined service for uploading files with automatic LLM extraction and naming
 - **File Reference Tracking**: Multi-entity file references with orphan detection, soft delete, and lifecycle management
 - **File Change Detection**: xxHash-based content hashing for efficient change detection
-- **Schema Migrations**: Built-in V2 migration utilities for adding reference tracking to existing databases
+- **Content Tagging**: Optional LLM-based content classification at upload time or on-demand via `content_tag` field
+- **Schema Migrations**: Built-in V2/V3 migration utilities for adding reference tracking and content tagging to existing databases
 - **TypeScript**: Full type safety and IntelliSense support
 - **OAuth Integration**: Built-in Google Drive OAuth authentication
 - **Progress Tracking**: Upload/download progress callbacks
@@ -1108,11 +1109,17 @@ const extractionService = new LLMExtractionService((provider, options) => {
   return createLLM({ provider, ...options });
 }, 'gemini');
 
-// Create upload + extract service
+// Create upload + extract service (with optional content tag config)
 const uploadExtract = new UploadExtractService(
   trackedFileManager,
   namingService,
-  extractionService
+  extractionService,
+  {
+    content_tag_set_by_llm: true,
+    content_tag_prompt_area: 'classification',
+    content_tag_prompt_key: 'classify_document',
+    content_tag_prompt_return_fieldname: 'document_type',
+  }
 );
 
 // Upload with extraction and naming convention
@@ -1140,6 +1147,8 @@ if (result.success) {
   console.log('Uploaded to:', result.generatedPath);
   // e.g., '/documents/2024/ACME/ACME_Q4_2024-12-09_001.pdf'
   console.log('Extracted data:', result.extraction?.data);
+  console.log('Content tag:', result.contentTag);
+  // e.g., 'invoice', 'report', 'contract'
 }
 
 // Generate path preview without uploading
@@ -1194,6 +1203,74 @@ const autoResult = await extractionService.extract(
 );
 ```
 
+## Content Tagging
+
+Automatically classify uploaded files using LLM-based content analysis. The `content_tag` field stores a classification string (e.g., "invoice", "report", "contract") determined by an LLM prompt.
+
+### Configuration
+
+```typescript
+import type { ContentTagConfig } from 'hazo_files';
+
+const contentTagConfig: ContentTagConfig = {
+  content_tag_set_by_llm: true,
+  content_tag_prompt_area: 'classification',
+  content_tag_prompt_key: 'classify_document',
+  content_tag_prompt_return_fieldname: 'document_type',
+  content_tag_prompt_variables: { language: 'en' }, // optional
+};
+```
+
+### Automatic Tagging at Upload
+
+Pass `contentTagConfig` to `UploadExtractService` constructor (default for all uploads) or per-upload via options:
+
+```typescript
+// Per-upload override
+const result = await uploadExtract.uploadWithExtract(buffer, 'file.pdf', {
+  basePath: '/docs',
+  contentTagConfig: {
+    content_tag_set_by_llm: true,
+    content_tag_prompt_area: 'classification',
+    content_tag_prompt_key: 'classify_document',
+    content_tag_prompt_return_fieldname: 'document_type',
+  },
+});
+console.log(result.contentTag); // e.g., 'invoice'
+```
+
+### Manual Tagging
+
+Tag existing files by their database record ID:
+
+```typescript
+const tagResult = await uploadExtract.tagFileContent('file-record-id');
+if (tagResult.success) {
+  console.log('Tagged as:', tagResult.data);
+}
+```
+
+### V3 Database Migration
+
+If you have an existing `hazo_files` table, run the V3 migration to add the `content_tag` column:
+
+```typescript
+import { migrateToV3, HAZO_FILES_MIGRATION_V3 } from 'hazo_files';
+
+// Using the migration helper
+await migrateToV3(
+  { run: (sql) => db.run(sql) },
+  'sqlite'
+);
+
+// Or run statements manually
+for (const stmt of HAZO_FILES_MIGRATION_V3.sqlite.alterStatements) {
+  try { await db.run(stmt); } catch { /* column exists */ }
+}
+```
+
+New tables created with `HAZO_FILES_TABLE_SCHEMA` already include the `content_tag` column.
+
 ## File Reference Tracking
 
 Track which entities (form fields, chat messages, etc.) reference each file. Multiple entities can reference the same file, enabling shared files without duplication.
@@ -1274,7 +1351,7 @@ for (const idx of HAZO_FILES_MIGRATION_V2.sqlite.indexes) {
 }
 ```
 
-New tables created with `HAZO_FILES_TABLE_SCHEMA` already include V2 columns.
+New tables created with `HAZO_FILES_TABLE_SCHEMA` already include V2 columns. For V3 content tagging migration, see [Content Tagging](#content-tagging) above.
 
 ### Reference Tracking Types
 
@@ -1333,6 +1410,13 @@ const hazoFiles = await createHazoFilesServer({
   },
   enableTracking: true,
   llmFactory: (provider) => createLLM({ provider }),
+  // Optional: enable automatic content tagging for all uploads
+  defaultContentTagConfig: {
+    content_tag_set_by_llm: true,
+    content_tag_prompt_area: 'classification',
+    content_tag_prompt_key: 'classify_document',
+    content_tag_prompt_return_fieldname: 'document_type',
+  },
 });
 
 // Access all services

package/dist/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;
 
 /**
  * Configuration loader for hazo_files
@@ -1743,6 +1787,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
@@ -1925,6 +1971,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)
@@ -1967,6 +2053,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
  */
@@ -2782,4 +2895,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 HazoFilesTableSchema, type HazoLLMInstance, 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, createEmptyFileDataStructure, createEmptyNamingRuleSchema, createFileItem, createFileManager, createFileMetadataService, createFileRef, createFolderItem, createGoogleDriveAuth, createGoogleDriveModule, 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 HazoFilesTableSchema, type HazoLLMInstance, 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, createEmptyFileDataStructure, createEmptyNamingRuleSchema, createFileItem, createFileManager, createFileMetadataService, createFileRef, createFolderItem, createGoogleDriveAuth, createGoogleDriveModule, 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/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;
 
 /**
  * Configuration loader for hazo_files
@@ -1743,6 +1787,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
@@ -1925,6 +1971,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)
@@ -1967,6 +2053,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
  */
@@ -2782,4 +2895,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 HazoFilesTableSchema, type HazoLLMInstance, 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, createEmptyFileDataStructure, createEmptyNamingRuleSchema, createFileItem, createFileManager, createFileMetadataService, createFileRef, createFolderItem, createGoogleDriveAuth, createGoogleDriveModule, 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 HazoFilesTableSchema, type HazoLLMInstance, 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, createEmptyFileDataStructure, createEmptyNamingRuleSchema, createFileItem, createFileManager, createFileMetadataService, createFileRef, createFolderItem, createGoogleDriveAuth, createGoogleDriveModule, 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 };