feat: OSCBR optional provider, re-baseline after inactivity, field audit, provider UI/feature matrix tests, benchmark chain; 1.3.1

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

central/app/config.py

@@ -79,6 +79,8 @@ class Settings:
     ai_base_url: str = os.getenv("AI_BASE_URL", "https://api.z.ai/api/paas/v4")
     # ---- Product enrichment (docs/product_enrichment.md): free providers only, tokens live ONLY in the Hub environment ----
     cosmos_token: str = os.getenv("COSMOS_TOKEN", "")          # optional; without it Cosmos is NOT_CONFIGURED (not an error)
+    oscbr_user: str = os.getenv("OSCBR_USER", "")              # optional free-plan account of gtin.rscsistemas.com.br (never in logs/UI)
+    oscbr_password: str = os.getenv("OSCBR_PASSWORD", "")
     allow_paid_providers: bool = os.getenv("ALLOW_PAID_PROVIDERS", "0") == "1"
     official_refresh_enabled: bool = os.getenv("OFFICIAL_REFRESH_ENABLED", "1") == "1"
     enrichment_time_budget_seconds: float = float(os.getenv("ENRICHMENT_TIME_BUDGET_SECONDS", "4.5"))

central/app/enrichment/providers.py

@@ -225,9 +225,71 @@ class Cosmos(Provider):
         return out
 
 
+class Oscbr(Provider):
+    """OSCBR / RSC Sistemas GTIN API (https://gtin.rscsistemas.com.br). Free plan (no card): 20 req/min; account created BY THE OPERATOR, credentials only in the Hub env
+    (OSCBR_USER / OSCBR_PASSWORD). Bearer token lasts 1 h and is renewed automatically. Optional: NOT_CONFIGURED without credentials (no call is made)."""
+    name = "oscbr"
+    rate_per_minute = 20
+    provides_ncm = True
+    base = "https://gtin.rscsistemas.com.br"
+
+    def __init__(self, client=None, token=None, user=None, password=None):
+        super().__init__(client, token)
+        self._user, self._password = user, password
+        self._bearer, self._bearer_until = None, 0.0
+
+    @property
+    def configured(self) -> bool:
+        return bool(self._user and self._password)
+
+    def _auth(self) -> str:
+        if self._bearer and time.time() < self._bearer_until:
+            return self._bearer
+        try:
+            response = self.client.post(f"{self.base}/oauth/token", auth=(self._user, self._password), headers={"User-Agent": USER_AGENT})
+        except httpx.TimeoutException as error:
+            raise ProviderError("TIMEOUT", type(error).__name__) from error
+        except httpx.HTTPError as error:
+            raise ProviderError("NETWORK", type(error).__name__) from error
+        if response.status_code in (400, 401, 403):
+            raise ProviderError("AUTH_ERROR", f"HTTP {response.status_code}")
+        if response.status_code == 429:
+            raise ProviderError("RATE_LIMITED", "HTTP 429")
+        if response.status_code >= 500 or response.status_code != 200:
+            raise ProviderError("SERVER_ERROR", f"HTTP {response.status_code}")
+        try:
+            token = response.json().get("token") or response.json().get("access_token")
+        except ValueError as error:
+            raise ProviderError("BAD_RESPONSE", "not JSON") from error
+        if not token:
+            raise ProviderError("BAD_RESPONSE", "no token")
+        self._bearer, self._bearer_until = token, time.time() + 55 * 60
+        return token
+
+    def lookup_gtin(self, gtin: str) -> ProviderProduct:
+        if not self.configured:
+            raise ProviderError("AUTH_ERROR", "NOT_CONFIGURED")
+        response = self._get(f"{self.base}/api/gtin/infor/{gtin}", headers={"Authorization": f"Bearer {self._auth()}", "User-Agent": USER_AGENT})
+        headers = {k.lower(): v for k, v in response.headers.items()}
+        if response.status_code == 404:
+            return ProviderProduct(self.name, gtin, False, latency_ms=getattr(response, "latency_ms", 0), headers=headers)
+        if response.status_code != 200:
+            raise ProviderError("BAD_RESPONSE", f"HTTP {response.status_code}")
+        try:
+            body = response.json()
+        except ValueError as error:
+            raise ProviderError("BAD_RESPONSE", "not JSON") from error
+        if isinstance(body, list):
+            body = body[0] if body else {}
+        if not body or not (body.get("nome") or body.get("ncm")):
+            return ProviderProduct(self.name, gtin, False, latency_ms=getattr(response, "latency_ms", 0), headers=headers)
+        return ProviderProduct(self.name, gtin, True, title=body.get("nome"), brand=body.get("marca"), category=body.get("categoria"), ncm=_digits(body.get("ncm")), cest=_digits(body.get("cest")),
+                               raw_hash=hashlib.sha256(json.dumps(body, sort_keys=True, ensure_ascii=False).encode()).hexdigest(), latency_ms=getattr(response, "latency_ms", 0), headers=headers)
+
+
 def build_providers(settings, client: httpx.Client | None = None) -> list[Provider]:
-    """Fixed order chosen from the benchmark (docs/product_enrichment.md): Cosmos (fiscal-capable) first when configured, then UPCitemdb, then the Open *Facts family (food, general products, beauty; identity only). Paid providers do not exist here."""
-    providers: list[Provider] = [Cosmos(client, getattr(settings, "cosmos_token", None)), UpcItemDb(client), OpenFoodFacts(client), OpenProductsFacts(client), OpenBeautyFacts(client)]
+    """Fixed order chosen from the benchmark (docs/product_enrichment.md): Cosmos then OSCBR (fiscal-capable) first when configured, then UPCitemdb, then the Open *Facts family (food, general products, beauty; identity only). Paid providers do not exist here."""
+    providers: list[Provider] = [Cosmos(client, getattr(settings, "cosmos_token", None)), Oscbr(client, None, getattr(settings, "oscbr_user", None), getattr(settings, "oscbr_password", None)), UpcItemDb(client), OpenFoodFacts(client), OpenProductsFacts(client), OpenBeautyFacts(client)]
     if any(p.paid for p in providers) and not getattr(settings, "allow_paid_providers", False):
         raise RuntimeError("paid providers are not allowed (ALLOW_PAID_PROVIDERS=false)")
     return providers

central/app/version.py

@@ -4,5 +4,5 @@ kept identical to this) and what an AgentRelease row's `version` column holds
 once published — never a second, independent version number. Fiscal semantics
 are versioned separately (ENGINE_VERSION/DECISION_VERSION in classification.py,
 DECISION_ENGINE_VERSION etc.) and are NOT changed by a release bump."""
-GTI_FISCAL_VERSION = "1.3.0"
+GTI_FISCAL_VERSION = "1.3.1"
 API_COMPAT_MAJOR_MINOR = "1.0"  # an Agent 1.0.x/1.1.x talks to any Hub 1.0.x