decision-cascade 1.0.0__py3-none-any.whl

api/sdk/agent.py

@@ -0,0 +1,145 @@
+"""Маршрутизация обращения по решениям decision-cascade.
+
+Показывает типичную интеграцию «мозга решений» в чат-агента: по типизированным
+решениям (noul/choice/score) выбирается команда, приоритет, эскалация и тон
+ответа. Логика чистая (без сети) и легко тестируется отдельно от SDK.
+
+Каскад: ``route_ticket`` решает, нужна ли эскалация; вызывающий код (см.
+``examples/integrations/chat_agent.py``) может на этом основании переспросить внешний сервис.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+PRIORITIES = ("low", "normal", "high", "urgent")
+
+
+@dataclass(frozen=True)
+class RoutingPolicy:
+    """Пороги, по которым решения превращаются в действие агента."""
+
+    escalate_threshold: float = 0.5
+    urgent_threshold: float = 0.6
+    high_threshold: float = 0.3
+    churn_threshold: float = 3.0
+    heat_urgent: float = 3.5
+    heat_high: float = 2.0
+    default_team: str = "общая поддержка"
+
+
+@dataclass(frozen=True)
+class AgentAction:
+    team: str
+    priority: str
+    escalate: bool
+    tone: str
+    reply: str
+    rationale: tuple[str, ...] = ()
+
+
+def _noul(decisions: dict[str, Any], key: str) -> float | None:
+    d = decisions.get(key)
+    if isinstance(d, dict) and d.get("type") == "noul":
+        return float(d["noul"])
+    return None
+
+
+def _choice(decisions: dict[str, Any], key: str) -> str | None:
+    d = decisions.get(key)
+    if isinstance(d, dict) and d.get("type") == "choice" and "choice" in d:
+        return str(d["choice"])
+    return None
+
+
+def _score(decisions: dict[str, Any], key: str) -> float | None:
+    d = decisions.get(key)
+    if isinstance(d, dict) and d.get("type") == "score":
+        return float(d["score"])
+    return None
+
+
+def _priority(
+    urgency: float,
+    heat: float,
+    churn: float,
+    policy: RoutingPolicy,
+    rationale: list[str],
+) -> str:
+    if urgency >= policy.urgent_threshold or heat >= policy.heat_urgent:
+        rationale.append(
+            f"срочность={urgency:.2f}, накал={heat:.2f} -> urgent"
+        )
+        return "urgent"
+    if urgency >= policy.high_threshold or heat >= policy.heat_high or churn >= policy.churn_threshold:
+        rationale.append(
+            f"срочность={urgency:.2f}, накал={heat:.2f}, отток={churn:.2f} -> high"
+        )
+        return "high"
+    if urgency < 0.2 and heat < 1.0:
+        rationale.append("низкая срочность и низкий накал -> low")
+        return "low"
+    return "normal"
+
+
+def _tone(heat: float, churn: float) -> str:
+    if heat >= 3.0:
+        return "извиняющийся"
+    if heat >= 1.5 or churn >= 3.0:
+        return "эмпатичный"
+    return "нейтральный"
+
+
+def _reply(team: str, priority: str, tone: str, escalate: bool) -> str:
+    if tone == "извиняющийся":
+        opening = "Приносим извинения за доставленные неудобства."
+    elif tone == "эмпатичный":
+        opening = "Понимаю, как это неприятно."
+    else:
+        opening = "Спасибо за обращение."
+    if escalate:
+        return (
+            f"{opening} Передаю обращение старшему инженеру "
+            f"(команда «{team}», приоритет: {priority})."
+        )
+    return f"{opening} Обращение принято в команду «{team}» (приоритет: {priority})."
+
+
+def route_ticket(
+    decisions: dict[str, Any],
+    policy: RoutingPolicy | None = None,
+) -> AgentAction:
+    """Превращает решения по обращению в действие чат-агента.
+
+    Ожидаемые вопросы (любой можно опустить): ``срочность``/``эскалация`` (noul),
+    ``команда`` (choice), ``накал``/``удержание`` (score).
+    """
+    policy = policy or RoutingPolicy()
+    rationale: list[str] = []
+
+    team = _choice(decisions, "команда") or policy.default_team
+    if team != policy.default_team:
+        rationale.append(f"команда из решения: {team!r}")
+
+    urgency = _noul(decisions, "срочность") or 0.0
+    escalation = _noul(decisions, "эскалация") or 0.0
+    heat = _score(decisions, "накал") or 0.0
+    churn = _score(decisions, "удержание") or 0.0
+
+    priority = _priority(urgency, heat, churn, policy, rationale)
+    escalate = escalation >= policy.escalate_threshold or priority == "urgent"
+    if escalate:
+        rationale.append(
+            f"эскалация={escalation:.2f} (порог {policy.escalate_threshold:.2f})"
+        )
+    tone = _tone(heat, churn)
+    rationale.append(f"тон ответа: {tone}")
+
+    return AgentAction(
+        team=team,
+        priority=priority,
+        escalate=escalate,
+        tone=tone,
+        reply=_reply(team, priority, tone, escalate),
+        rationale=tuple(rationale),
+    )

api/sdk/client.py

@@ -0,0 +1,127 @@
+"""Python SDK для decision-cascade API: типизированный клиент с валидацией."""
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal, Self
+
+import httpx
+from pydantic import BaseModel, Field
+
+from src.schemas import SCHEMA_VERSION
+from src.versioning import is_compatible
+
+QuestionPayload = dict[str, Any]
+
+
+class _NoulOut(BaseModel):
+    type: Literal["noul"] = "noul"
+    noul: float = Field(..., ge=0.0, le=1.0)
+    confidence: float = Field(..., ge=0.0, le=1.0)
+
+
+class _ChoiceOut(BaseModel):
+    type: Literal["choice"] = "choice"
+    choice: str
+    probabilities: dict[str, float]
+    confidence: float = Field(..., ge=0.0, le=1.0)
+
+
+class _ScoreOut(BaseModel):
+    type: Literal["score"] = "score"
+    score: float
+    probabilities: dict[str, float]
+    confidence: float = Field(..., ge=0.0, le=1.0)
+    legend: list[str]
+
+
+_Out = Annotated[
+    _NoulOut | _ChoiceOut | _ScoreOut, Field(discriminator="type")
+]
+
+
+class _Response(BaseModel):
+    schema_version: str
+    decisions: dict[str, _Out]
+
+
+class _FeedbackQuestion(BaseModel):
+    question: str
+    accepted: int = Field(..., ge=0)
+    examples: int = Field(..., ge=0)
+    reference: int = Field(..., ge=0)
+    retrained: bool
+
+
+class _FeedbackResponse(BaseModel):
+    accepted: int = Field(..., ge=0)
+    questions: list[_FeedbackQuestion]
+
+
+def validate_response(payload: dict[str, Any]) -> list[str] | None:
+    """Проверяет ответ API на соответствие типизированному контракту.
+
+    Версия схемы должна быть совместима по major (аддитивные minor-изменения не
+    ломают клиент), см. ``src/versioning.py``.
+    """
+    schema_version = payload.get("schema_version")
+    if not isinstance(schema_version, str) or not is_compatible(
+        SCHEMA_VERSION, schema_version
+    ):
+        raise ValueError(
+            f"schema_version mismatch: expected major of {SCHEMA_VERSION}, "
+            f"got {schema_version!r}"
+        )
+    _Response.model_validate(payload)
+    for name, res in payload["decisions"].items():
+        probs = res.get("probabilities")
+        if probs is not None:
+            if abs(sum(probs.values()) - 1.0) > 1e-6:
+                raise ValueError(f"decision {name!r}: probabilities must sum to 1.0")
+            if any(p < 0.0 for p in probs.values()):
+                raise ValueError(f"decision {name!r}: probabilities must be non-negative")
+    return None
+
+
+class DecisionClient:
+    def __init__(
+        self,
+        base_url: str = "http://localhost:8000",
+        timeout: float = 60.0,
+        transport: httpx.BaseTransport | None = None,
+    ):
+        self._client = httpx.Client(base_url=base_url, timeout=timeout, transport=transport)
+
+    def decisions(
+        self, state: str, questions: dict[str, QuestionPayload]
+    ) -> dict[str, Any]:
+        payload = {"state": state, "questions": questions}
+        resp = self._client.post("/decisions", json=payload)
+        resp.raise_for_status()
+        body = resp.json()
+        validate_response(body)
+        return body
+
+    def feedback(self, examples: list[dict[str, Any]]) -> dict[str, Any]:
+        """Прислать размеченные примеры решений (few-shot риск-модели).
+
+        ``examples`` — список вида
+        ``{"question": ..., "decision": <решение из decisions()>, "correct": bool}``:
+        повторяется именно решение, которое сервер уже отдавал, состояние кодировать
+        заново не нужно. В ответе — сколько примеров накоплено по вопросу и не
+        достигнут ли порог `DECISION_RISK_FEW_SHOT_N` (тогда риск-модель вопроса
+        переобучена). Если бэкенд обратную связь не принимает, сервер отвечает
+        ``409 FEEDBACK_UNSUPPORTED`` — это ``httpx.HTTPStatusError``.
+        """
+        resp = self._client.post("/v1/feedback", json={"examples": examples})
+        resp.raise_for_status()
+        body = resp.json()
+        _FeedbackResponse.model_validate(body)
+        return body
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

api/server/deprecation.py

@@ -0,0 +1,114 @@
+"""Политика депрекации: реестр устаревших поверхностей и заголовки ответа.
+
+Правило (``docs/stability.md`` §5): поверхность объявляется устаревшей минимум
+за две минорные версии до удаления. Всё это время она работает, отдаёт
+заголовки ``Deprecation``/``Sunset``/``Link`` и один раз пишет предупреждение в
+лог. Удаление — только в major-релизе.
+
+Реестр намеренно пуст: пока в проекте нет устаревших поверхностей. Механизм
+здесь, чтобы первая же депрекация была объявлена одинаково и проверялась
+тестом, а не «на словах».
+"""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+logger = logging.getLogger("decision.deprecation")
+
+#: Сколько минорных релизов поверхность обязана прожить после объявления.
+MIN_MINOR_RELEASES = 2
+
+
+def parse_minor(version: str) -> tuple[int, int]:
+    """Разбирает ``X.Y[.Z]`` в ``(major, minor)``; иначе ``ValueError``."""
+    parts = version.strip().split(".")
+    if len(parts) < 2:
+        raise ValueError(f"expected MAJOR.MINOR[.PATCH], got {version!r}")
+    try:
+        return int(parts[0]), int(parts[1])
+    except ValueError as exc:
+        raise ValueError(f"expected numeric MAJOR.MINOR, got {version!r}") from exc
+
+
+def minor_distance(since: str, remove_in: str) -> int:
+    """Сколько минорных версий между объявлением и удалением."""
+    since_major, since_minor = parse_minor(since)
+    remove_major, remove_minor = parse_minor(remove_in)
+    return (remove_major - since_major) * 1000 + (remove_minor - since_minor)
+
+
+@dataclass(frozen=True)
+class Deprecation:
+    """Одна устаревшая поверхность: путь, поле ответа или переменная окружения."""
+
+    #: что именно устарело — путь (``/decisions``) или имя (``DECISION_FOO``)
+    item: str
+    #: версия, в которой объявлена депрекация
+    since: str
+    #: версия, в которой поверхность исчезнет (не раньше since + 2 минорные)
+    remove_in: str
+    #: чем заменить; попадает в ``Link`` и в предупреждение
+    alternative: str | None = None
+    #: дата отключения в формате RFC 8594 (``Sunset``), необязательна
+    sunset: str | None = None
+
+    def headers(self) -> dict[str, str]:
+        """Заголовки ответа по RFC 8594 и RFC 9745."""
+        headers = {"Deprecation": "true"}
+        if self.sunset:
+            headers["Sunset"] = self.sunset
+        if self.alternative:
+            headers["Link"] = f'<{self.alternative}>; rel="deprecation"'
+        return headers
+
+    def __post_init__(self) -> None:
+        distance = minor_distance(self.since, self.remove_in)
+        if distance < MIN_MINOR_RELEASES:
+            raise ValueError(
+                f"deprecation {self.item!r}: remove_in={self.remove_in} is only "
+                f"{distance} minor release(s) after since={self.since}; "
+                f"minimum is {MIN_MINOR_RELEASES}"
+            )
+
+
+#: Реестр устаревших поверхностей: ключ — ``Deprecation.item``.
+DEPRECATIONS: dict[str, Deprecation] = {}
+
+#: Уже предупреждённые элементы: в лог пишем один раз за жизнь процесса.
+_warned: set[str] = set()
+
+
+def deprecation_for(item: str) -> Deprecation | None:
+    """Возвращает депрекацию для поверхности или ``None``."""
+    return DEPRECATIONS.get(item)
+
+
+def warn_once(item: str) -> Deprecation | None:
+    """Пишет предупреждение о депрекации один раз и возвращает её запись."""
+    deprecation = DEPRECATIONS.get(item)
+    if deprecation is None or item in _warned:
+        return deprecation
+    _warned.add(item)
+    logger.warning(
+        "deprecated %s since %s, removal in %s: %s",
+        deprecation.item,
+        deprecation.since,
+        deprecation.remove_in,
+        deprecation.alternative or "no replacement announced",
+    )
+    return deprecation
+
+
+def reset_warnings() -> None:
+    """Сбрасывает память предупреждений (для тестов и перезапуска)."""
+    _warned.clear()
+
+
+def validate_registry() -> None:
+    """Проверяет, что реестр не нарушает правило двух минорных версий."""
+    for item, deprecation in DEPRECATIONS.items():
+        if item != deprecation.item:
+            raise ValueError(
+                f"registry key {item!r} does not match item {deprecation.item!r}"
+            )