hazo_llm_api 1.0.6 → 1.1.0

package/README.md

@@ -23,6 +23,7 @@ A wrapper package for calling different LLMs with built-in prompt management and
 - **Extensible Architecture**: Provider-based design with simple registration system
 - **Type-Safe**: Full TypeScript support with comprehensive type definitions
 - **Auto-Initialization**: Database initializes automatically on import
+- **File-Based Logging**: Built-in Winston logger with daily file rotation
 
 ## Installation
 
@@ -65,15 +66,22 @@ import {
   hazo_llm_image_text,
   hazo_llm_text_image,
   hazo_llm_image_image,
+  // Built-in Winston logger
+  create_hazo_logger,
+  parse_logging_config,
 } from 'hazo_llm_api/server';
 
-// Create a logger (Winston-compatible)
-const logger = {
-  error: console.error,
-  info: console.log,
-  warn: console.warn,
-  debug: console.debug,
-};
+// Option A: Use built-in Winston logger with file rotation
+const config = parse_logging_config('./config/hazo_llm_api_config.ini');
+const logger = create_hazo_logger(config);
+
+// Option B: Use a simple console logger
+// const logger = {
+//   error: console.error,
+//   info: console.log,
+//   warn: console.warn,
+//   debug: console.debug,
+// };
 
 // Initialize - reads config from config/hazo_llm_api_config.ini
 await initialize_llm_api({ logger });
@@ -439,6 +447,130 @@ const response = await hazo_llm_text_text({
 });
 ```
 
+### Prompt Import/Export Format
+
+The test application supports bulk import/export of prompts via JSON files. This enables backup, migration, and sharing of prompt libraries.
+
+#### Export Format
+
+When exporting prompts, the JSON file follows this structure:
+
+```json
+{
+  "version": "1.0",
+  "exported_at": "2024-01-15T10:30:00.000Z",
+  "prompts": [
+    {
+      "prompt_area": "marketing",
+      "prompt_key": "greeting",
+      "local_1": null,
+      "local_2": null,
+      "local_3": null,
+      "user_id": null,
+      "scope_id": null,
+      "prompt_text": "Hello {{name}}, welcome to {{service}}.",
+      "prompt_variables": [
+        { "name": "name", "description": "Customer name" },
+        { "name": "service", "description": "Service name" }
+      ],
+      "prompt_notes": "Standard greeting for marketing emails"
+    }
+  ]
+}
+```
+
+#### Required Fields for Import
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `prompt_area` | string | Yes | Category/area for the prompt |
+| `prompt_key` | string | Yes | Unique key within the area |
+| `prompt_text` | string | Yes | The prompt template text |
+| `local_1` | string \| null | No | Local filter 1 (e.g., region) |
+| `local_2` | string \| null | No | Local filter 2 (e.g., department) |
+| `local_3` | string \| null | No | Local filter 3 (e.g., sub-category) |
+| `user_id` | string \| null | No | User-specific identifier |
+| `scope_id` | string \| null | No | Scope-specific identifier |
+| `prompt_variables` | array | No | Array of `{ name, description }` objects |
+| `prompt_notes` | string | No | Documentation/notes for the prompt |
+
+#### Import Behavior
+
+- Each imported prompt receives a new UUID automatically
+- `created_at` is set to the import timestamp
+- `changed_at` is set to the import timestamp
+- Duplicate `prompt_area`/`prompt_key` combinations create new entries (no automatic deduplication)
+- Invalid prompts (missing required fields) are skipped with errors reported
+
+#### Bulk Operations UI
+
+The test application's Prompt Configuration page (`/prompt-config`) provides a user interface for bulk operations:
+
+**Selection:**
+- Individual row selection via checkbox
+- Select all/deselect all checkbox in table header
+- Visual indication of selected rows
+
+**Export:**
+1. Select one or more prompts using checkboxes
+2. Click "Export" button (Download icon)
+3. JSON file downloads automatically with filename: `prompts_export_YYYY-MM-DD.json`
+
+**Import:**
+1. Click "Import" button (Upload icon)
+2. Select a JSON file matching the export format
+3. Prompts are validated and imported automatically
+4. Success/error messages display import results
+
+**Delete:**
+1. Select one or more prompts using checkboxes
+2. Click "Delete Selected" button
+3. Confirm deletion in dialog
+4. Selected prompts are removed permanently
+
+#### API Endpoints
+
+The test application provides bulk operation endpoints:
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/api/prompts/bulk` | Import prompts from JSON |
+| `DELETE` | `/api/prompts/bulk` | Delete multiple prompts by ID |
+
+**Import Request:**
+```json
+{
+  "prompts": [
+    { "prompt_area": "...", "prompt_key": "...", "prompt_text": "..." }
+  ]
+}
+```
+
+**Import Response:**
+```json
+{
+  "success": true,
+  "imported_count": 5,
+  "errors": ["Optional array of error messages for failed imports"]
+}
+```
+
+**Delete Request:**
+```json
+{
+  "ids": ["uuid-1", "uuid-2", "uuid-3"]
+}
+```
+
+**Delete Response:**
+```json
+{
+  "success": true,
+  "deleted_count": 3,
+  "errors": ["Optional array of error messages for failed deletions"]
+}
+```
+
 ## Server-Side Only
 
 **Important**: All LLM API functions must be used server-side only.
