backstage-agents 3.3.0__py3-none-any.whl

backstage/agents/__init__.py

@@ -0,0 +1,38 @@
+"""Khal Backstage — o SDK que o agente usa para escrever na Khal.
+
+    from backstage.agents import Backstage
+
+    backstage = Backstage(instance="https://agents-api.suaempresa.khal.app")
+
+    with backstage.session("conv-abc", contact="cus_987"):
+        backstage.identify("cus_987", identity={"name": "Maria Souza"},
+                      analytics={"cidade": "Recife"})
+        backstage.track("proposta.aceita", analytics={"valor": 850})
+        backstage.set_status("em-negociacao")
+
+As escritas voltam na hora: a rede é de uma thread de fundo, em lote, e nunca levanta.
+"""
+
+from ._client import Backstage
+from ._types import (
+    BackstageConfigurationError,
+    BackstageError,
+    BackstageInvalidEvent,
+    BackstageOrphanEvent,
+    Identity,
+    OutboxStats,
+    Stats,
+)
+from ._version import __version__
+
+__all__ = [
+    "Identity",
+    "Backstage",
+    "BackstageConfigurationError",
+    "BackstageError",
+    "BackstageInvalidEvent",
+    "BackstageOrphanEvent",
+    "OutboxStats",
+    "Stats",
+    "__version__",
+]

backstage/agents/_client.py

