horde-model-reference 2.0.0__tar.gz → 2.1.1__tar.gz

horde_model_reference-2.1.1/.readthedocs.yaml

@@ -0,0 +1,28 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+    # You can also specify other tool versions:
+    # nodejs: "20"
+    # rust: "1.70"
+    # golang: "1.20"
+  jobs:
+    pre_create_environment:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+    create_environment:
+      - uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
+    install:
+      - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --frozen --group docs
+
+
+mkdocs:
+  configuration: mkdocs.yml

{horde_model_reference-2.0.0/src/horde_model_reference.egg-info → horde_model_reference-2.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: horde_model_reference
-Version: 2.0.0
+Version: 2.1.1
 Summary: A helper library providing a way to work with the lists of generation models, utility models, and any other related files required for the AI-Horde ecosystem.
 Author-email: tazlin <tazlin.on.github@gmail.com>, db0 <mail@dbzer0.com>
 License:                     GNU AFFERO GENERAL PUBLIC LICENSE
@@ -964,10 +964,11 @@ print(f"Description: {model['description']}")
 
 ## Documentation
 
-- **📖 Full Documentation**: [MkDocs Site](https://haidra-org.github.io/horde-model-reference/) *(coming soon)*
+- **📖 Full Documentation**: [MkDocs Site](https://horde-model-reference.readthedocs.io/en/latest/)
 - **🚀 Deployment Guide**: [DEPLOYMENT.md](DEPLOYMENT.md)
-- **� GitHub Sync (Docker)**: [DOCKER_SYNC.md](DOCKER_SYNC.md) - Optional automated sync to legacy repos
-- **�🔧 API Reference**: Run service and visit `http://localhost:19800/docs` for interactive Swagger UI
+- **🔄 GitHub Sync (Docker)**: [DOCKER_SYNC.md](DOCKER_SYNC.md) - Optional automated sync to legacy repos
+- **📝 Legacy CSV Conversion**: [docs/legacy_csv_conversion.md](docs/legacy_csv_conversion.md) - Text generation CSV format details
+- **🔧 API Reference**: Run service and visit `http://localhost:19800/docs` for interactive Swagger UI
 - **🤝 Contributing**: [.CONTRIBUTING.md](.CONTRIBUTING.md)
 - **🗂️ Project Structure**:
     - `src/horde_model_reference/` - Core library

{horde_model_reference-2.0.0 → horde_model_reference-2.1.1}/README.md

@@ -270,10 +270,11 @@ print(f"Description: {model['description']}")
 
 ## Documentation
 
-- **📖 Full Documentation**: [MkDocs Site](https://haidra-org.github.io/horde-model-reference/) *(coming soon)*
+- **📖 Full Documentation**: [MkDocs Site](https://horde-model-reference.readthedocs.io/en/latest/)
 - **🚀 Deployment Guide**: [DEPLOYMENT.md](DEPLOYMENT.md)
-- **� GitHub Sync (Docker)**: [DOCKER_SYNC.md](DOCKER_SYNC.md) - Optional automated sync to legacy repos
-- **�🔧 API Reference**: Run service and visit `http://localhost:19800/docs` for interactive Swagger UI
+- **🔄 GitHub Sync (Docker)**: [DOCKER_SYNC.md](DOCKER_SYNC.md) - Optional automated sync to legacy repos
+- **📝 Legacy CSV Conversion**: [docs/legacy_csv_conversion.md](docs/legacy_csv_conversion.md) - Text generation CSV format details
+- **🔧 API Reference**: Run service and visit `http://localhost:19800/docs` for interactive Swagger UI
 - **🤝 Contributing**: [.CONTRIBUTING.md](.CONTRIBUTING.md)
 - **🗂️ Project Structure**:
     - `src/horde_model_reference/` - Core library

horde_model_reference-2.1.1/docs/legacy_csv_conversion.md

@@ -0,0 +1,259 @@
+# Legacy CSV Conversion for Text Generation Models
+
+## Overview
+
+The `text_generation` category is unique in the model reference system as it's the **only category** that uses CSV format for legacy files instead of JSON. This document explains the conversion process, common pitfalls, and implementation details.
+
+## File Format Summary
+
+| Category | Legacy Format | V2 Format | Legacy Path | V2 Path |
+|----------|---------------|-----------|-------------|---------|
+| `text_generation` | **CSV** | JSON | `{base}/legacy/models.csv` | `{base}/text_generation.json` |
+| All others | JSON | JSON | `{base}/legacy/{category}.json` | `{base}/{category}.json` |
+
+## CSV Structure
+
+The legacy CSV file (`models.csv`) has the following columns:
+
+```csv
+name,parameters_bn,description,version,style,nsfw,baseline,url,tags,settings,display_name
+```
+
+### Column Details
+
+- **name**: Model identifier (string)
+- **parameters_bn**: Parameters in billions (float, e.g., "7.0" for 7B parameters)
+- **description**: Model description (string)
+- **version**: Model version (string)
+- **style**: Model style/category (string)
+- **nsfw**: NSFW flag (string: "true" or "false")
+- **baseline**: Base model/architecture (string)
+- **url**: Model URL (string)
+- **tags**: Comma-separated tags (string, e.g., "tag1,tag2,tag3")
+- **settings**: JSON object as string (string, e.g., '{"temperature": 0.7}')
+- **display_name**: Display name (string)
+
+## Conversion Process
+
+### 1. CSV → Internal Dictionary
+
+The `LegacyTextGenerationConverter._load_and_validate_legacy_records()` method reads the CSV and converts it to an internal dictionary format:
+
+```python
+# Parameters: billions → integer
+params_bn = float(row.get("parameters_bn", 0))
+parameters = int(params_bn * 1_000_000_000)  # 7.0 → 7,000,000,000
+
+# Tags: comma-separated string → list
+tags_str = row.get("tags", "")
+tags = [t.strip() for t in tags_str.split(",") if t.strip()]
+
+# Settings: JSON string → dict
+settings_str = row.get("settings", "")
+settings = json.loads(settings_str) if settings_str else None
+
+# NSFW: string → boolean
+nsfw = row.get("nsfw", "").lower() == "true"
+```
+
+### 2. Dictionary → Pydantic Validation
+
+The internal dictionary is validated using `LegacyTextGenerationRecord` Pydantic model.
+
+### 3. Pydantic → V2 JSON Output
+
+The base class `write_out_records()` method writes the converted records to `text_generation.json` (always JSON format).
+
+### Backend Prefix Filtering
+
+`LegacyTextGenerationConverter._convert_single_record()` calls `has_legacy_text_backend_prefix()` and drops any rows whose `name` uses backend-generated prefixes such as `aphrodite/` or `koboldcpp/`. These prefixed entries are duplicates that only exist for backwards compatibility and are intentionally excluded from the v2 dataset.
+
+## Critical Constraints
+
+### Settings Field Type Limitation
+
+The `settings` field has a strict type constraint that **does NOT support nested dictionaries**:
+
+```python
+settings: dict[str, int | float | str | list[int] | list[float] | list[str] | bool] | None
+```
+
+**Valid Settings:**
+
+```json
+{
+    "temperature": 0.7,
+    "top_p": 0.9,
+    "max_tokens": 2048,
+    "stop_sequences": ["</s>", "[DONE]"],
+    "enabled": true
+}
+```
+
+**Invalid Settings (will fail validation):**
+
+```json
+{
+    "nested": {"key": "value"},  // ❌ Nested dicts not allowed
+    "complex": {"another": {"level": "here"}}  // ❌ Nested dicts not allowed
+}
+```
+
+### Settings JSON Validity
+
+The `settings` column must contain valid JSON. If a row includes malformed JSON, `json.loads()` raises `json.JSONDecodeError` and the converter stops rather than silently skipping that entry.
+
+### Numeric Parameters Required
+
+`parameters_bn` must parse as a floating-point number (e.g., `"7.0"`). Non-numeric strings—including blank cells—raise a `ValueError` during conversion; there is no automatic fallback beyond the explicit `0` default used when the column is truly missing.
+
+## Common Pitfalls
+
+### 1. Double Legacy Folder Bug
+
+**Problem:** Passing the wrong path to converters results in `{base}/legacy/legacy/models.csv`.
+
+**Root Cause:** The converter's `legacy_folder_path` parameter expects a BASE path (e.g., `data/`), and it automatically appends `/legacy/` internally via `get_legacy_model_reference_file_path()`.
+
+**Wrong Usage:**
+
+```python
+# ❌ WRONG - results in data/legacy/legacy/models.csv
+converter = LegacyTextGenerationConverter(
+    legacy_folder_path=Path("data/legacy"),  # Already has /legacy/
+    target_file_folder=Path("data"),
+)
+```
+
+**Correct Usage:**
+
+```python
+# ✅ CORRECT - results in data/legacy/models.csv
+converter = LegacyTextGenerationConverter(
+    legacy_folder_path=Path("data"),  # Base path only
+    target_file_folder=Path("data"),
+)
+```
+
+### 2. Empty File Handling
+
+Empty CSV files (0 bytes or only headers) are handled gracefully and return an empty dictionary without errors.
+
+### 3. Missing Optional Fields
+
+CSV rows with missing optional fields are handled by using empty strings or default values:
+
+```python
+# Missing fields default to:
+description=""
+version=""
+style=""
+baseline=""
+url=""
+tags=[]
+settings=None
+display_name=""
+```
+
+`parameters_bn` is the exception—leave it blank or non-numeric and the conversion fails. Ensure every row contains a numeric value (use `0` when no parameter estimate is available).
+
+## Testing Considerations
+
+### Test Fixture Path Handling
+
+In tests, the `populated_legacy_path` fixture creates files in `primary/legacy/` but when calling converters, always pass `primary_base` (not `populated_legacy_path`):
+
+```python
+# ✅ CORRECT
+def test_converter(primary_base: Path, populated_legacy_path: Path):
+    converter = LegacyTextGenerationConverter(
+        legacy_folder_path=primary_base,  # Pass base, not populated_legacy_path
+        target_file_folder=primary_base,
+    )
+```
+
+### Comprehensive Test Coverage
+
+The test suite (`test_text_generation_csv_conversion.py`) covers:
+
+1. CSV reading and parsing
+2. JSON output format verification (regression test)
+3. Data integrity (all fields preserved)
+4. Empty file handling
+5. Missing optional fields
+6. Complex settings (within type constraints)
+7. Non-existent file handling
+8. Large parameter value conversion
+9. Output format verification (JSON not CSV)
+
+## Implementation Details
+
+### Key Files
+
+- **Converter**: `src/horde_model_reference/legacy/classes/legacy_converters.py`
+    - `LegacyTextGenerationConverter` class
+    - `_load_and_validate_legacy_records()` override for CSV reading
+    - `_convert_single_record()` skips backend-prefixed duplicates via `has_legacy_text_backend_prefix()`
+
+- **Backend - GitHub**: `src/horde_model_reference/backends/github_backend.py`
+    - `_read_legacy_csv_to_dict()` method for CSV parsing
+    - Empty file handling
+
+- **Backend - FileSystem**: `src/horde_model_reference/backends/filesystem_backend.py`
+    - `_read_legacy_csv_to_dict()` method for CSV parsing
+
+- **Tests**:
+    - `tests/test_text_generation_csv_conversion.py` - Comprehensive CSV conversion tests
+    - `tests/test_text_generation_file_paths.py` - File path and format verification
+    - `tests/conftest.py` - Test fixtures with CSV generation
+
+### Parameter Conversion Formula
+
+```python
+# CSV stores parameters in billions (float)
+parameters_bn = 7.0  # From CSV
+
+# Convert to integer parameters
+parameters = int(parameters_bn * 1_000_000_000)
+# Result: 7,000,000,000
+
+# Examples:
+# 0.5 → 500,000,000 (500M)
+# 7.0 → 7,000,000,000 (7B)
+# 13.0 → 13,000,000,000 (13B)
+# 70.0 → 70,000,000,000 (70B)
+```
+
+## Best Practices
+
+1. **Always pass base paths** to converters, never paths with `/legacy/` already included
+2. **Test with empty files** to ensure graceful handling
+3. **Validate settings constraints** - only flat dicts allowed
+4. **Pre-validate numeric and JSON fields** - ensure `parameters_bn` values are numeric strings and `settings` cells contain valid JSON before running the converter
+5. **Use CSV.DictWriter** for creating test CSV files to ensure proper formatting
+6. **Verify JSON output** - output should always be JSON, never CSV
+7. **Handle missing fields** with appropriate defaults
+
+## GitHub Sync Behavior
+
+When syncing from GitHub:
+
+1. GitHub backend downloads `legacy/models.csv` (CSV format)
+2. If file is empty (0 bytes), skip conversion
+3. Parse CSV using `_read_legacy_csv_to_dict()`
+4. Convert to TextGenerationModelRecord objects
+5. Write to `text_generation.json` (JSON format)
+6. Serve both legacy CSV and v2 JSON endpoints
+
+## Migration Notes
+
+If you need to add a new category with CSV format (not recommended unless necessary):
+
+1. Override `_load_and_validate_legacy_records()` in your converter
+2. Implement CSV reading logic similar to `LegacyTextGenerationConverter`
+3. Add backend CSV reading support in GitHub and FileSystem backends
+4. Create comprehensive tests covering all edge cases
+5. Update path constants if using different filenames
+6. Document the CSV structure and conversion process
+
+**Note:** It's strongly recommended to use JSON for new categories to maintain consistency with the rest of the system.

{horde_model_reference-2.0.0 → horde_model_reference-2.1.1}/pyproject.toml

@@ -136,7 +136,6 @@ dev = [
     "types-requests>=2.31.0.6",
     "types-tabulate>=0.9.0.20241207",
     "types-ujson>=5.10.0.20250822",
-    "vcrpy>=5.1.0",
 ]
 sync-dev = [
     "gitpython>=3.1.45",

{horde_model_reference-2.0.0 → horde_model_reference-2.1.1}/schemas/stable_diffusion.schema.json

@@ -243,7 +243,9 @@
                 "text_generation",
                 "video_generation",
                 "audio_generation",
-                "miscellaneous"
+                "miscellaneous",
+                "lora",
+                "ti"
             ],
             "title": "MODEL_REFERENCE_CATEGORY",
             "type": "string"

{horde_model_reference-2.0.0 → horde_model_reference-2.1.1}/scripts/get_all_names.py

@@ -5,7 +5,7 @@ from loguru import logger
 
 logger.remove()
 
-from horde_model_reference import MODEL_REFERENCE_CATEGORY, ModelReferenceManager  # noqa: E402
+from horde_model_reference import MODEL_REFERENCE_CATEGORY, ModelReferenceManager, PrefetchStrategy  # noqa: E402
 
 ALIASES = {"stable_diffusion": "image_generation"}
 
@@ -22,7 +22,7 @@ def configure_logger(quiet: bool) -> None:
 def get_all_names(model_reference_category: MODEL_REFERENCE_CATEGORY, refresh: bool) -> list[str]:
     """Get all model names for a given model reference category."""
     logger.debug(f"Getting all names for category: {model_reference_category}")
-    model_reference_manager = ModelReferenceManager(lazy_mode=False)
+    model_reference_manager = ModelReferenceManager(prefetch_strategy=PrefetchStrategy.SYNC)
     all_references = model_reference_manager.get_all_model_references(overwrite_existing=refresh)
 
     if model_reference_category not in all_references:

{horde_model_reference-2.0.0 → horde_model_reference-2.1.1}/scripts/sync/README.md

@@ -61,6 +61,13 @@ PRIMARY (v1 API) ────► Comparator ◄──── GitHub (legacy repos
 ## Important Notes
 
 - Ensure your environment variables are set correctly before running the sync service.
+- **Git Identity Configuration**: The user running the sync service must have git identity configured for commits to work:
+
+  ```bash
+  git config --global user.name "Your Name"
+  git config --global user.email "your.email@example.com"
+  ```
+
 - **If running the sync service on the same host as the PRIMARY instance**
     - You must set a different `AIWORKER_CACHE_HOME` for each or it will never detect changes. You should always set this variable when using the sync service.
 

{horde_model_reference-2.0.0 → horde_model_reference-2.1.1}/src/horde_model_reference/__init__.py

@@ -269,6 +269,18 @@ Only used in PRIMARY mode. If True, will download and convert legacy references
     """Percentage threshold for low usage flag in audit analysis. Default 0.0065% flags bottom ~10% of models. \
 Set lower (e.g., 0.005%) to flag fewer models or higher (e.g., 0.01%) to flag more models."""
 
+    text_gen_low_usage_threshold_percentage: float = 0.02
+    """Low usage threshold for text_generation models (2% - more lenient than image models at 0.65%)."""
+
+    text_gen_ignore_download_hosts: bool = True
+    """Skip download host validation for text_generation models completely."""
+
+    text_gen_critical_usage_threshold: int = 10
+    """Minimum monthly usage for text_generation to be flagged as critical (allows some usage)."""
+
+    text_gen_critical_worker_threshold: int = 1
+    """Minimum worker count for text_generation to be flagged as critical (allows some workers)."""
+
     @model_validator(mode="after")
     def validate_mode_configuration(self) -> HordeModelReferenceSettings:
         """Validate that settings are appropriate for the configured replication mode."""
@@ -349,7 +361,7 @@ from .path_consts import (  # noqa: E402
     horde_model_reference_paths,
 )
 
-from .model_reference_manager import ModelReferenceManager  # noqa: E402
+from .model_reference_manager import ModelReferenceManager, PrefetchStrategy  # noqa: E402
 
 __all__ = [
     "BASE_PATH",
@@ -363,6 +375,7 @@ __all__ = [
     "MODEL_STYLE",
     "ModelClassification",
     "ModelReferenceManager",
+    "PrefetchStrategy",
     "get_model_reference_file_path",
     "get_model_reference_filename",
     "horde_model_reference_paths",

{horde_model_reference-2.0.0 → horde_model_reference-2.1.1}/src/horde_model_reference/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = 'v2.0.0'
-__version_tuple__ = version_tuple = (2, 0, 0)
+__version__ = version = 'v2.1.1'
+__version_tuple__ = version_tuple = (2, 1, 1)
 
 __commit_id__ = commit_id = None

{horde_model_reference-2.0.0 → horde_model_reference-2.1.1}/src/horde_model_reference/analytics/audit_analysis.py

@@ -123,16 +123,25 @@ class FlagValidatorService:
     def validate_downloads(
         downloads: list[Any] | None,
         preferred_hosts: list[str] | None = None,
+        category: MODEL_REFERENCE_CATEGORY | None = None,
     ) -> tuple[bool, bool, bool, bool]:
         """Validate download URLs and return related flags.
 
         Args:
             downloads: List of download records to validate.
             preferred_hosts: List of preferred file hosts. If None, uses settings.
+            category: Model category - if text_generation and ignore setting is True, returns all False.
 
         Returns:
             Tuple of (no_download_urls, has_multiple_hosts, has_non_preferred_host, has_unknown_host)
         """
+        # Skip download validation for text_generation if configured
+        if (
+            category == MODEL_REFERENCE_CATEGORY.text_generation
+            and horde_model_reference_settings.text_gen_ignore_download_hosts
+        ):
+            return (False, False, False, False)
+
         if preferred_hosts is None:
             preferred_hosts = horde_model_reference_settings.preferred_file_hosts
 
@@ -195,6 +204,7 @@ class FlagValidatorService:
         statistics: CombinedModelStatistics | None,
         category_total_usage: int,
         low_usage_threshold: float | None = None,
+        category: MODEL_REFERENCE_CATEGORY | None = None,
     ) -> tuple[bool, bool, bool, bool, bool]:
         """Validate Horde API statistics and usage data.
 
@@ -202,6 +212,7 @@ class FlagValidatorService:
             statistics: Optional Horde API statistics.
             category_total_usage: Total monthly usage for the category.
             low_usage_threshold: Percentage threshold for low usage. If None, uses settings default.
+            category: Model category for category-specific thresholds.
 
         Returns:
             Tuple of (zero_usage_day, zero_usage_month, zero_usage_total, no_active_workers, low_usage)
@@ -209,9 +220,12 @@ class FlagValidatorService:
         if not statistics:
             return (False, False, False, False, False)
 
-        # Use configured threshold if not provided
+        # Use category-specific threshold for text_generation
         if low_usage_threshold is None:
-            low_usage_threshold = horde_model_reference_settings.low_usage_threshold_percentage
+            if category == MODEL_REFERENCE_CATEGORY.text_generation:
+                low_usage_threshold = horde_model_reference_settings.text_gen_low_usage_threshold_percentage
+            else:
+                low_usage_threshold = horde_model_reference_settings.low_usage_threshold_percentage
 
         # Check for zero workers
         no_active_workers = statistics.worker_count == 0
@@ -422,11 +436,16 @@ class ModelAuditInfo(BaseModel):
     def is_critical(self) -> bool:
         """Determine if model is in critical state.
 
-        Critical = zero month usage AND no active workers.
+        For text_generation: usage_month < threshold AND worker_count < threshold
+        For other models: zero month usage AND no active workers (original logic)
 
         Returns:
             True if model meets critical criteria.
         """
+        if self.category == MODEL_REFERENCE_CATEGORY.text_generation:
+            usage_threshold = horde_model_reference_settings.text_gen_critical_usage_threshold
+            worker_threshold = horde_model_reference_settings.text_gen_critical_worker_threshold
+            return self.usage_month < usage_threshold and self.worker_count < worker_threshold
         return self.deletion_risk_flags.zero_usage_month and self.deletion_risk_flags.no_active_workers
 
     @computed_field  # type: ignore[prop-decorator]
@@ -632,10 +651,16 @@ class ImageGenerationDeletionRiskFlagsHandler(DeletionRiskFlagsHandler):
 
         return (
             DeletionRiskFlagsBuilder()
-            .with_download_flags(*FlagValidatorService.validate_downloads(downloads))
+            .with_download_flags(
+                *FlagValidatorService.validate_downloads(downloads, category=MODEL_REFERENCE_CATEGORY.image_generation)
+            )
             .with_missing_description(FlagValidatorService.validate_description(model_record.description))
             .with_missing_baseline(FlagValidatorService.validate_baseline(model_record.baseline))
-            .with_statistics_flags(*FlagValidatorService.validate_statistics(statistics, category_total_usage))
+            .with_statistics_flags(
+                *FlagValidatorService.validate_statistics(
+                    statistics, category_total_usage, category=MODEL_REFERENCE_CATEGORY.image_generation
+                )
+            )
             .build()
         )
 
@@ -697,10 +722,16 @@ class TextGenerationDeletionRiskFlagsHandler(DeletionRiskFlagsHandler):
 
         return (
             DeletionRiskFlagsBuilder()
-            .with_download_flags(*FlagValidatorService.validate_downloads(downloads))
+            .with_download_flags(
+                *FlagValidatorService.validate_downloads(downloads, category=MODEL_REFERENCE_CATEGORY.text_generation)
+            )
             .with_missing_description(FlagValidatorService.validate_description(model_record.description))
             .with_missing_baseline(FlagValidatorService.validate_baseline(model_record.baseline))
-            .with_statistics_flags(*FlagValidatorService.validate_statistics(statistics, category_total_usage))
+            .with_statistics_flags(
+                *FlagValidatorService.validate_statistics(
+                    statistics, category_total_usage, category=MODEL_REFERENCE_CATEGORY.text_generation
+                )
+            )
             .build()
         )
 

{horde_model_reference-2.0.0 → horde_model_reference-2.1.1}/src/horde_model_reference/analytics/text_model_parser.py

@@ -49,7 +49,9 @@ VARIANT_PATTERNS = [
 
 # Quantization patterns
 QUANT_PATTERNS = [
-    r"\b(Q[2-8](?:_K)?(?:_[SMLH])?)\b",  # Q4_K_M, Q8, Q5_K_S
+    r"\b(Q[2-8]_K(?:_[SMLH])?)\b",  # Q4_K_M, Q5_K_S, Q6_K (K-quants with optional size)
+    r"\b(Q[2-8]_[01])\b",  # Q4_0, Q5_0, Q5_1, Q8_0 (legacy/standard quants)
+    r"\b(Q[2-8])\b",  # Q4, Q8 (bare quant indicators)
     r"\b(GGUF|GGML|GPTQ|AWQ|EXL2)\b",
     r"\b(fp16|fp32|int8|int4)\b",
 ]
@@ -185,9 +187,22 @@ def normalize_model_name(model_name: str) -> str:
     return normalized.strip("_")
 
 
+@dataclass
+class TextModelGroup:
+    """Represents a group of text model variants sharing the same base model.
+
+    Attributes:
+        base_name: The base model name.
+        variants: List of full model names that are variants of the base model.
+    """
+
+    base_name: str
+    variants: list[str]
+
+
 def group_text_models_by_base(
     model_names: list[str],
-) -> dict[str, list[str]]:
+) -> dict[str, TextModelGroup]:
     """Group text model names by their base model.
 
     Groups variants of the same model together based on extracted base names.
@@ -224,7 +239,13 @@ def group_text_models_by_base(
 
     logger.debug(f"Grouped {len(model_names)} models into {len(grouped)} base models")
 
-    return grouped
+    return {
+        base_name: TextModelGroup(
+            base_name=base_name,
+            variants=variants,
+        )
+        for base_name, variants in grouped.items()
+    }
 
 
 @lru_cache(maxsize=2048)