@@ -510,6 +642,69 @@ if (!response.success) {
 
 ## Configuration
 
+### File-Based Logging (hazo_logs)
+
+The package includes a built-in Winston-based logger with daily file rotation. Configure logging in your `config/hazo_llm_api_config.ini`:
+
+```ini
+[logging]
+# Log file path (relative to config directory parent)
+logfile=logs/hazo_llm_api.log
+# Minimum log level: debug, info, warn, error
+level=info
+# Max file size before rotation (e.g., '10m', '100k')
+max_size=10m
+# Max number of rotated files to keep
+max_files=5
+# Also log to console (true/false)
+console_enabled=true
+```
+
+#### Using the Built-in Logger
+
+```typescript
+import { create_hazo_logger, parse_logging_config } from 'hazo_llm_api/server';
+
+// Parse config from INI file
+const config = parse_logging_config('./config/hazo_llm_api_config.ini');
+
+// Create logger instance
+const logger = create_hazo_logger(config);
+
+// Pass to initialize_llm_api
+await initialize_llm_api({ logger });
+
+// Use directly for application logging
+logger.info('Application started');
+logger.debug('Debug information', { key: 'value' });
+logger.error('Error occurred', { error: err.message });
+```
+
+#### Log Output Format
+
+```
+2026-01-18 08:22:00.885 [INFO] Logger initialized {"config_path":"..."}
+2026-01-18 08:22:01.123 [DEBUG] API call started {"provider":"gemini"}
+2026-01-18 08:22:02.456 [ERROR] Request failed {"error":"timeout"}
+```
+
+#### Log File Rotation
+
+Log files are automatically rotated:
+- Daily rotation with date suffix: `hazo_llm_api-2026-01-18.log`
+- Size-based rotation when `max_size` is exceeded
+- Old files are deleted when `max_files` limit is reached
+
+#### HazoLoggerConfig Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `log_file` | string | Required | Full path to log file |
+| `log_level` | LogLevel | 'info' | Minimum log level (debug, info, warn, error) |
+| `max_size` | string | '10m' | Max file size before rotation |
+| `max_files` | number | 5 | Max rotated files to keep |
+| `console_enabled` | boolean | true | Also log to console |
+
 ### Logger Interface
 
 The logger must implement these methods (Winston-compatible):

package/config/hazo_llm_api_config.ini

@@ -0,0 +1,224 @@
+# Configuration file for hazo_llm_api package
+# All configurable values should be stored here
+
+[logging]
+# Log file path for winston logging
+logfile=logs/hazo_llm_api.log
+# Minimum log level: debug, info, warn, error
+level=info
+# Max file size before rotation (e.g., '10m', '100k')
+max_size=10m
+# Max number of rotated files to keep
+max_files=5
+# Also log to console (true/false)
+console_enabled=true
+
+[package]
+# Package build configuration
+build_dir=dist
+source_dir=src
+
+[test_app]
+# Test application configuration
+port=3000
+host=localhost
+
+[ui]
+# UI component defaults
+default_theme=light
+sidebar_width=256
+
+[llm]
+# LLM API global configuration
+# Comma-separated list of enabled LLM providers (e.g., gemini,openai)
+# Or JSON array format: ["gemini", "openai"]
+enabled_llms=["gemini", "qwen"]
+# Primary/default LLM to use when not specified in function calls
+primary_llm=gemini
+# SQLite database path relative to app root
+sqlite_path=prompt_library.sqlite
+
+# =============================================================================
+# DEPRECATED: Legacy sections below kept for backward compatibility
+# Migrate to new [llm_gemini] section below
+# =============================================================================
+; [gemini]
+; # Legacy: Gemini API configuration - MIGRATED to [llm_gemini] section below
+; api_url=https://generativelanguage.googleapis.com/v1/models/gemini-2.5-flash:generateContent
+; api_url_image=https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-image:generateContent
+
+; [gemini_text_api]
+; # Legacy: Gemini Text API generation configuration - MIGRATED to [llm_gemini] section below
+
+; [gemini_image_api]
+; # Legacy: Gemini Image API generation configuration - MIGRATED to [llm_gemini] section below
+
+[llm_gemini]
+# Gemini Provider Configuration
+# Note: API key must be in .env.local as GEMINI_API_KEY (not in config for security)
+# Base API URL for text generation
+api_url=https://generativelanguage.googleapis.com/v1/models/gemini-2.5-flash:generateContent
+# API URL for image generation (optional, uses api_url if not set)
+api_url_image=https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-image:generateContent
+; api_url_image=https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image-preview:generateContent
+# Per-service model configuration (optional, uses model in URL if not specified)
+# Model for text_text service
+; model_text_text=gemini-2.5-flash
+# Model for image_text service
+; model_image_text=gemini-2.5-flash
+# Model for text_image service
+; model_text_image=gemini-2.5-flash-image
+# Model for image_image service
+; model_image_image=gemini-2.5-flash-image
+# Model for document_text service (PDF analysis)
+; model_document_text=gemini-2.5-flash
+# Capabilities this provider supports (JSON array)
+# Options: text_text, image_text, text_image, image_image, document_text
+capabilities=["text_text", "image_text", "text_image", "image_image", "document_text"]
+# Generation config for text API calls
+# These parameters are optional - only include them in API calls if uncommented
+#
+# temperature - Controls randomness in output (0.0-2.0)
+# Lower values = more deterministic, higher values = more creative
+; text_temperature=0.7
+#
+# maxOutputTokens - Maximum number of tokens in the response
+# Limits response length to control costs and output size
+; text_maxOutputTokens=1024
+#
+# topP - Nucleus sampling probability (0.0-1.0)
+# Considers tokens with cumulative probability up to topP
+; text_topP=0.95
+#
+# topK - Top-k sampling
+# Considers only the top K most probable tokens
+; text_topK=40
+#
+# candidateCount - Number of response candidates to generate
+# Returns multiple alternative responses (1-8)
+; text_candidateCount=1
+#
+# stopSequences - JSON array of sequences that stop generation
+# Generation stops when any of these sequences is encountered
+; text_stopSequences=["###END"]
+#
+# responseMimeType - Format of the response
+# Options: text/plain, application/json
+; text_responseMimeType=text/plain
+# Generation config for image API calls (text_image, image_image, image_text)
+# These parameters are optional - only include them in API calls if uncommented
+#
+# temperature - Controls randomness in output (0.0-2.0)
+# For image analysis, lower values (0.3-0.5) typically provide more accurate descriptions
+image_temperature=0.1
+#
+# maxOutputTokens - Maximum number of tokens in the response
+# For image descriptions, 300-500 is usually sufficient
+; image_maxOutputTokens=300
+#
+# topP - Nucleus sampling probability (0.0-1.0)
+# Considers tokens with cumulative probability up to topP
+; image_topP=0.8
+#
+# topK - Top-k sampling
+# Considers only the top K most probable tokens
+; image_topK=20
+#
+# candidateCount - Number of response candidates to generate
+# Returns multiple alternative responses (1-8)
+; image_candidateCount=1
+#
+# stopSequences - JSON array of sequences that stop generation
+# Generation stops when any of these sequences is encountered
+; image_stopSequences=["###END"]
+#
+# responseMimeType - Format of the response
+# Options: text/plain, application/json
+; image_responseMimeType=text/plain
+
+[llm_qwen]
+# Qwen Provider Configuration
+# Note: API key must be in .env.local as QWEN_API_KEY (not in config for security)
+# Base API URL (default: DashScope endpoint)
+# Used as fallback if service-specific URLs are not configured
+api_url=https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions
+# Per-service model configuration (required for each service you want to use)
+# Model for text_text service (e.g., qwen-max, qwen-plus)
+model_text_text=qwen-max
+# Model for image_text service (e.g., qwen-vl-max, qwen-vl-plus)
+model_image_text=qwen-vl-max
+model_text_image=qwen-image
+; model_image_image=qwen-image-edit
+model_image_image=qwen-image-edit-plus
+# Model for text_image service (if supported)
+; model_text_image=qwen-vl-max
+# Model for image_image service (if supported)
+; model_image_image=qwen-vl-max
+# Per-service API URL configuration (optional, uses api_url if not specified)
+# API URL for text_text service
+; api_url_text_text=https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions
+# API URL for image_text service
+; api_url_image_text=https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions
+# API URL for text_image service (image generation)
+; api_url_text_image=https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
+# API URL for image_image service (image editing)
+# Try multimodal generation endpoint for qwen-image-edit
+api_url_image_image=https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
+# Capabilities this provider supports (JSON array)
+# Options: text_text, image_text, text_image, image_image
+# Note: Qwen typically supports text_text and image_text, image generation/transformation may not be available
+capabilities=["text_text", "image_text", "text_image", "image_image"]
+# Default system instruction (optional)
+; system_instruction=You are a helpful and friendly assistant.
+# Generation config for text API calls
+# These parameters are optional - only include them in API calls if uncommented
+#
+# temperature - Controls randomness in output (0.0-2.0)
+# Lower values = more deterministic, higher values = more creative
+; text_temperature=0.8
+#
+# max_tokens - Maximum number of tokens in the response
+# Limits response length to control costs and output size
+; text_max_tokens=1024
+#
+# top_p - Nucleus sampling probability (0.0-1.0)
+# Considers tokens with cumulative probability up to top_p
+; text_top_p=0.95
+#
+# top_k - Top-k sampling
+# Considers only the top K most probable tokens
+; text_top_k=40
+#
+# stop - JSON array of sequences that stop generation
+# Generation stops when any of these sequences is encountered
+; text_stop=["###END"]
+# Generation config for image API calls (image_text, text_image, image_image)
+# These parameters are optional - only include them in API calls if uncommented
+#
+# temperature - Controls randomness in output (0.0-2.0)
+# For image analysis, lower values (0.3-0.5) typically provide more accurate descriptions
+; image_temperature=0.4
+#
+# max_tokens - Maximum number of tokens in the response
+# For image descriptions, 300-500 is usually sufficient
+; image_max_tokens=500
+#
+# top_p - Nucleus sampling probability (0.0-1.0)
+# Considers tokens with cumulative probability up to top_p
+; image_top_p=0.8
+#
+# top_k - Top-k sampling
+# Considers only the top K most probable tokens
+; image_top_k=20
+#
+# stop - JSON array of sequences that stop generation
+# Generation stops when any of these sequences is encountered
+; image_stop=["###END"]
+
+[database]
+# Database configuration
+# Enable WAL mode for better SQLite performance
+wal_mode=true
+# Table name for prompts
+prompts_table=prompts_library
+

package/dist/lib/database/init_database.d.ts

@@ -3,7 +3,7 @@
  *
  * Initializes and manages the SQLite database for prompt storage.
  * Uses sql.js for database operations (pure JavaScript SQLite).
- * Creates the prompts_library table if it doesn't exist.
+ * Creates the hazo_prompts table if it doesn't exist.
  */
 import { Database as SqlJsDatabase } from 'sql.js';
 import type { Logger, PromptRecord } from '../llm_api/types.js';
@@ -97,22 +97,22 @@ export declare function close_database(logger: Logger): void;
  * @param logger - Logger instance
  * @returns The inserted prompt record
  */
-export declare function insert_prompt(db: SqlJsDatabase, prompt: Omit<PromptRecord, 'uuid' | 'created_at' | 'changed_by'>, logger: Logger): PromptRecord;
+export declare function insert_prompt(db: SqlJsDatabase, prompt: Omit<PromptRecord, 'id' | 'created_at' | 'changed_at'>, logger: Logger): PromptRecord;
 /**
  * Update an existing prompt in the database
  * @param db - Database instance
- * @param uuid - UUID of the prompt to update
+ * @param id - ID (UUID) of the prompt to update
  * @param updates - Fields to update
  * @param logger - Logger instance
  * @returns The updated prompt record
  */
-export declare function update_prompt(db: SqlJsDatabase, uuid: string, updates: Partial<Omit<PromptRecord, 'uuid' | 'created_at' | 'changed_by'>>, logger: Logger): PromptRecord | null;
+export declare function update_prompt(db: SqlJsDatabase, id: string, updates: Partial<Omit<PromptRecord, 'id' | 'created_at' | 'changed_at'>>, logger: Logger): PromptRecord | null;
 /**
  * Delete a prompt from the database
  * @param db - Database instance
- * @param uuid - UUID of the prompt to delete
+ * @param id - ID (UUID) of the prompt to delete
  * @param logger - Logger instance
  * @returns True if deleted successfully, false if not found
  */
-export declare function delete_prompt(db: SqlJsDatabase, uuid: string, logger: Logger): boolean;
+export declare function delete_prompt(db: SqlJsDatabase, id: string, logger: Logger): boolean;
 //# sourceMappingURL=init_database.d.ts.map

package/dist/lib/database/init_database.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init_database.d.ts","sourceRoot":"","sources":["../../../src/lib/database/init_database.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAkB,EAAE,QAAQ,IAAI,aAAa,EAAE,MAAM,QAAQ,CAAC;AAK9D,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAYhE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAmBrD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAQ/D;AAcD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,aAAa,CAAC,CAgFxB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb,aAAa,GAAG,IAAI,CAatB;AA+GD;;;GAGG;AACH,wBAAgB,YAAY,IAAI,aAAa,GAAG,IAAI,CAEnD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAoClD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAyBnD;AAMD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,EAAE,EAAE,aAAa,EACjB,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,YAAY,GAAG,YAAY,CAAC,EAChE,MAAM,EAAE,MAAM,GACb,YAAY,CAqEd;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,EAAE,EAAE,aAAa,EACjB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,YAAY,GAAG,YAAY,CAAC,CAAC,EAC1E,MAAM,EAAE,MAAM,GACb,YAAY,GAAG,IAAI,CA2GrB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,EAAE,EAAE,aAAa,EACjB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,OAAO,CAgDT"}
+{"version":3,"file":"init_database.d.ts","sourceRoot":"","sources":["../../../src/lib/database/init_database.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAkB,EAAE,QAAQ,IAAI,aAAa,EAAE,MAAM,QAAQ,CAAC;AAK9D,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAYhE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAmBrD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAQ/D;AAcD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,aAAa,CAAC,CAgFxB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb,aAAa,GAAG,IAAI,CAatB;AAuLD;;;GAGG;AACH,wBAAgB,YAAY,IAAI,aAAa,GAAG,IAAI,CAEnD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAoClD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAyBnD;AAMD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,EAAE,EAAE,aAAa,EACjB,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,GAAG,YAAY,GAAG,YAAY,CAAC,EAC9D,MAAM,EAAE,MAAM,GACb,YAAY,CA0Ed;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,EAAE,EAAE,aAAa,EACjB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,GAAG,YAAY,GAAG,YAAY,CAAC,CAAC,EACxE,MAAM,EAAE,MAAM,GACb,YAAY,GAAG,IAAI,CAuHrB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,EAAE,EAAE,aAAa,EACjB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,GACb,OAAO,CAgDT"}