feat: add cached prompt tokens and reported model to response types

src/polygateway/types.py

@@ -30,12 +30,20 @@ class LLMResponse:
     ttft_ms: float | None
     max_inter_token_ms: float | None
     cache_hit: bool
+    """**PolyGateway 自身响应缓存**命中(未产生网关调用);与供应商侧 prompt
+    cache 无关,后者见 `cached_prompt_tokens`。"""
     call_id: str
     # —— 库新增(只增不删,必带默认值;迁移兼容硬约束)——
     source_name: str = ""
     cost: float | None = None
     usage_source: str = "measured"
     structured_data: Any | None = None
+    cached_prompt_tokens: int | None = None
+    """供应商 prompt cache 命中的输入 token 数(issue #3);None = 该源未上报,
+    与"上报了但是 0"(真实零命中)区分——两者对下游的处置不同。"""
+    model_reported: str | None = None
+    """API 响应体里的 model 字段;None = 未上报。与 `model`(配置别名)可能
+    分叉——供应商把别名指向新权重时,实验复现必须认这个串。"""
 
 
 @dataclass(frozen=True)
@@ -82,6 +90,9 @@ class TransportResult:
     ttft_ms: float | None
     max_inter_token_ms: float | None
     raw: dict[str, Any]
+    # —— 可观测字段(issue #3;带默认值,非 OpenAI 兼容的 transport 可不填)——
+    cached_prompt_tokens: int | None = None
+    model_reported: str | None = None
 
 
 @dataclass(frozen=True)