wpmind/includes/Routing/RoutingContext.php

<?php
/**
 * Routing Context - 路由上下文
 *
 * 封装路由决策所需的所有上下文信息
 *
 * @package WPMind
 * @since 1.9.0
 */

declare(strict_types=1);

namespace WPMind\Routing;

use WPMind\Failover\ProviderHealthTracker;
use WPMind\Modules\CostControl\UsageTracker;

class RoutingContext
{
    /** @var string|null 请求的模型类型 (chat, completion, embedding) */
    private ?string $modelType = null;

    /** @var int 预估的输入 token 数 */
    private int $estimatedInputTokens = 0;

    /** @var int 预估的输出 token 数 */
    private int $estimatedOutputTokens = 0;

    /** @var string|null 用户首选的 Provider */
    private ?string $preferredProvider = null;

    /** @var array<string> 排除的 Provider 列表 */
    private array $excludedProviders = [];

    /** @var array<string, mixed> 额外的上下文数据 */
    private array $metadata = [];

    /** @var array|null 缓存的健康数据 */
    private ?array $healthData = null;

    /** @var array|null 缓存的使用统计 */
    private ?array $usageStats = null;

    /**
     * 创建新的路由上下文
     */
    public static function create(): self
    {
        return new self();
    }

    /**
     * 设置模型类型
     */
    public function with_model_type(string $type): self
    {
        $this->modelType = $type;
        return $this;
    }

    /**
     * 设置预估 token 数
     */
    public function with_estimated_tokens(int $input, int $output = 0): self
    {
        $this->estimatedInputTokens = max(0, $input);
        $this->estimatedOutputTokens = max(0, $output);
        return $this;
    }

    /**
     * 设置首选 Provider
     */
    public function with_preferred_provider(?string $providerId): self
    {
        $this->preferredProvider = $providerId;
        return $this;
    }

    /**
     * 添加排除的 Provider
     */
    public function with_excluded_provider(string $providerId): self
    {
        if (!in_array($providerId, $this->excludedProviders, true)) {
            $this->excludedProviders[] = $providerId;
        }
        return $this;
    }

    /**
     * 设置排除的 Provider 列表
     */
    public function with_excluded_providers(array $providerIds): self
    {
        $this->excludedProviders = array_values(array_unique($providerIds));
        return $this;
    }

    /**
     * 添加元数据
     */
    public function with_metadata(string $key, mixed $value): self
    {
        $this->metadata[$key] = $value;
        return $this;
    }

    // Getters

    public function get_model_type(): ?string
    {
        return $this->modelType;
    }

    public function get_estimated_input_tokens(): int
    {
        return $this->estimatedInputTokens;
    }

    public function get_estimated_output_tokens(): int
    {
        return $this->estimatedOutputTokens;
    }

    public function get_estimated_total_tokens(): int
    {
        return $this->estimatedInputTokens + $this->estimatedOutputTokens;
    }

    public function get_preferred_provider(): ?string
    {
        return $this->preferredProvider;
    }

    public function get_excluded_providers(): array
    {
        return $this->excludedProviders;
    }

    public function is_excluded(string $providerId): bool
    {
        return in_array($providerId, $this->excludedProviders, true);
    }

    public function get_metadata(string $key, mixed $default = null): mixed
    {
        return $this->metadata[$key] ?? $default;
    }

    public function get_all_metadata(): array
    {
        return $this->metadata;
    }

    /**
     * 获取 Provider 健康数据（带缓存）
     */
    public function get_health_data(): array
    {
        if ($this->healthData === null) {
            $this->healthData = ProviderHealthTracker::get_all_health();
        }
        return $this->healthData;
    }

    /**
     * 获取指定 Provider 的健康分数（使用缓存）
     */
    public function get_health_score(string $providerId): int
    {
        $healthData = $this->get_health_data();
        if (!isset($healthData[$providerId]) || empty($healthData[$providerId]['history'])) {
            return 100;
        }
        $history = $healthData[$providerId]['history'];
        $recentSuccesses = array_filter($history, fn($h) => $h['success']);
        return (int) round((count($recentSuccesses) / count($history)) * 100);
    }

    /**
     * 获取指定 Provider 的平均延迟（使用缓存）
     */
    public function get_average_latency(string $providerId): int
    {
        $healthData = $this->get_health_data();
        return $healthData[$providerId]['avg_latency'] ?? 0;
    }

    /**
     * 获取使用统计（带缓存）
     */
    public function get_usage_stats(): array
    {
        if ($this->usageStats === null) {
            $this->usageStats = UsageTracker::get_stats();
        }
        return $this->usageStats;
    }

    /**
     * 获取指定 Provider 的使用统计
     */
    public function get_provider_usage_stats(string $providerId): array
    {
        $stats = $this->get_usage_stats();
        return $stats['providers'][$providerId] ?? [
            'total_input_tokens' => 0,
            'total_output_tokens' => 0,
            'total_cost' => 0,
            'request_count' => 0,
        ];
    }

    /**
     * 计算指定 Provider 的预估成本
     */
    public function estimate_cost(string $providerId, string $model = 'default'): float
    {
        return UsageTracker::calculate_cost(
            $providerId,
            $model,
            $this->estimatedInputTokens,
            $this->estimatedOutputTokens
        );
    }
}