serigy 0.2.0__py3-none-any.whl

serigy/__init__.py

@@ -0,0 +1,44 @@
+"""Serigy — inferência pública (pip).
+
+Uso:
+    from serigy import SerigyModel, Escolha, Verdadeiro
+    model = SerigyModel("wendellperbar/serigy-jev")
+    out = model.predict("texto da notícia...")
+    result = model.system_one(state, {"q": Verdadeiro(instructions="…?")})
+
+Após cada upload no Hub, atualize DEFAULT_HUB_REVISION em cliente.py
+(pin atual: 785ef7e842fb82409af027b4f9ee217a4e72f9d7).
+"""
+
+from __future__ import annotations
+
+from serigy.cliente import DEFAULT_REPO, SerigyModel
+from serigy.primitivos.schemas import (
+    Escolha,
+    Indice,
+    Prioridade,
+    SystemOneRequest,
+    SystemOneResult,
+    Verdadeiro,
+)
+
+__all__ = [
+    "SerigyModel",
+    "DEFAULT_REPO",
+    "Escolha",
+    "Indice",
+    "Verdadeiro",
+    "Prioridade",
+    "SystemOneRequest",
+    "SystemOneResult",
+]
+
+try:
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        __version__ = version("serigy")
+    except PackageNotFoundError:
+        __version__ = "0.2.0"
+except ImportError:  # pragma: no cover
+    __version__ = "0.2.0"

serigy/__main__.py

