mLLMCelltype Changelog

1.3.2 (2025-08-28)

CRAN Compliance Updates

📝 Documentation Improvements

Added single quotes around all package names (‘Seurat’), software names, and API names in DESCRIPTION
Explained all acronyms: LLM (Large Language Models) and API (Application Programming Interfaces)
Added proper web references with angle brackets for API documentation

🔧 Code Quality Improvements

Replaced cat() with message() for console output, with proper verbose control
Fixed file writing to use tempdir() by default instead of user’s workspace
Removed .GlobalEnv modifications - now using package-private environment

🚀 Default Behavior Changes

cache_dir now defaults to tempdir() instead of “consensus_cache”
log_dir now defaults to tempdir() instead of “logs”
All file operations now respect CRAN policies for not writing to user’s home directory

1.3.1 (2025-07-16)

New Features: Enhanced Cluster Analysis Control

🎯 Selective Cluster Analysis

New parameter clusters_to_analyze: Allows users to specify exactly which clusters to analyze
- No need to manually filter input data
- Maintains original cluster numbering
- Reduces API calls and costs by focusing on relevant clusters
- Perfect for iterative refinement and subtyping workflows

🔄 Cache Control for Re-analysis

New parameter force_rerun: Forces fresh analysis of controversial clusters
- Bypasses cache when you need new analysis with different context
- Essential for subtype identification with tissue-specific context
- Non-controversial clusters still benefit from cache performance
- Combines perfectly with clusters_to_analyze for targeted workflows

💡 Use Cases

Iterative Subtyping: Analyze broad cell types first, then focus on specific populations
Cost-Effective Re-analysis: Only re-analyze controversial or specific clusters
Context-Specific Analysis: Re-run with different tissue contexts without cache interference
Targeted Refinement: Focus computational resources on clusters of interest

🛠️ Implementation

Full backward compatibility maintained
Comprehensive input validation and error handling
Extensive testing with real API keys across multiple scenarios
Updated documentation with detailed examples

1.2.9 (2025-06-24)

Major Enhancement: Consensus Check Optimization

🚀 Performance Optimization

Two-Stage Consensus Strategy: Implemented optimized consensus checking that reduces LLM API calls by ~70-80%
- Stage 1 - Simple Consensus: First performs fast local calculation based on normalized annotations
- Stage 2 - LLM Verification: Only calls LLM for clusters that don’t meet consensus thresholds
- Smart Resource Usage: LLM only used for genuinely ambiguous cases

💰 Cost Reduction

Significant API Savings:
- Clear consensus cases (majority of clusters) now processed without LLM calls
- Reduces costs proportionally to API call reduction
- Maintains same accuracy while being much more economical

🔧 Implementation Details

New Functions:
- normalize_annotation(): Handles annotation variations (e.g., “T cells” vs “T lymphocytes”)
- calculate_simple_consensus(): Fast local consensus calculation with CP and entropy metrics
Improved Fallback: If LLM fails, falls back to simple consensus results instead of default values
Enhanced Logging: Clear indication of which strategy was used for each cluster

1.2.7 (2025-06-17)

Major Enhancements: Code Deduplication and Enhanced Logging

🔧 Code Architecture Refactoring

BaseAPIProcessor: Introduced abstract base class for API processing with unified error handling and logging
- Eliminated 70% code duplication across 10 API processor files
- Standardized interface: All processors now inherit from BaseAPIProcessor with consistent make_api_call() and extract_response_content() methods
- Unified error handling: Centralized exception handling and retry logic across all API providers

📝 Enhanced Discussion Logging

Fixed Discussion Format Issues: Resolved fragmented discussion logs where multi-line model responses were split into multiple entries
- Improved readability: Multi-line model predictions now properly consolidated into single coherent text blocks
- Better structure: Clean Markdown format with proper headers and code block formatting
- Complete conversations: Full model reasoning (grounds, warrant, backing, qualifier, rebuttal) preserved in readable format