@@ -0,0 +1,353 @@
+"""A classe `Backstage`, a única superfície pública que escreve eventos."""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from datetime import datetime
+from typing import Any, Callable, List, Literal, Mapping, Optional, Tuple
+
+from . import _envelope, _lifecycle
+from ._config import Settings, env_flag, new_transport, resolve_settings
+from ._consumer import Consumer
+from ._context import SessionScope, current_contact, current_session
+from ._sink import NullSink, Sink
+from ._types import (
+    BackstageConfigurationError,
+    BackstageError,
+    BackstageInvalidEvent,
+    BackstageOrphanEvent,
+    ErrorHook,
+    Identity,
+    Stats,
+    notify_error,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class Backstage:
+    """O cliente. ⚠️ Um por processo, no escopo do módulo: um por requisição é uma fila e uma thread cada."""
+
+    def __init__(
+        self,
+        *,
+        instance: Optional[str] = None,
+        key_id: Optional[str] = None,
+        secret: Optional[str] = None,
+        enabled: Optional[bool] = None,
+        strict: bool = False,
+        on_error: Optional[ErrorHook] = None,
+        max_queue_size: int = 10_000,
+        batch_size: int = 100,
+        flush_interval: float = 2.0,
+        timeout: float = 10.0,
+    ) -> None:
+        self._strict = strict
+        self._on_error = on_error
+        self._orphans = 0
+        # Eventos que nem viraram envelope; entram em `stats().failed`.
+        self._invalid = 0
+        self._counters_lock = threading.Lock()
+        self._closed = False
+        # UM destino. A fila HTTP nasce na primeira escrita: com o outbox ligado antes dela, nunca nasce.
+        self._sink: Sink = NullSink()
+        self._sink_lock = threading.Lock()
+        # O que o finalizador enxerga: o sink atual, nunca `self`.
+        self._sink_box: List[Sink] = []
+
+        resolution = resolve_settings(
+            instance=instance,
+            key_id=key_id,
+            secret=secret,
+            enabled=enabled,
+            strict=strict,
+            on_error=on_error,
+            max_queue_size=max_queue_size,
+            batch_size=batch_size,
+            flush_interval=flush_interval,
+            timeout=timeout,
+        )
+        for warning in resolution.warnings:
+            logger.warning(warning)
+        if resolution.problem is not None:
+            if strict:
+                raise BackstageConfigurationError(resolution.problem)
+            logger.log(resolution.level, resolution.problem)
+        self._settings: Optional[Settings] = resolution.settings
+        if self._settings is None:
+            # Desligado é desligado: nenhuma thread, nenhuma fila, nenhum gancho.
+            return
+
+        logger.info("backstage: enviando para %s", self._settings.base_url)
+        # Sem isto a thread de um `Backstage()` coletado sem `close()` gira para sempre.
+        self._finalizer = _lifecycle.finalize_sink(self, self._sink_box)
+        _lifecycle.register(self)
+
+    # -- escrita -------------------------------------------------------------
+
+    def track(
+        self,
+        name: str,
+        properties: Optional[Mapping[str, Any]] = None,
+        *,
+        analytics: Optional[Mapping[str, Any]] = None,
+        display: Optional[Mapping[str, Any]] = None,
+        session: Optional[str] = None,
+        user: Optional[str] = None,
+        occurred_at: Optional[datetime] = None,
+    ) -> None:
+        """Registra que algo aconteceu. Volta na hora; nunca levanta.
+
+        `analytics`: candidato a dimensão de análise; `display`: texto para ler, nunca analisado;
+        `properties`: lido como `analytics` (que vence na chave repetida). Sem sessão nem `user=`,
+        o evento é órfão, e isso é válido.
+        """
+
+        if not self._writable():
+            return
+        session_ref, contact_ref = _scope_refs(session, user)
+        if session_ref is None and contact_ref is None:
+            if self._strict:
+                raise BackstageOrphanEvent(
+                    f"backstage: track({name!r}) sem session e sem user. "
+                    "Abra um `with backstage.session(...)` ou passe session=/user=."
+                )
+            # Sem log: um cron noturno é órfão por natureza.
+            with self._counters_lock:
+                self._orphans += 1
+        self._dispatch(
+            f"track({name!r})",
+            lambda: _envelope.track(
+                name=name,
+                session_ref=session_ref,
+                contact_ref=contact_ref,
+                occurred_at=occurred_at,
+                properties=properties,
+                analytics=analytics,
+                display=display,
+            ),
+        )
+
+    def identify(
+        self,
+        user: str,
+        traits: Optional[Mapping[str, Any]] = None,
+        *,
+        identity: Optional[Identity] = None,
+        display: Optional[Mapping[str, Any]] = None,
+        analytics: Optional[Mapping[str, Any]] = None,
+        session: Optional[str] = None,
+        occurred_at: Optional[datetime] = None,
+    ) -> None:
+        """Diz quem é a pessoa por trás do `contact_ref` (`user`). Volta na hora.
+
+        `identity`: a lista fechada que resolve a pessoa, nunca analisada; `display`: para ler;
+        `analytics`: candidato a dimensão; `traits`: o saco sem declaração.
+        """
+
+        if not self._writable():
+            return
+        session_ref, _ = _scope_refs(session, None)
+        # ⚠️ O rótulo não leva o `user`: é telefone ou e-mail, e iria para o log (LGPD).
+        self._dispatch(
+            "identify()",
+            lambda: _envelope.identify(
+                contact_ref=user,
+                session_ref=session_ref,
+                occurred_at=occurred_at,
+                traits=traits,
+                identity=identity,
+                analytics=analytics,
+                display=display,
+            ),
+        )
+
+    def set_status(
+        self,
+        status: str,
+        *,
+        session: Optional[str] = None,
+        note: Optional[str] = None,
+        occurred_at: Optional[datetime] = None,
+    ) -> None:
+        """Move a conversa para um status do catálogo (o slug ou o uuid). Volta na hora.
+
+        ⚠️ Exige a conversa (`session()` ou `session=`): sem ela, avisa sempre e conta em `failed`.
+        """
+
+        if not self._writable():
+            return
+        session_ref, _ = _scope_refs(session, None)
+        self._dispatch(
+            f"set_status({status!r})",
+            lambda: _envelope.status(
+                status_ref=status, session_ref=session_ref, note=note, occurred_at=occurred_at
+            ),
+        )
+
+    def session(self, session_id: str, *, contact: Optional[str] = None) -> SessionScope:
+        """Abre o escopo de uma conversa. Aninhar funciona; o argumento explícito vence o escopo."""
+
+        return SessionScope(session_id, contact)
+
+    # -- controle ------------------------------------------------------------
+
+    def flush(self, timeout: float = 5.0) -> bool:
+        """Espera o que já foi aceito ter veredito; com o outbox, até a memória entrar no banco e
+        `pending == 0`. `False` se estourou o prazo. Não é para cada turno: desfaz o lote."""
+
+        return self._sink.flush(timeout)
+
+    def close(self, timeout: float = 5.0) -> None:
+        """Drena com teto e para a thread. Idempotente; depois disto, no-op.
+
+        O prazo é UM para tudo: cada etapa recebe o que sobrou, não o `timeout` inteiro.
+        """
+
+        deadline = time.monotonic() + max(0.0, timeout)
+        # Sob o lock do `_ensure_sink`: um write que já passou do `_writable()` não cria fila depois daqui.
+        with self._sink_lock:
+            self._closed = True
+            sink = self._sink
+        sink.close(max(0.0, deadline - time.monotonic()))
+
+    def stats(self) -> Stats:
+        current = self._sink
+        sink = current.stats()
+        with self._counters_lock:
+            orphans, invalid = self._orphans, self._invalid
+        # O que não virou envelope entra em `failed`; `dropped` é só fila cheia.
+        return Stats(
+            queued=sink.queued,
+            sent=sink.sent,
+            dropped=sink.dropped,
+            failed=sink.failed + invalid,
+            orphans=orphans,
+            outbox=current.outbox_stats(),
+        )
+
+    @property
+    def enabled(self) -> bool:
+        return self._settings is not None
+
+    def __enter__(self) -> Backstage:
+        return self
+
+    def __exit__(self, *exc_info: object) -> Literal[False]:
+        self.close()
+        return False
+
+    # -- para as integrações -------------------------------------------------
+
+    @property
+    def _error_hook(self) -> Optional[ErrorHook]:
+        """O `on_error` do cliente, para quem precisa avisar pelo mesmo gancho (o tracker)."""
+
+        return self._on_error
+
+    def _attach_sink(self, sink: Sink, retire_timeout: float = 2.0) -> bool:
+        """Troca o destino (o outbox do Agno). A fila HTTP que já existia drena para a porta e fecha.
+
+        `False` com o cliente fechado: nada é trocado.
+        """
+
+        with self._sink_lock:
+            if self._closed:
+                return False
+            old = self._sink
+            self._set_sink(sink)
+        old.close(retire_timeout)
+        return True
+
+    # -- interno -------------------------------------------------------------
+
+    def _writable(self) -> bool:
+        # Lido a cada evento: o kill switch vale sem reiniciar o processo.
+        if self._settings is None or env_flag("BACKSTAGE_DISABLED"):
+            return False
+        if self._closed:
+            logger.warning("backstage: cliente ja fechado, evento ignorado")
+            return False
+        return True
+
+    def _dispatch(self, label: str, build: Callable[[], dict[str, Any]]) -> None:
+        """Monta, serializa e enfileira. Fora de `strict`, não levanta por nada.
+
+        `label` nomeia o evento no warning e nunca leva dado pessoal.
+        """
+
+        try:
+            # Montar e serializar no MESMO try: `dict(properties)` com o argumento errado
+            # também falha aqui, e não na cara de quem chamou.
+            envelope = build()
+            payload = _envelope.serialize(envelope, label)
+        except Exception as exc:  # noqa: BLE001 — nunca `BaseException`: o Ctrl-C passa
+            self._reject(label, exc)
+            return
+        sink = self._ensure_sink()
+        # Um sink fechado no meio da troca (`_attach_sink`) recusa; o novo recebe.
+        if not sink.submit(payload, envelope) and self._sink is not sink:
+            self._sink.submit(payload, envelope)
+
+    def _reject(self, label: str, exc: Exception) -> None:
+        """O único lugar que descarta um evento antes da fila."""
+
+        if self._strict:
+            if isinstance(exc, BackstageError):
+                raise exc
+            raise BackstageInvalidEvent(f"backstage: {label} nao virou envelope") from exc
+        logger.warning("backstage: %s nao virou envelope e foi ignorado: %s", label, exc)
+        with self._counters_lock:
+            self._invalid += 1
+        notify_error(self._on_error, exc)
+
+    def _ensure_sink(self) -> Sink:
+        sink = self._sink
+        if not isinstance(sink, NullSink) or self._settings is None:
+            return sink
+        with self._sink_lock:
+            if isinstance(self._sink, NullSink) and not self._closed:
+                settings = self._settings
+                self._set_sink(
+                    Consumer(
+                        new_transport(settings),
+                        max_queue_size=settings.max_queue_size,
+                        batch_size=settings.batch_size,
+                        flush_interval=settings.flush_interval,
+                        on_error=settings.on_error,
+                    )
+                )
+            return self._sink
+
+    def _set_sink(self, sink: Sink) -> None:
+        self._sink = sink
+        # A caixa aponta para o sink ATUAL, senão o finalizador pararia o velho depois do fork.
+        self._sink_box[:] = [sink]
+
+    # -- _lifecycle.Component ------------------------------------------------
+
+    def _wake(self) -> None:
+        self._sink.wake()
+
+    def _drain(self, deadline: float) -> int:
+        if self._sink.flush(max(0.0, deadline - time.monotonic())):
+            return 0
+        return self.stats().queued
+
+    def _after_fork(self) -> None:
+        # O fork não copia threads, e a fila herdada pode ter um lock travado.
+        self._sink_lock = threading.Lock()
+        self._set_sink(self._sink.after_fork())
+
+
+def _scope_refs(session: Optional[str], user: Optional[str]) -> Tuple[Optional[str], Optional[str]]:
+    """O argumento explícito vence o escopo; `""` é descuido, não referência."""
+
+    session_ref = session if session is not None else current_session()
+    contact_ref = user if user is not None else current_contact()
+    return (session_ref if session_ref != "" else None, contact_ref if contact_ref != "" else None)
+
+
+__all__ = ["Backstage"]

backstage/agents/_config.py

@@ -0,0 +1,125 @@
+"""A configuração do cliente, resolvida UMA vez: argumentos, ambiente e o que desliga."""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from typing import Mapping, Optional, Tuple
+
+from ._endpoints import normalize_instance
+from ._transport import Transport
+from ._types import ErrorHook
+
+_TRUTHY = frozenset({"1", "true", "yes", "on"})
+
+
+@dataclass(frozen=True)
+class Settings:
+    """O cliente ligado. Só existe com instância e credenciais válidas."""
+
+    base_url: str
+    key_id: str
+    secret: str
+    timeout: float
+    strict: bool
+    on_error: Optional[ErrorHook]
+    max_queue_size: int
+    batch_size: int
+    flush_interval: float
+
+
+@dataclass(frozen=True)
+class Resolution:
+    """`settings` é `None` quando o cliente fica em no-op; `problem` diz por quê (com o nível do log)."""
+
+    settings: Optional[Settings]
+    problem: Optional[str] = None
+    level: int = logging.WARNING
+    warnings: Tuple[str, ...] = ()
+
+
+def env_flag(name: str, environ: Optional[Mapping[str, str]] = None) -> bool:
+    value = (os.environ if environ is None else environ).get(name)
+    return value is not None and value.strip().lower() in _TRUTHY
+
+
+def resolve_settings(
+    *,
+    instance: Optional[str],
+    key_id: Optional[str],
+    secret: Optional[str],
+    enabled: Optional[bool],
+    strict: bool,
+    on_error: Optional[ErrorHook],
+    max_queue_size: int,
+    batch_size: int,
+    flush_interval: float,
+    timeout: float,
+    environ: Optional[Mapping[str, str]] = None,
+) -> Resolution:
+    """Pura: não loga nem levanta. Quem chama decide entre `logger` e `strict`."""
+
+    env = os.environ if environ is None else environ
+    if enabled is None:
+        enabled = not env_flag("BACKSTAGE_DISABLED", env)
+    if not enabled:
+        return Resolution(None)
+
+    warnings = []
+    credentials = []
+    for name, value in (("BACKSTAGE_KEY_ID", key_id), ("BACKSTAGE_SECRET", secret)):
+        value = value if value is not None else env.get(name)
+        # Um `\n` do `echo` ou do arquivo de segredo vira 401 eterno; o valor nunca vai ao log.
+        if value is not None and value != value.strip():
+            value = value.strip()
+            warnings.append(f"backstage: {name} tinha espaco ou quebra de linha nas pontas — removidos")
+        credentials.append(value or None)
+
+    if instance is None:
+        instance = env.get("BACKSTAGE_INSTANCE") or None
+    if instance is None:
+        return Resolution(
+            None,
+            "backstage: BACKSTAGE_INSTANCE ausente — diga a raiz da porta da sua instancia "
+            "(Backstage(instance=\"https://agents-api.suaempresa.khal.app\")). O cliente fica em no-op.",
+            logging.ERROR,
+            tuple(warnings),
+        )
+    url, reason = normalize_instance(instance)
+    if url is None:
+        return Resolution(None, f"backstage: {reason}. O cliente fica em no-op.", logging.ERROR, tuple(warnings))
+
+    key, sec = credentials
+    if not (key and sec):
+        return Resolution(
+            None,
+            "backstage: BACKSTAGE_KEY_ID e/ou BACKSTAGE_SECRET ausentes — o cliente fica em "
+            "no-op. Nenhum evento sera enviado.",
+            logging.WARNING,
+            tuple(warnings),
+        )
+    settings = Settings(
+        base_url=url,
+        key_id=key,
+        secret=sec,
+        timeout=timeout,
+        strict=strict,
+        on_error=on_error,
+        max_queue_size=max_queue_size,
+        batch_size=batch_size,
+        flush_interval=flush_interval,
+    )
+    return Resolution(settings, warnings=tuple(warnings))
+
+
+def new_transport(settings: Settings, timeout: Optional[float] = None) -> Transport:
+    return Transport(
+        base_url=settings.base_url,
+        key_id=settings.key_id,
+        secret=settings.secret,
+        timeout=settings.timeout if timeout is None else timeout,
+    )
+
+
+__all__ = ["Resolution", "Settings", "env_flag", "new_transport", "resolve_settings"]