feat: Phase 2b router integration with offerings/packages catalogs

- Router uses offering-specific pricing for cost estimation
- Package scoring based on remaining credits and expiry dates
- Dashboard shows package details and credits overview
- Updated version to 1.17.0

Author: André Lange

CHANGELOG.md

@@ -1,5 +1,22 @@
 # fusionAIze Gate Changelog
 
+## v1.17.0 - 2026-04-01
+
+### Added
+
+- Added router integration with offerings catalog for price-aware routing decisions (Phase 2b)
+- Added package scoring based on remaining credits and expiry dates for intelligent routing
+- Added detailed package overview to dashboard with credits, expiry, and provider mapping
+- Added `_metadata_packages_detail()` function for detailed package insights
+- Enhanced dashboard with package details section and cost projection improvements
+
+### Changed
+
+- Updated router cost estimation to prefer offering-specific pricing over provider defaults
+- Improved provider dimension scoring with package score integration
+- Extended dashboard metadata catalogs summary with package details
+- No breaking changes; existing routing behavior remains compatible
+
 ## v1.16.0 - 2026-04-01
 
 ### Added

faigate/__init__.py

@@ -1,3 +1,3 @@
 """fusionAIze Gate package."""
 
-__version__ = "1.16.0"
+__version__ = "1.17.0"

faigate/dashboard.py

@@ -6,12 +6,17 @@
 
 import json
 import time
+from datetime import date
 from pathlib import Path
 from typing import Any
 
 from .lane_registry import get_route_add_recommendations
 from .metrics import MetricsStore
