mLLMCelltype Changelog

May 11, 2026 · View on GitHub

2.0.5 (2026-05-11)

Bug Fixes

  • Unified discussion cell-type extraction across consensus checking and early discussion fallback paths.
  • Scoped Qwen endpoint detection cache by API key to avoid cross-credential endpoint reuse.
  • Forwarded registered custom model configuration to custom providers that accept model_config or ....

Documentation

  • Updated caching guidance, model examples, and Python integration examples for current package behavior.

2.0.4 (2026-05-10)

Bug Fixes

  • Aligned R documentation with the actual annotate_cell_types() return contract.
  • Hardened discussion error-response filtering so failed model responses are excluded consistently.
  • Kept default tests offline by gating real API integration tests behind explicit environment variables.

Documentation

  • Updated examples and integration guidance for the current cross-language API surface.

2.0.0 (2026-02-08)

Breaking Changes

  • Version bump to 2.0.0: Major release reflecting substantial architectural improvements since 1.2.9
  • Logger defaults changed: UnifiedLogger console output is now disabled by default (enable_console = FALSE). Use configure_logger(console_output = TRUE) to enable console logging.

New Model Support

  • Added support for latest LLM models across all providers:
    • OpenAI: GPT-5.2, GPT-5.1, GPT-5, o3-pro, o4-mini
    • Anthropic: Claude Opus 4.6, Claude Opus 4.5, Claude Sonnet 4.5
    • Google: Gemini 3 Pro, Gemini 3 Flash, Gemini 2.5 Pro/Flash
    • X.AI: Grok 4, Grok 4.1, Grok 4 Heavy
    • DeepSeek: DeepSeek R1
    • Alibaba: Qwen 3 Max
    • Zhipu: GLM-4.7
    • MiniMax: MiniMax M2.1

Architecture Improvements

  • Unified logging system: Consolidated dual debug mechanisms (debug parameter + LLMCELLTYPE_DEBUG_CACHE env var) into single log_debug() approach; debug = TRUE temporarily enables console + DEBUG level via on.exit()
  • Complete audit trail: All warning() calls now paired with log_warn() for file-based audit; LLM consensus decisions logged to audit trail
  • NAMESPACE fix: QwenProcessor now correctly exported; internal .qwen_endpoint_cache no longer exposed in public API
  • Cluster ID preservation: Cluster IDs from input are preserved as-is throughout the annotation pipeline

Bug Fixes

  • Fixed @export misplacement in qwen_processor.R that exported internal state instead of the processor class
  • Fixed missing tissue_name parameter in real API test calls
  • Fixed print() bypassing logging system in compare_model_predictions.R
  • Fixed trailing newlines causing double-spaced console output in compare_model_predictions.R
  • Fixed message() format inconsistencies across consensus and comparison functions
  • Improved NA handling in API key validation and print functions

Code Quality

  • Removed marketing language from documentation
  • Consistent message() + log_info() pairing across entire codebase
  • Removed dead TaskState.TESTING from state machine (web component)

1.3.6 (2026-02-07)

Documentation Clarification

  • Clarified current cluster ID contract in tutorials and examples: input cluster IDs are preserved as-is
  • Updated mapping examples to use annotation names directly (instead of assuming sequential 0:(n-1) IDs)
  • Kept historical release notes unchanged; this entry documents the current behavior explicitly

1.3.5 (2025-10-12)

Updated Models

  • Updated Anthropic Claude model support to include latest releases:
    • Added Claude Sonnet 4.5 (claude-sonnet-4-5-20250929) - Newest Sonnet model, same price as earlier Sonnets
    • Added Claude Opus 4.1 (claude-opus-4-1-20250805) - Updated Opus model
    • Added Claude 4 series models (claude-sonnet-4-20250514, claude-opus-4-20250514)
    • Added support for both date-versioned and alias formats (e.g., claude-sonnet-4.5, claude-opus-4.1)
  • Updated all documentation, vignettes, and examples to recommend latest models
  • All Sonnet models (4.5, 4, 3.5, 3.7) have identical pricing - Claude Sonnet 4.5 is now supported at identical pricing

Documentation Updates

  • Updated model recommendations in usage tutorials and vignettes
  • Updated get_provider() documentation with comprehensive model lists
  • Added clarification that dated model versions are identical across all platforms

Notes

  • OpenRouter now supports anthropic/claude-sonnet-4.5 and anthropic/claude-opus-4.1
  • All dated model versions (e.g., 20250929) remain stable and do not change over time

1.3.4 (2025-09-09)

Bug Fixes

  • Fixed critical NA handling issue in base_api_processor.R that caused "missing value where TRUE/FALSE needed" errors
  • Fixed similar NA handling issues in print_consensus_summary.R
  • Improved robustness of API key validation to handle NA, NULL, and empty string cases correctly

Improvements

  • Enhanced error handling for invalid API keys
  • Better support for OpenRouter API integration
  • Improved stability when processing consensus annotations

1.3.2 (2025-09-02) - CRAN Release

Official CRAN Release

Installation

  • Standard R package installation from CRAN repository
  • Package has passed CRAN checks for reliability and compatibility
  • Tested across R versions and platforms (Windows, macOS, Linux)

Features

  • Automated cell type annotation using consensus from multiple LLMs
  • Support for OpenAI, Anthropic, Google, and other providers through OpenRouter
  • Integration with Seurat workflows
  • Uncertainty quantification for annotations
  • Caching system for API cost reduction
  • Interactive consensus building with multi-model discussion

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)

Consensus check optimization

Performance Optimization

  • Two-Stage Consensus Strategy: Implemented optimized consensus checking that reduces redundant API calls through early consensus detection
    • 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

  • API cost optimization:
    • 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
    • Reduced code duplication across API processors
    • 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: Consolidated API processor code
  • 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