@@ -0,0 +1,112 @@
+"""CLI: python -m serigy --texto "..." | --json '{...}' | --stdin."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from serigy.cliente import DEFAULT_REPO, SerigyModel, _saida_publica_system_one
+from serigy.primitivos.schemas import SystemOneRequest
+
+
+def _carregar_json(args: argparse.Namespace) -> dict[str, Any]:
+    if args.stdin:
+        return json.load(sys.stdin)
+    assert args.json is not None
+    raw = args.json
+    caminho = Path(raw)
+    if caminho.is_file():
+        return json.loads(caminho.read_text(encoding="utf-8"))
+    return json.loads(raw)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="serigy",
+        description="Inferência Serigy (schema público I/O)",
+    )
+    parser.add_argument(
+        "texto_posicional",
+        nargs="?",
+        default=None,
+        help="Texto da notícia (alternativa a --texto)",
+    )
+    parser.add_argument("--texto", default=None, help="Texto da notícia (predict)")
+    parser.add_argument("--fonte", default=None, help="Fonte opcional (predict)")
+    parser.add_argument(
+        "--json",
+        default=None,
+        help="System One: JSON (arquivo ou string) com state + questions",
+    )
+    parser.add_argument(
+        "--stdin",
+        action="store_true",
+        help="System One: ler envelope JSON de stdin",
+    )
+    parser.add_argument(
+        "--model",
+        default=DEFAULT_REPO,
+        help=f"Hub id ou pasta local (default: {DEFAULT_REPO})",
+    )
+    parser.add_argument(
+        "--revision",
+        default=None,
+        help="Revision Hub (commit/tag); default: SERIGY_HUB_REVISION / pin do pacote",
+    )
+    parser.add_argument(
+        "--allow-custom-models",
+        action="store_true",
+        help="Permite model_id/embedding fora da allowlist (só se confiar no checkpoint)",
+    )
+    parser.add_argument(
+        "--hf-token",
+        default=None,
+        help="Token HF (ou env HF_TOKEN)",
+    )
+    parser.add_argument(
+        "--warm",
+        action="store_true",
+        help="Pré-carrega o sensor antes da predição",
+    )
+    args = parser.parse_args(argv)
+
+    modo_system_one = bool(args.json or args.stdin)
+    texto = args.texto or args.texto_posicional
+    if modo_system_one and texto:
+        parser.error("use --texto OU --json/--stdin, não ambos")
+    if not modo_system_one and not texto:
+        parser.error("informe --texto, argumento posicional, --json ou --stdin")
+
+    print(f"carregando {args.model}…", file=sys.stderr)
+    model = SerigyModel(
+        args.model,
+        token=args.hf_token,
+        warm=args.warm,
+        revision=args.revision,
+        allow_custom_models=args.allow_custom_models,
+    )
+
+    if modo_system_one:
+        payload = _carregar_json(args)
+        req = SystemOneRequest.model_validate(payload)
+        result = model.system_one(req.state, req.questions)
+        out = _saida_publica_system_one(result)
+        print(json.dumps(out, ensure_ascii=False, indent=2))
+        return 0
+
+    out = model.predict(texto, fonte=args.fonte)
+    print(
+        f"→ {out['predicao']}  |  classe={out['classe_ordinal']}  "
+        f"|  score={out['score_final']:.3f}  "
+        f"|  confiança={out['confianca_calibrada']:.3f}",
+        file=sys.stderr,
+    )
+    print(json.dumps(out, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

serigy/api/__init__.py

@@ -0,0 +1,46 @@
+"""Schemas + motor de inferência (uso interno; API pública = SerigyModel)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from serigy.api.schemas import (
+    ComponentesConfianca,
+    CriteriosAvaliacao,
+    InputEco,
+    MetricasInferencia,
+    NivelOrdinal,
+    Noticia,
+    NoticiaRequest,
+    OutputPredicao,
+    PesosComponentes,
+    PredicaoResponse,
+    ProbabilidadesOrdinais,
+)
+
+if TYPE_CHECKING:
+    from serigy.api.inferencia import MotorInferencia, predizer
+
+__all__ = [
+    "Noticia",
+    "NivelOrdinal",
+    "CriteriosAvaliacao",
+    "NoticiaRequest",
+    "InputEco",
+    "ComponentesConfianca",
+    "PesosComponentes",
+    "ProbabilidadesOrdinais",
+    "OutputPredicao",
+    "MetricasInferencia",
+    "PredicaoResponse",
+    "MotorInferencia",
+    "predizer",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name in ("MotorInferencia", "predizer"):
+        from serigy.api import inferencia as _inf
+
+        return getattr(_inf, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

serigy/api/inferencia.py

@@ -0,0 +1,484 @@
+"""Inferência end-to-end: NoticiaRequest → PredicaoResponse (FASE 5)."""
+
+from __future__ import annotations
+
+import hashlib
+import time
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from serigy.api.schemas import (
+    ComponentesConfianca,
+    InputEco,
+    MetricasInferencia,
+    NoticiaRequest,
+    OutputPredicao,
+    PesosComponentes,
+    PredicaoResponse,
+    ProbabilidadesOrdinais,
+)
+from serigy.components.sistema import SistemaConfianca
+from serigy.config import CONFIG_PADRAO, ConfiguracaoSerigy, _raiz_repositorio
+from serigy.dados.extrator import ExtratorHiddenStates, ResultadoExtracao
+from serigy.checkpoint import carregar_sistema
+from serigy.utils.ordinal import aplicar_cabeca_ordinal
+
+
+def _como_float(x: Any) -> float:
+    """Extrai escalar de array NumPy / lista / float."""
+    arr = np.asarray(x, dtype=np.float64)
+    if arr.size == 0:
+        raise ValueError("valor vazio")
+    return float(arr.reshape(-1)[0])
+
+
+def resolver_checkpoint(config: ConfiguracaoSerigy | None = None) -> Path:
+    """
+    Resolve caminho do `.safetensors`.
+
+    Aceita:
+      - arquivo `.safetensors`
+      - diretório com `serigy.safetensors` / `serigy_jev.safetensors`
+      - único `.safetensors` no diretório
+    """
+    config = config or CONFIG_PADRAO
+    raiz = _raiz_repositorio()
+    base = Path(config.checkpoint_dir)
+    if not base.is_absolute():
+        base = raiz / base
+
+    if base.is_file() and base.suffix == ".safetensors":
+        return base
+
+    preferidos = (
+        "serigy.safetensors",
+        "serigy_jev.safetensors",
+        "modelo.safetensors",
+        "checkpoint.safetensors",
+    )
+    if base.is_dir():
+        for nome in preferidos:
+            candidato = base / nome
+            if candidato.is_file():
+                return candidato
+        encontrados = sorted(base.glob("*.safetensors"))
+        if encontrados:
+            return encontrados[0]
+
+    raise FileNotFoundError(
+        f"Checkpoint não encontrado em '{config.checkpoint_dir}'. "
+        "Baixe pesos do Hub (wendellperbar/serigy-jev) ou ajuste "
+        "SERIGY_CHECKPOINT_DIR / SerigyModel(caminho_local)."
+    )
+
+
+def gerar_request_id(texto: str) -> str:
+    """ID: serigy_<sha256[:16]><uuid8>."""
+    digest = hashlib.sha256(texto.encode("utf-8")).hexdigest()[:16]
+    return f"serigy_{digest}{uuid.uuid4().hex[:8]}"
+
+
+def _preparar_batch(extracao: ResultadoExtracao) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Garante shapes de batch=1 para o SistemaConfianca."""
+    h = np.asarray(extracao.h_final, dtype=np.float64)
+    e = np.asarray(extracao.e_ref, dtype=np.float64)
+    layers = np.asarray(extracao.h_layers, dtype=np.float64)
+
+    if h.ndim == 1:
+        h = h[None, :]
+    if e.ndim == 1:
+        e = e[None, :]
+    # Cconv aceita (L, dim); se vier (L, 1, dim) ok também
+    if layers.ndim == 2:
+        pass
+    elif layers.ndim == 3 and layers.shape[1] == 1:
+        layers = layers[:, 0, :]
+    return h, e, layers
+
+
+class MotorInferencia:
+    """
+    Orquestra extrator (sensor) + SistemaConfianca + cabeça ordinal.
+
+    Lazy-load do checkpoint; sensor sob demanda na primeira `predizer`.
+    """
+
+    def __init__(
+        self,
+        config: ConfiguracaoSerigy | None = None,
+        *,
+        caminho_checkpoint: Path | str | None = None,
+        extrator: ExtratorHiddenStates | None = None,
+        sistema: SistemaConfianca | None = None,
+        sigma: float | None = None,
+        prioridade_via_heads: bool | None = None,
+    ):
+        """
+        ``prioridade_via_heads``:
+          - ``None`` (auto): usa head nativa se existir ``serigy_heads.safetensors``
+            e ``prioridade_modo == "nativa"``; senão RBF legado.
+          - ``True`` / ``False``: força o caminho.
+        """
+        self.config = config or CONFIG_PADRAO
+        self._caminho_checkpoint = (
+            Path(caminho_checkpoint) if caminho_checkpoint else None
+        )
+        self._extrator = extrator
+        self._sistema = sistema
+        self._sigma = sigma
+        self._heads = None
+        self._prioridade_via_heads = prioridade_via_heads
+        self._heads_carregadas_do_disco = False
+
+    @property
+    def sigma(self) -> float:
+        self._garantir_sistema()
+        assert self._sigma is not None
+        return self._sigma
+
+    @property
+    def sistema(self) -> SistemaConfianca:
+        self._garantir_sistema()
+        assert self._sistema is not None
+        return self._sistema
+
+    def _garantir_sistema(self) -> None:
+        if self._sistema is not None and self._sigma is not None:
+            return
+        caminho = self._caminho_checkpoint or resolver_checkpoint(self.config)
+        self._sistema, self._sigma = carregar_sistema(caminho, config=self.config)
+
+    def _garantir_extrator(self) -> ExtratorHiddenStates:
+        if self._extrator is None:
+            self._extrator = ExtratorHiddenStates(self.config)
+        return self._extrator
+
+    def aquecer(self, *, carregar_sensor: bool = True) -> None:
+        """
+        Carrega checkpoint (+ sensor) antecipadamente.
+
+        Use no REPL para pagar o custo de Qwen uma vez só.
+        Com sensor, anexa MiniLM às heads (perguntas/opções/níveis).
+        """
+        self._garantir_sistema()
+        if carregar_sensor:
+            self._garantir_extrator().aquecer()
+            self._garantir_heads()
+            self._sincronizar_embedder_heads()
+
+    def _deve_usar_prioridade_heads(self) -> bool:
+        if self._prioridade_via_heads is False:
+            return False
+        if self._prioridade_via_heads is True:
+            return True
+        # auto: só se pesos treinados estiverem no disco (evita regressão com init aleatório)
+        path = self._caminho_heads()
+        return path is not None and path.is_file()
+
+    def _ordinal_de_heads(
+        self,
+        h_vec: np.ndarray,
+        criterios: Any,
+        *,
+        score_torre: float,
+    ) -> Any:
+        """Prioridade nativa no tronco; ``score_final`` da resposta = torre (compat API)."""
+        from serigy.primitivos.prioridade_util import criterios_para_prioridade_question
+        from serigy.utils.ordinal import ResultadoOrdinal
+
+        heads = self._garantir_heads()
+        if getattr(heads, "prioridade_modo", "nativa") == "rbf":
+            return aplicar_cabeca_ordinal(
+                score_torre, criterios, sigma=self._sigma or CONFIG_PADRAO.ordinal_sigma
+            )
+        q = criterios_para_prioridade_question(criterios)
+        ans = heads.avaliar_prioridade(h_vec, q, score_final=score_torre)
+        probs = ans.probabilities
+        return ResultadoOrdinal(
+            score_final=float(np.clip(score_torre, 0.0, 1.0)),
+            probabilidades=(
+                float(probs["0"]),
+                float(probs["1"]),
+                float(probs["2"]),
+            ),
+            classe_ordinal=int(ans.classe_ordinal),
+            predicao=ans.predicao,
+            entropia_shannon=float(ans.entropia_shannon),
+            confianca_calibrada=float(ans.confianca_calibrada),
+        )
+
+    def predizer_de_features(
+        self,
+        request: NoticiaRequest | dict[str, Any],
+        extracao: ResultadoExtracao,
+        *,
+        tempo_ms: float = 0.0,
+        request_id: str | None = None,
+    ) -> PredicaoResponse:
+        """Forward a partir de features já extraídas (testes / cache)."""
+        if isinstance(request, dict):
+            request = NoticiaRequest.model_validate(request)
+
+        self._garantir_sistema()
+        assert self._sistema is not None and self._sigma is not None
+
+        h, e, layers = _preparar_batch(extracao)
+        bruto = self._sistema(
+            estado_oculto=h,
+            embedding_referencia=e,
+            estados_camadas=layers,
+        )
+        csem = _como_float(bruto["score_csem"])
+        cconv = _como_float(bruto["score_cconv"])
+        clearned = _como_float(bruto["score_clearned"])
+        score_final = _como_float(bruto["score_final"])
+        h_vec = np.asarray(h, dtype=np.float64).reshape(-1)
+
+        w = self._sistema.config.pesos_normalizados
+        if self._deve_usar_prioridade_heads():
+            ordinal = self._ordinal_de_heads(
+                h_vec, request.criterios_avaliacao, score_torre=score_final
+            )
+        else:
+            ordinal = aplicar_cabeca_ordinal(
+                score_final,
+                request.criterios_avaliacao,
+                sigma=self._sigma,
+            )
+
+        return PredicaoResponse(
+            model=self.config.model_version,
+            timestamp=datetime.now(timezone.utc),
+            input=InputEco(
+                texto=request.noticia.texto,
+                fonte=request.noticia.fonte,
+                timestamp=request.noticia.timestamp,
+            ),
+            criterios=request.criterios_avaliacao.mapa_labels(),
+            output=OutputPredicao(
+                predicao=ordinal.predicao,
+                classe_ordinal=ordinal.classe_ordinal,  # type: ignore[arg-type]
+                score_final=ordinal.score_final,
+                confianca_calibrada=ordinal.confianca_calibrada,
+                entropia_shannon=ordinal.entropia_shannon,
+                componentes=ComponentesConfianca(
+                    csem=csem, cconv=cconv, clearned=clearned
+                ),
+                pesos=PesosComponentes(
+                    w_csem=w[0], w_cconv=w[1], w_clearned=w[2]
+                ),
+                probabilidades=ProbabilidadesOrdinais.model_validate(
+                    ordinal.probs_dict()
+                ),
+            ),
+            metricas=MetricasInferencia(
+                tempo_ms=float(tempo_ms),
+                input_tokens=int(extracao.input_tokens),
+                output_tokens=0,
+            ),
+            request_id=request_id or gerar_request_id(request.noticia.texto),
+        )
+
+    def predizer(
+        self,
+        request: NoticiaRequest | dict[str, Any],
+        *,
+        request_id: str | None = None,
+    ) -> PredicaoResponse:
+        """Pipeline completo: texto → sensor → componentes → ordinal → response."""
+        if isinstance(request, dict):
+            request = NoticiaRequest.model_validate(request)
+
+        t0 = time.perf_counter()
+        extracao = self._garantir_extrator().extrair(request.noticia.texto)
+        tempo_ms = (time.perf_counter() - t0) * 1000.0
+
+        return self.predizer_de_features(
+            request,
+            extracao,
+            tempo_ms=tempo_ms,
+            request_id=request_id,
+        )
+
+    def computar_score_final(
+        self,
+        texto: str,
+        *,
+        extracao: ResultadoExtracao | None = None,
+    ) -> tuple[float, int, float]:
+        """
+        Uma passagem sensor+sistema → (score_final, input_tokens, tempo_ms).
+
+        Usado por system_one (adapters) para não reextrair por pergunta.
+        """
+        score_final, _h, tokens, tempo = self.computar_representacao(
+            texto, extracao=extracao
+        )
+        return score_final, tokens, tempo
+
+    def computar_representacao(
+        self,
+        texto: str,
+        *,
+        extracao: ResultadoExtracao | None = None,
+    ) -> tuple[float, np.ndarray, int, float]:
+        """
+        Sensor+sistema → (score_final, h_state, input_tokens, tempo_ms).
+
+        ``h_state`` alimenta as perguntas tipadas System One.
+        """
+        self._garantir_sistema()
+        assert self._sistema is not None
+
+        t0 = time.perf_counter()
+        if extracao is None:
+            extracao = self._garantir_extrator().extrair(texto)
+            tempo_ms = (time.perf_counter() - t0) * 1000.0
+        else:
+            tempo_ms = 0.0
+
+        h, e, layers = _preparar_batch(extracao)
+        bruto = self._sistema(
+            estado_oculto=h,
+            embedding_referencia=e,
+            estados_camadas=layers,
+        )
+        score_final = _como_float(bruto["score_final"])
+        h_vec = np.asarray(h, dtype=np.float64).reshape(-1)
+        return score_final, h_vec, int(extracao.input_tokens), float(tempo_ms)
+
+    def _caminho_heads(self) -> Path | None:
+        caminho = self._caminho_checkpoint
+        if caminho is None:
+            try:
+                caminho = resolver_checkpoint(self.config)
+            except FileNotFoundError:
+                return None
+        from serigy.primitivos.persist import caminho_heads_ao_lado
+
+        return caminho_heads_ao_lado(caminho)
+
+    def _garantir_heads(self) -> Any:
+        if getattr(self, "_heads", None) is not None:
+            return self._heads
+
+        from serigy.primitivos.encode import HashTextEmbedder
+        from serigy.primitivos.heads import ConfigHeads, SistemaHeads
+        from serigy.primitivos.persist import carregar_heads
+
+        dim_q = int(self.config.embedding_dim)
+        heads_path = self._caminho_heads()
+        if heads_path is not None and heads_path.is_file():
+            # embedder=None → HashTextEmbedder com seed gravado no checkpoint
+            self._heads = carregar_heads(heads_path, embedder=None)
+            self._heads_carregadas_do_disco = True
+        else:
+            # dim_h: projeção do h do sensor; dim_q alinhado ao MiniLM
+            self._heads = SistemaHeads(
+                ConfigHeads(dim_h=256, dim_q=dim_q, dim_z=256),
+                embedder=HashTextEmbedder(dim_q, seed=7),
+            )
+            self._heads_carregadas_do_disco = False
+        self._sincronizar_embedder_heads()
+        return self._heads
+
+    def _sincronizar_embedder_heads(self) -> None:
+        """Se MiniLM já estiver carregado no extrator, usa-o nas perguntas."""
+        if self._heads is None:
+            return
+        if getattr(self._heads, "_embedder_fonte", None) == "minilm":
+            return
+        ext = self._extrator
+        if ext is None or getattr(ext, "_sentence_model", None) is None:
+            return
+        from serigy.primitivos.encode import CallableTextEmbedder
+
+        dim_q = int(self._heads.config.dim_q)
+
+        def _batch(textos: list[str]) -> np.ndarray:
+            return np.asarray(ext.embed_texts(textos), dtype=np.float64)
+
+        self._heads.definir_embedder(
+            CallableTextEmbedder(_batch, dim_q, batch=True),
+            fonte="minilm",
+        )
+
+    def system_one(
+        self,
+        state: str | dict[str, Any] | list[Any] | Any,
+        questions: dict[str, Any] | None = None,
+        *,
+        extracao: ResultadoExtracao | None = None,
+        usar_heads: bool | None = None,
+    ) -> Any:
+        """
+        System One: um state, N perguntas tipadas.
+
+        ``usar_heads`` é interno (testes/monorepo):
+          - ``None`` (default): usa sidecar de heads se existir; senão caminho legado
+          - ``True`` / ``False``: força o caminho
+        """
+        from serigy.primitivos.system_one import (
+            normalizar_request,
+            system_one_de_heads,
+            system_one_de_score,
+        )
+
+        texto, qs, model = normalizar_request(
+            state,
+            questions,
+            model=self.config.model_version,
+        )
+        self._garantir_sistema()
+        assert self._sigma is not None
+        score_final, h_vec, tokens, _tempo = self.computar_representacao(
+            texto, extracao=extracao
+        )
+        modelo = model or self.config.model_version
+        if usar_heads is None:
+            heads_path = self._caminho_heads()
+            if heads_path is not None and heads_path.is_file():
+                usar_heads = True
+            else:
+                # Adapters legados só cobrem Escolha N=3; N≠3 exige heads.
+                from serigy.primitivos.schemas import EscolhaQuestion
+
+                usar_heads = any(
+                    isinstance(q, EscolhaQuestion) and len(q.criteria) != 3
+                    for q in qs.values()
+                )
+        if usar_heads:
+            heads = self._garantir_heads()
+            self._sincronizar_embedder_heads()
+            return system_one_de_heads(
+                h_vec,
+                qs,
+                heads,
+                score_final=score_final,
+                model=modelo,
+                input_tokens=tokens,
+                sigma=self._sigma,
+            )
+        return system_one_de_score(
+            score_final,
+            qs,
+            model=modelo,
+            input_tokens=tokens,
+            sigma=self._sigma,
+        )
+
+
+def predizer(
+    request: NoticiaRequest | dict[str, Any],
+    *,
+    config: ConfiguracaoSerigy | None = None,
+    caminho_checkpoint: Path | str | None = None,
+) -> PredicaoResponse:
+    """Atalho one-shot (preferir `MotorInferencia` para reuso do sensor)."""
+    return MotorInferencia(
+        config=config, caminho_checkpoint=caminho_checkpoint
+    ).predizer(request)