🔍 Complete API Request/Response Logging

New Feature: Full API audit trail with complete request and response content
- Dual format logging: Both JSON (machine-readable) and Markdown (human-readable) formats
- Complete transparency: Every API call now logged with full prompt content and response
- Debugging support: Detailed metadata including chunk information, timing, and response characteristics
- Session organization: API logs organized in dedicated api_logs/ subdirectories within each session

📊 Improved Log Organization

Enhanced directory structure:

logs/
├── mllm_YYYYMMDD_HHMMSS.log          # Main session log
├── YYYYMMDD_HHMMSS/                   # Session directory
│   ├── cluster_X_discussion.md        # Discussion logs (fixed format)
│   └── api_logs/                      # Complete API call logs (NEW)
│       ├── provider_model_timestamp.json
│       └── provider_model_timestamp.md

🚀 Performance Improvements

Reduced codebase size: Eliminated ~2000 lines of duplicate code across API processors
Maintainability: Single source of truth for API processing logic
Consistency: Standardized error messages and logging across all providers

✅ Quality Assurance

Comprehensive testing: All changes verified with real API calls using OpenRouter
Backward compatibility: Existing functionality preserved while enhancing logging capabilities
Zero breaking changes: All public APIs remain unchanged

1.2.6 (2025-06-14)

Major Logging System Overhaul

🔄 Unified Logging System: Replaced fragmented logging infrastructure with comprehensive unified logging
- Removed: Old DiscussionLogger class and scattered write_log calls
- Added: New UnifiedLogger R6 class with structured JSON output, multi-level logging, and performance monitoring
- New functions: configure_logger(), get_logger(), log_info(), log_warn(), log_error(), log_debug()
- Features: Session tracking, API call monitoring, cache operation logging, automatic log rotation

Performance Improvements

📊 Performance Monitoring: Integrated performance tracking with session duration, API call counting, and error statistics
🔄 Log Rotation: Automatic log file rotation with configurable size limits and file retention
📝 Structured Logging: JSON-formatted logs with context metadata for better analysis and debugging

API Enhancements

🔧 Function Signature Updates: Removed logger parameters from all consensus annotation functions
🧹 Code Cleanup: Eliminated 20+ scattered logger parameter dependencies across the codebase
⚡ Cache Integration: Enhanced cache operations with detailed logging and performance tracking

Documentation Updates

📚 Updated Vignettes: Revised advanced features tutorial with new unified logging examples
📖 Roxygen Documentation: Updated all function documentation to reflect new logging system
🔄 NAMESPACE Updates: Added exports for new logging functions and UnifiedLogger class

Breaking Changes

⚠️ Logger Parameters: Removed logger parameters from interactive_consensus_annotation() and related functions
⚠️ DiscussionLogger: Deprecated DiscussionLogger class (still exported for backward compatibility but not recommended)

1.2.5 (2025-06-02)

Model Updates

Updated Gemini model support: Added support for new Gemini models and removed discontinued ones
- Added gemini-2.0-flash-lite to supported models list
- Updated documentation to reflect Google’s model migration recommendations
- Removed references to discontinued Gemini 1.5 Pro 001 and Gemini 1.5 Flash 001 models

Important Notes

Google Gemini Model Migration: Google has discontinued several Gemini 1.5 models:
- Already discontinued: Gemini 1.5 Pro 001, Gemini 1.5 Flash 001
- Will be discontinued on Sept 24, 2025: Gemini 1.5 Pro 002, Gemini 1.5 Flash 002, Gemini 1.5 Flash-8B -001
- Recommended migration: Use gemini-2.0-flash or gemini-2.0-flash-lite for better performance and continued support
- The aliases gemini-1.5-pro and gemini-1.5-flash will continue to work until September 24, 2025

Documentation Updates

Updated all README files (English and international versions) with new Gemini model information
Updated R documentation and vignettes to reflect model changes
Added migration guidance in main documentation