-from .provider_catalog import build_provider_refresh_guidance
+from .provider_catalog import (
+    build_provider_refresh_guidance,
+    get_offerings_catalog,
+    get_packages_catalog,
+)
 from .provider_catalog_refresh import (
     build_catalog_alert_summary,
     build_catalog_alerts,
@@ -209,6 +214,100 @@ def _provider_catalog_summary(db_path: str) -> dict[str, Any]:
         store.close()
 
 
+def _metadata_catalogs_summary() -> dict[str, Any]:
+    """Return summary statistics for offerings and packages catalogs."""
+    offerings = get_offerings_catalog()
+    packages = get_packages_catalog()
+
+    # Count offerings by freshness
+    freshness_counts = {"fresh": 0, "aging": 0, "stale": 0, "unknown": 0}
+    for offering in offerings.values():
+        pricing = offering.get("pricing", {})
+        freshness = pricing.get("freshness_status", "unknown")
+        if freshness in freshness_counts:
+            freshness_counts[freshness] += 1
+        else:
+            freshness_counts["unknown"] += 1
+
+    # Count packages by type and expiry
+    package_types = {}
+    expiring_soon = 0
+    today = date.today()
+    for package in packages.values():
+        pkg_type = package.get("type", "unknown")
+        package_types[pkg_type] = package_types.get(pkg_type, 0) + 1
+
+        # Check expiry
+        expiry_str = package.get("expiry_date")
+        if expiry_str:
+            try:
+                expiry_date = date.fromisoformat(expiry_str)
+                days_left = (expiry_date - today).days
+                if 0 <= days_left <= 7:
+                    expiring_soon += 1
+            except ValueError:
+                pass
+
+    return {
+        "offerings": {
+            "total": len(offerings),
+            "freshness": freshness_counts,
+        },
+        "packages": {
+            "total": len(packages),
+            "types": package_types,
+            "expiring_soon": expiring_soon,
+        },
+    }
+
+
+def _metadata_packages_detail() -> list[dict[str, Any]]:
+    """Return detailed package information for dashboard."""
+    packages = get_packages_catalog()
+    today = date.today()
+    result = []
+    for package in packages.values():
+        expiry_str = package.get("expiry_date")
+        days_left = None
+        if expiry_str:
+            try:
+                expiry_date = date.fromisoformat(expiry_str)
+                days_left = (expiry_date - today).days
+            except ValueError:
+                pass
+        total = package.get("total_credits")
+        used = package.get("used_credits", 0)
+        remaining = total - used if total is not None else None
+        remaining_pct = (remaining / total * 100) if total and total > 0 else 0
+        result.append(
+            {
+                "package_id": package.get("package_id"),
+                "provider_id": package.get("provider_id"),
+                "name": package.get("name"),
+                "type": package.get("type"),
+                "total_credits": total,
+                "used_credits": used,
+                "remaining_credits": remaining,
+                "remaining_pct": remaining_pct,
+                "expiry_date": expiry_str,
+                "days_left": days_left,
+                "currency": package.get("currency"),
+                "price": package.get("price"),
+                "renewal_policy": package.get("renewal_policy"),
+                "notes": package.get("notes"),
+            }
+        )
+    # Sort by expiry (soonest first, then no expiry), then by remaining percentage (lowest first)
+    result.sort(
+        key=lambda p: (
+            0 if p["days_left"] is not None and p["days_left"] >= 0 else 1,
+            p["days_left"] if p["days_left"] is not None else float("inf"),
+            p["remaining_pct"] if p["remaining_pct"] is not None else float("inf"),
+        )
+    )
+    return result
+
+
 def _lane_family_summary(
     provider_rows: list[dict[str, Any]],
     provider_map: dict[str, dict[str, Any]],
@@ -1029,6 +1128,15 @@ def build_dashboard_report(
                 "review_now": _safe_int(provider_catalog_alert_summary.get("review_now")),
                 "inspect": _safe_int(provider_catalog_alert_summary.get("inspect")),
             },
+            "metadata_catalogs": {
+                "offerings_total": _safe_int(_metadata_catalogs_summary()["offerings"]["total"]),
+                "offerings_fresh": _safe_int(_metadata_catalogs_summary()["offerings"]["freshness"]["fresh"]),
+                "offerings_aging": _safe_int(_metadata_catalogs_summary()["offerings"]["freshness"]["aging"]),
+                "offerings_stale": _safe_int(_metadata_catalogs_summary()["offerings"]["freshness"]["stale"]),
+                "packages_total": _safe_int(_metadata_catalogs_summary()["packages"]["total"]),
+                "packages_expiring_soon": _safe_int(_metadata_catalogs_summary()["packages"]["expiring_soon"]),
+                "packages_detail": _metadata_packages_detail(),
+            },
             "drivers": {
                 "top_provider": top_provider,
                 "top_cost_provider": top_provider_cost,
@@ -1125,6 +1233,42 @@ def _render_overview(report: dict[str, Any]) -> str:
             f"  Recent changes     {_safe_int(report['cards']['provider_catalog']['recent_changes'])}",
         ]
     )
+
+    # Add metadata catalogs section
+    lines.extend(
+        [
+            "",
+            "Metadata catalogs",
+            f"  Offerings          {_safe_int(report['cards']['metadata_catalogs']['offerings_total'])} total ({_safe_int(report['cards']['metadata_catalogs']['offerings_fresh'])} fresh)",
+            f"  Packages           {_safe_int(report['cards']['metadata_catalogs']['packages_total'])} total ({_safe_int(report['cards']['metadata_catalogs']['packages_expiring_soon'])} expiring soon)",
+        ]
+    )
+    # Add package details if any packages exist
+    packages_detail = report["cards"]["metadata_catalogs"].get("packages_detail", [])
+    if packages_detail:
+        # Show top 3 packages (sorted by expiry and remaining)
+        lines.append("")
+        lines.append("  Package details")
+        for pkg in packages_detail[:3]:
+            provider = pkg.get("provider_id", "unknown")
+            name = pkg.get("name", "unnamed")
+            total = pkg.get("total_credits")
+            remaining = pkg.get("remaining_credits")
+            expiry = pkg.get("expiry_date")
+            days_left = pkg.get("days_left")
+            if total is not None and remaining is not None:
+                creds = f"{remaining}/{total}"
+                pct = pkg.get("remaining_pct", 0)
+                creds_line = f"{creds} ({pct:.0f}%)"
+            else:
+                creds_line = "n/a"
+            expiry_line = ""
+            if expiry:
+                if days_left is not None and days_left >= 0:
+                    expiry_line = f", expires in {days_left} day{'s' if days_left != 1 else ''}"
+                else:
+                    expiry_line = ", expired"
+            lines.append(f"    - {provider}: {name} ({creds_line}{expiry_line})")
     if report["alerts"]:
         alert = report["alerts"][0]
         lines.extend(

faigate/provider_catalog.py

@@ -331,6 +331,47 @@ def _get_provider_pricing(provider_name: str) -> dict[str, Any]:
     return pricing
 
 
+def _get_pricing_for_provider_and_model(provider_name: str, model_id: str | None = None) -> dict[str, Any]:
+    """Get pricing metadata for a provider and optional specific model.
+
+    First tries the offerings catalog for the exact model-provider pair.
+    If not found, falls back to provider-level pricing.
+    """
+    # If model_id is provided, try offerings catalog
+    if model_id:
+        offering_pricing = get_offering_pricing(model_id, provider_name)
+        if offering_pricing:
+            # Normalize field names (same mapping as in _get_provider_pricing)
+            field_mapping = {
+                "input_cost_per_1m": "input",
+                "output_cost_per_1m": "output",
+                "cache_read_cost_per_1m": "cache_read",
+            }
+            normalized = {}
+            for src, dst in field_mapping.items():
+                if src in offering_pricing and dst not in offering_pricing:
+                    normalized[dst] = offering_pricing[src]
+                elif dst in offering_pricing:
+                    normalized[dst] = offering_pricing[dst]
+            # Preserve other fields (source_type, freshness_status, etc.)
+            for key, value in offering_pricing.items():
+                if key not in normalized:
+                    normalized[key] = value
+            return normalized
+    # Fall back to provider-level pricing
+    return _get_provider_pricing(provider_name)
+
+
+def _get_packages_for_provider(provider_name: str) -> list[dict[str, Any]]:
+    """Return active packages for a provider from the packages catalog."""
+    packages_catalog = get_packages_catalog()
+    provider_packages = []
+    for package_id, package in packages_catalog.items():
+        if package.get("provider_id") == provider_name:
+            provider_packages.append(package)
+    return provider_packages
+
+
 _CATALOG: dict[str, dict[str, Any]] = {
     "deepseek-chat": {
         "recommended_model": get_active_model_id("deepseek/chat"),

faigate/router.py

@@ -6,10 +6,12 @@
 import re
 import time
 from dataclasses import dataclass, field
+from datetime import date
 from typing import Any
 
 from .config import Config
 from .lane_registry import get_canonical_model_catalog, get_canonical_model_routes
+from .provider_catalog import _get_packages_for_provider, _get_pricing_for_provider_and_model
 
 logger = logging.getLogger("faigate.router")
 _BOUNDARY_TEXT_RE = re.compile(r"[a-z0-9]")
@@ -612,6 +614,45 @@ def _estimated_request_cost_usd(provider: dict[str, Any], ctx: _RoutingContext |
     return round(prompt_cost + output_cost, 6)
 
 
+def _estimated_request_cost_usd_with_lane(
+    provider_name: str,
+    model_id: str | None,
+    provider: dict[str, Any],
+    ctx: _RoutingContext | None,
+) -> float:
+    """Estimate request cost using offerings catalog pricing if available."""
+    if ctx is None:
+        return 0.0
+    # First check provider config pricing
+    config_pricing = provider.get("pricing")
+    if config_pricing and isinstance(config_pricing, dict):
+        pricing = config_pricing
+    else:
+        pricing = _get_pricing_for_provider_and_model(provider_name, model_id)
+        if not pricing:
+            return 0.0
+    prompt_rate = float(pricing.get("input", 0) or 0)
+    output_rate = float(pricing.get("output", 0) or 0)
+    cache_rate = float(pricing.get("cache_read", prompt_rate) or 0)
+    prompt_tokens = max(1, int(ctx.total_tokens or 0))
+    output_tokens = int(ctx.requested_output_tokens or 0)
+    if output_tokens <= 0:
+        output_tokens = min(1024, max(128, prompt_tokens // 2))
+
+    cache_cfg = provider.get("cache") or {}
+    cache_mode = str(cache_cfg.get("mode") or "none")
+    cache_min_prefix = int(cache_cfg.get("min_prefix_tokens") or 64)
+    cache_threshold = max(64, cache_min_prefix)
+    if ctx.stable_prefix_tokens >= cache_threshold and cache_mode != "none":
+        cached_tokens = min(prompt_tokens, int(ctx.stable_prefix_tokens))
+        prompt_cost = ((cached_tokens * cache_rate) + ((prompt_tokens - cached_tokens) * prompt_rate)) / 1_000_000
+    else:
+        prompt_cost = (prompt_tokens * prompt_rate) / 1_000_000
+
+    output_cost = (output_tokens * output_rate) / 1_000_000
+    return round(prompt_cost + output_cost, 6)
+
+
 def _build_request_insights(
     *,
     last_user_message: str,
@@ -1572,7 +1613,8 @@ def _provider_dimension_details(
         benchmark_score = self._benchmark_posture_score(lane, routing_posture)
         benchmark_request_score = _benchmark_request_score(lane, ctx)
         cost_tier = str(capabilities.get("cost_tier") or lane.get("quality_tier") or "")
-        estimated_request_cost_usd = _estimated_request_cost_usd(provider, ctx)
+        model_id = lane.get("canonical_model")
+        estimated_request_cost_usd = _estimated_request_cost_usd_with_lane(name, model_id, provider, ctx)
         cost_score = _cost_posture_score(
             estimated_cost_usd=estimated_request_cost_usd,
             routing_posture=routing_posture,
@@ -1583,6 +1625,42 @@ def _provider_dimension_details(
         kilo_score = int(kilo_fit.get("score") or 0)
         adaptation_penalty = int(runtime_state.get("penalty", 0) or 0)
         recovery_score = self._recovery_posture_score(lane, runtime_state, routing_posture)
+        # Package score based on remaining credits and expiry
+        package_score = 0
+        package_details = []
+        packages = _get_packages_for_provider(name)
+        for pkg in packages:
+            total = pkg.get("total_credits")
+            used = pkg.get("used_credits", 0)
+            expiry = pkg.get("expiry_date")
+            if total is not None and total > 0:
+                remaining = total - used
+                remaining_ratio = remaining / total
+                # Score based on remaining ratio (0-5 points)
+                remaining_score = min(5, int(remaining_ratio * 5))
+                expiry_score = 0
+                if expiry:
+                    try:
+                        expiry_date = date.fromisoformat(expiry)
+                        days_left = (expiry_date - date.today()).days
+                        if days_left > 0:
+                            # Prefer packages that expire soon (use them up)
+                            if days_left <= 7:
+                                expiry_score = 5
+                            elif days_left <= 30:
+                                expiry_score = 2
+                    except ValueError:
+                        pass
+                package_score += remaining_score + expiry_score
+                package_details.append(
+                    {
+                        "package_id": pkg.get("package_id"),
+                        "remaining": remaining,
+                        "total": total,
+                        "expiry_date": expiry,
+                        "remaining_ratio": remaining_ratio,
+                    }
+                )
         image_score = 0
         image_policy_score = 0
         image_outputs_fit = True
@@ -1641,6 +1719,7 @@ def _provider_dimension_details(
             + freshness_score
             + kilo_score
             + recovery_score
+            + package_score
             + image_score
             + image_policy_score
             - adaptation_penalty
@@ -1671,6 +1750,8 @@ def _provider_dimension_details(
             "kilo_reasons": list(kilo_fit.get("reasons") or []),
             "adaptation_penalty": adaptation_penalty,
             "recovery_score": recovery_score,
+            "package_score": package_score,
+            "package_details": package_details,
             "image_score": image_score,
             "image_policy_score": image_policy_score,
             "headroom": headroom,

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "faigate"
-version = "1.16.0"
+version = "1.17.0"
 description = "Local OpenAI-compatible routing gateway for OpenClaw and other AI-native clients."
 readme = "README.md"
 license = "Apache-2.0"