YoVinchen
f4ba5d5342
Some checks failed
verify / verify (push) Has been cancelled
The Stage 1 foundation now proves provider contracts with mocks and validates PostgreSQL/pgvector ingestion, approval binding, retrieval, reranking, and idempotency using only synthetic data. Live Bailian validation remains gated on rotating the exposed key. Constraint: The key shown in chat is compromised and cannot be used or committed Rejected: Mark Stage 1 complete from mock and offline results | real three-model smoke is still required Confidence: high Scope-risk: moderate Reversibility: clean Directive: Do not enable real-data ingestion until Stage 3 cloud approval and outbound manifest controls are enforced end to end Tested: make verify; 41 pytest tests; strict mypy; Ruff; Compose config; pinned image build; empty-volume migration; role denial; two idempotent 20-vector seeds; database restart persistence Not-tested: Live Bailian calls require a newly rotated key; React product UI is not implemented
152 lines
3.7 KiB
Python
152 lines
3.7 KiB
Python
"""Dependency-inversion ports for external model providers.
|
|
|
|
The domain and service layers depend on these provider-neutral value objects and
|
|
protocols. Vendor SDK/HTTP response objects must not cross this boundary.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from collections.abc import AsyncIterator, Callable, Sequence
|
|
from dataclasses import dataclass
|
|
from enum import StrEnum
|
|
from typing import Protocol
|
|
|
|
TokenCounter = Callable[[str], int]
|
|
|
|
|
|
class ProviderErrorKind(StrEnum):
|
|
"""Stable, provider-neutral error categories."""
|
|
|
|
INVALID_REQUEST = "invalid_request"
|
|
AUTHENTICATION = "authentication"
|
|
PERMISSION_DENIED = "permission_denied"
|
|
NOT_FOUND = "not_found"
|
|
RATE_LIMITED = "rate_limited"
|
|
TIMEOUT = "timeout"
|
|
TRANSPORT = "transport"
|
|
UPSTREAM = "upstream"
|
|
INVALID_RESPONSE = "invalid_response"
|
|
|
|
|
|
class ModelProviderError(RuntimeError):
|
|
"""Sanitized provider failure safe for structured application handling.
|
|
|
|
The exception intentionally never stores request payloads, response bodies,
|
|
HTTP request objects, headers, or credentials.
|
|
"""
|
|
|
|
def __init__(
|
|
self,
|
|
*,
|
|
operation: str,
|
|
kind: ProviderErrorKind,
|
|
status_code: int | None = None,
|
|
provider_code: str | None = None,
|
|
request_id: str | None = None,
|
|
retryable: bool = False,
|
|
) -> None:
|
|
self.operation = operation
|
|
self.kind = kind
|
|
self.status_code = status_code
|
|
self.provider_code = provider_code
|
|
self.request_id = request_id
|
|
self.retryable = retryable
|
|
|
|
details = [f"kind={kind.value}"]
|
|
if status_code is not None:
|
|
details.append(f"status={status_code}")
|
|
if provider_code is not None:
|
|
details.append(f"code={provider_code}")
|
|
super().__init__(f"model provider {operation} failed ({', '.join(details)})")
|
|
|
|
|
|
@dataclass(frozen=True, slots=True)
|
|
class ProviderUsage:
|
|
input_tokens: int | None = None
|
|
output_tokens: int | None = None
|
|
total_tokens: int | None = None
|
|
|
|
|
|
@dataclass(frozen=True, slots=True)
|
|
class EmbeddingResult:
|
|
vectors: tuple[tuple[float, ...], ...]
|
|
model: str
|
|
request_id: str | None
|
|
usage: ProviderUsage
|
|
elapsed_ms: float
|
|
|
|
|
|
@dataclass(frozen=True, slots=True)
|
|
class RankedItem:
|
|
index: int
|
|
relevance_score: float
|
|
document: str
|
|
|
|
|
|
@dataclass(frozen=True, slots=True)
|
|
class RerankResult:
|
|
items: tuple[RankedItem, ...]
|
|
model: str
|
|
request_id: str | None
|
|
usage: ProviderUsage
|
|
elapsed_ms: float
|
|
|
|
|
|
@dataclass(frozen=True, slots=True)
|
|
class ChatMessage:
|
|
role: str
|
|
content: str
|
|
|
|
|
|
@dataclass(frozen=True, slots=True)
|
|
class ChatCompletionResult:
|
|
content: str
|
|
finish_reason: str | None
|
|
model: str
|
|
request_id: str | None
|
|
usage: ProviderUsage
|
|
elapsed_ms: float
|
|
|
|
|
|
@dataclass(frozen=True, slots=True)
|
|
class ChatStreamEvent:
|
|
delta: str
|
|
finish_reason: str | None
|
|
model: str
|
|
request_id: str | None
|
|
usage: ProviderUsage
|
|
elapsed_ms: float
|
|
|
|
|
|
class EmbeddingProvider(Protocol):
|
|
async def embed_documents(self, texts: Sequence[str]) -> EmbeddingResult: ...
|
|
|
|
async def embed_query(self, text: str) -> EmbeddingResult: ...
|
|
|
|
|
|
class Reranker(Protocol):
|
|
async def rerank(
|
|
self,
|
|
query: str,
|
|
documents: Sequence[str],
|
|
*,
|
|
top_n: int,
|
|
instruct: str | None = None,
|
|
) -> RerankResult: ...
|
|
|
|
|
|
class ChatProvider(Protocol):
|
|
async def complete(
|
|
self,
|
|
messages: Sequence[ChatMessage],
|
|
*,
|
|
max_tokens: int,
|
|
) -> ChatCompletionResult: ...
|
|
|
|
def stream(
|
|
self,
|
|
messages: Sequence[ChatMessage],
|
|
*,
|
|
max_tokens: int,
|
|
) -> AsyncIterator[ChatStreamEvent]: ...
|