1.2.4 (2025-05-25)

Critical Bug Fixes

Fixed major as.logical(from) error: Resolved critical error that occurred when processing large numbers of clusters (60+ clusters), which was caused by non-character data being passed to strsplit() functions
Enhanced error handling for API responses: Added comprehensive tryCatch() blocks around all strsplit() operations in API processing functions
Improved response validation: Added robust type checking for API responses to prevent function/closure types from being processed as character strings

Improvements

Enhanced API processing robustness: All API processing functions (process_openrouter.R, process_anthropic.R, process_openai.R, process_deepseek.R, process_qwen.R, process_stepfun.R, process_minimax.R, process_zhipu.R, process_gemini.R, process_grok.R) now include improved error handling
Better NULL value handling: Improved unlist() operations to filter out NULL values and handle errors gracefully
Enhanced logging: Added more detailed error logging for debugging API response issues
Improved consensus checking: Enhanced check_consensus.R to handle edge cases with malformed responses

Technical Details

Fixed issue where large cluster datasets could cause type coercion errors in response parsing
Added validation for function/closure types in API responses to prevent downstream errors
Improved error messages to provide better diagnostics for API response issues

1.2.3 (2025-05-10)

Bug Fixes

Fixed error handling in consensus checking when API responses are NULL or invalid
Improved error logging for OpenRouter API error responses
Added robust NULL and type checking in check_consensus function

Improvements

Enhanced error diagnostics for OpenRouter API errors
Added detailed logging of API error messages and response structures
Improved robustness when handling unexpected API response formats

1.2.2 (2025-05-09)

Bug Fixes

Fixed the ‘non-character argument’ error that occurred when processing API responses
Added robust type checking for API responses across all model providers
Improved error handling for unexpected API response formats

Improvements

Added detailed error logging for API response issues
Implemented consistent error handling patterns across all API processing functions
Enhanced response validation to ensure proper structure before processing

1.2.1 (2025-05-01)

Improvements

Added support for OpenRouter API
Added support for free models through OpenRouter
Updated documentation with examples for using OpenRouter models

1.2.0 (2025-04-30)

Features

Added visualization functions for cell type annotation results
Added support for uncertainty metrics visualization
Implemented improved consensus building algorithm

1.1.5 (2025-04-27)

Bug Fixes

Fixed an issue with cluster index validation that caused errors when processing certain CSV input files
Improved error handling for negative indices with clearer error messages

Improvements

Added example script for CSV-based annotation workflow (cat_heart_annotation.R)
Enhanced input validation with more detailed diagnostics
Updated documentation to clarify CSV input format requirements

1.1.4 (2025-04-24)

Bug Fixes

Fixed a critical issue with cluster index handling, now the package strictly accepts only 0-based indices (compatible with Seurat)
Fixed negative index (-1) issues that could occur when processing CSV input files
Added strict validation for input cluster indices to ensure they start from 0

Improvements

Removed automatic conversion logic from 1-based to 0-based indices in prompt_templates.R
Added input validation in consensus_annotation.R to ensure cluster indices start from 0
Updated code comments to clearly indicate that the package only accepts 0-based indices

1.1.3 (2025-04-15)

Added support for X.AI’s Grok models
Updated the list of supported models, including Gemini 2.5 Pro
Improved error handling and logging

1.1.2 (2025-03-30)

Added support for Gemini 2.0 models
Improved model response parsing
Fixed cache management issues

1.1.1 (2025-03-15)

Added support for Claude 3.7 and Claude 3.5 models
Improved consensus building algorithm
Fixed multiple minor bugs

1.1.0 (2025-03-01)

Added interactive consensus annotation functionality
Added multi-model discussion capability
Improved cell type standardization

1.0.0 (2025-02-15)

Initial release
Support for cell type annotation using LLMs
Support for models from OpenAI, Anthropic, and Google