salute-api 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
salute_api/__init__.py ADDED
@@ -0,0 +1,88 @@
1
+ """Reusable Salute scenario runtime for Python smartapps."""
2
+
3
+ from salute_api.connector import handle_nlp_request
4
+ from salute_api.helpers import (
5
+ action_id,
6
+ is_screen_on,
7
+ legacy_action,
8
+ one_of,
9
+ suggest_button,
10
+ write_and_pronounce,
11
+ )
12
+ from salute_api.i18n import i18n
13
+ from salute_api.intents import create_intents, load_intents_model, lookup_missing_variables
14
+ from salute_api.logging import configure_logging, get_log_info, logger
15
+ from salute_api.matchers import create_matchers
16
+ from salute_api.metrics import MetricsSender, NoOpMetricsSender, create_metrics_sender
17
+ from salute_api.models import SaluteNlpRequest, SaluteNlpResponse
18
+ from salute_api.process import BoundProcess, ProcessType, bind_process
19
+ from salute_api.recognizer import IntentsRecognizer, Recognizer, SmartAppBrainRecognizer
20
+ from salute_api.request import SaluteRequest, create_salute_request
21
+ from salute_api.response import SaluteResponse, create_salute_response, make_image_card
22
+ from salute_api.scenario import (
23
+ Dispatch,
24
+ Handler,
25
+ ScenarioContext,
26
+ ScenarioState,
27
+ create_scenario_walker,
28
+ create_system_scenario,
29
+ create_user_scenario,
30
+ never,
31
+ )
32
+ from salute_api.server import create_salute_app
33
+ from salute_api.storage import MemoryStorage, RedisStorage, SessionStorage, empty_session
34
+ from salute_api.types import Inference, Intent, SaluteSession, Variant
35
+
36
+ __version__ = "0.1.0"
37
+
38
+ __all__ = [
39
+ "BoundProcess",
40
+ "Dispatch",
41
+ "Handler",
42
+ "Inference",
43
+ "Intent",
44
+ "IntentsRecognizer",
45
+ "MemoryStorage",
46
+ "MetricsSender",
47
+ "NoOpMetricsSender",
48
+ "ProcessType",
49
+ "Recognizer",
50
+ "RedisStorage",
51
+ "SaluteNlpRequest",
52
+ "SaluteNlpResponse",
53
+ "SaluteRequest",
54
+ "SaluteResponse",
55
+ "SaluteSession",
56
+ "ScenarioContext",
57
+ "ScenarioState",
58
+ "SessionStorage",
59
+ "SmartAppBrainRecognizer",
60
+ "Variant",
61
+ "__version__",
62
+ "action_id",
63
+ "bind_process",
64
+ "configure_logging",
65
+ "create_intents",
66
+ "create_matchers",
67
+ "create_metrics_sender",
68
+ "create_salute_app",
69
+ "create_salute_request",
70
+ "create_salute_response",
71
+ "create_scenario_walker",
72
+ "create_system_scenario",
73
+ "create_user_scenario",
74
+ "empty_session",
75
+ "get_log_info",
76
+ "handle_nlp_request",
77
+ "i18n",
78
+ "is_screen_on",
79
+ "legacy_action",
80
+ "load_intents_model",
81
+ "logger",
82
+ "lookup_missing_variables",
83
+ "make_image_card",
84
+ "never",
85
+ "one_of",
86
+ "suggest_button",
87
+ "write_and_pronounce",
88
+ ]
@@ -0,0 +1,64 @@
1
+ """Turn a raw NLP JSON body into a Salute response payload."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import time
6
+ from collections.abc import Awaitable, Callable
7
+ from typing import Any
8
+
9
+ from salute_api.device import device_scope, merge_device
10
+ from salute_api.logging import logger, request_log_fields, response_log_fields
11
+ from salute_api.metrics import MetricsSender, NoOpMetricsSender
12
+ from salute_api.request import create_salute_request
13
+ from salute_api.response import create_salute_response
14
+ from salute_api.storage import SessionStorage
15
+ from salute_api.types import SaluteSession
16
+
17
+ Walker = Callable[..., Awaitable[None]]
18
+ AfterHook = Callable[..., Awaitable[None] | None]
19
+
20
+
21
+ async def handle_nlp_request(
22
+ body: dict[str, Any],
23
+ *,
24
+ walker: Walker,
25
+ storage: SessionStorage,
26
+ after: AfterHook | None = None,
27
+ metrics: MetricsSender | None = None,
28
+ ) -> dict[str, Any]:
29
+ sender = metrics or NoOpMetricsSender()
30
+ started = time.perf_counter()
31
+ payload = body.get("payload") if isinstance(body.get("payload"), dict) else None
32
+ with device_scope(payload):
33
+ req = create_salute_request(body)
34
+ res = create_salute_response(body)
35
+ fields = request_log_fields(req)
36
+ session_id = fields.get("userId") or "anonymous"
37
+ logger.info("nlp request", extra=fields)
38
+ sender.increment("nlp.request")
39
+ try:
40
+ session: SaluteSession = await storage.resolve(session_id)
41
+ await walker(req=req, res=res, session=session)
42
+ response_payload = res.message.get("payload")
43
+ if isinstance(response_payload, dict):
44
+ merge_device(response_payload)
45
+ if after is not None:
46
+ result = after(req, session)
47
+ if result is not None:
48
+ await result
49
+ await storage.save(session_id, session)
50
+ except Exception as exc:
51
+ logger.exception("nlp request failed", extra=fields)
52
+ sender.error("nlp.request", exc)
53
+ raise
54
+ duration_ms = round((time.perf_counter() - started) * 1000, 2)
55
+ sender.timing("nlp.request", duration_ms)
56
+ logger.info(
57
+ "nlp response",
58
+ extra={
59
+ **request_log_fields(req),
60
+ **response_log_fields(res.message),
61
+ "durationMs": duration_ms,
62
+ },
63
+ )
64
+ return res.message
salute_api/device.py ADDED
@@ -0,0 +1,87 @@
1
+ """Request-scoped device identity via contextvars.
2
+
3
+ When a Salute payload includes `device`, every log line for that call gets
4
+ `deviceId` / `surface` / `platform`. Missing device is fine: logs still emit.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from collections.abc import Iterator, Mapping
10
+ from contextlib import contextmanager
11
+ from contextvars import ContextVar, Token
12
+ from typing import Any
13
+
14
+ device_id_var: ContextVar[str | None] = ContextVar("salute_device_id", default=None)
15
+ device_surface_var: ContextVar[str | None] = ContextVar("salute_device_surface", default=None)
16
+ device_platform_var: ContextVar[str | None] = ContextVar("salute_device_platform", default=None)
17
+
18
+
19
+ def device_log_fields() -> dict[str, str]:
20
+ fields: dict[str, str] = {}
21
+ device_id = device_id_var.get()
22
+ surface = device_surface_var.get()
23
+ platform = device_platform_var.get()
24
+ if device_id:
25
+ fields["deviceId"] = device_id
26
+ if surface:
27
+ fields["surface"] = surface
28
+ if platform:
29
+ fields["platform"] = platform
30
+ return fields
31
+
32
+
33
+ def extract_device(payload: Mapping[str, Any] | None) -> dict[str, str]:
34
+ if not payload:
35
+ return {}
36
+ device = payload.get("device")
37
+ if not isinstance(device, Mapping) or not device:
38
+ return {}
39
+ fields: dict[str, str] = {}
40
+ device_id = device.get("deviceId") or device.get("device_id")
41
+ surface = device.get("surface")
42
+ platform = device.get("platformType") or device.get("platform")
43
+ if device_id:
44
+ fields["deviceId"] = str(device_id)
45
+ if surface:
46
+ fields["surface"] = str(surface)
47
+ if platform:
48
+ fields["platform"] = str(platform)
49
+ return fields
50
+
51
+
52
+ def bind_device(fields: Mapping[str, str]) -> tuple[Token[str | None], ...]:
53
+ tokens = (
54
+ device_id_var.set(fields.get("deviceId")),
55
+ device_surface_var.set(fields.get("surface")),
56
+ device_platform_var.set(fields.get("platform")),
57
+ )
58
+ return tokens
59
+
60
+
61
+ def reset_device(tokens: tuple[Token[str | None], ...]) -> None:
62
+ device_id_var.reset(tokens[0])
63
+ device_surface_var.reset(tokens[1])
64
+ device_platform_var.reset(tokens[2])
65
+
66
+
67
+ def merge_device(payload: Mapping[str, Any] | None) -> None:
68
+ """Update bound device fields from a later payload (e.g. the response)."""
69
+ fields = extract_device(payload)
70
+ if not fields:
71
+ return
72
+ if "deviceId" in fields:
73
+ device_id_var.set(fields["deviceId"])
74
+ if "surface" in fields:
75
+ device_surface_var.set(fields["surface"])
76
+ if "platform" in fields:
77
+ device_platform_var.set(fields["platform"])
78
+
79
+
80
+ @contextmanager
81
+ def device_scope(payload: Mapping[str, Any] | None) -> Iterator[dict[str, str]]:
82
+ fields = extract_device(payload)
83
+ tokens = bind_device(fields)
84
+ try:
85
+ yield fields
86
+ finally:
87
+ reset_device(tokens)
salute_api/helpers.py ADDED
@@ -0,0 +1,53 @@
1
+ """Small helpers shared by scenario apps."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Callable
6
+ from typing import Any
7
+
8
+ from salute_api.matchers import Matcher
9
+ from salute_api.request import SaluteRequest
10
+ from salute_api.response import SaluteResponse
11
+
12
+
13
+ def one_of(*matchers: Matcher) -> Matcher:
14
+ def match(req: SaluteRequest) -> bool:
15
+ return any(matcher(req) for matcher in matchers)
16
+
17
+ return match
18
+
19
+
20
+ def is_screen_on(req: SaluteRequest) -> bool:
21
+ meta = req.payload.get("meta") or {}
22
+ features = meta.get("features") or {}
23
+ screen = features.get("screen") or {}
24
+ if "enabled" in screen:
25
+ return bool(screen["enabled"])
26
+ return True
27
+
28
+
29
+ def write_and_pronounce(res: SaluteResponse, text: str) -> None:
30
+ res.append_bubble(text)
31
+ res.set_pronounce_text(text)
32
+
33
+
34
+ def action_id(expected: str) -> Callable[[SaluteRequest], bool]:
35
+ def match(req: SaluteRequest) -> bool:
36
+ server_action = req.server_action or {}
37
+ return server_action.get("action_id") == expected
38
+
39
+ return match
40
+
41
+
42
+ legacy_action = action_id
43
+
44
+
45
+ def suggest_button(title: str, action_id_value: str) -> dict[str, Any]:
46
+ return {
47
+ "title": title,
48
+ "message_name": "SERVER_ACTION",
49
+ "action": {
50
+ "type": "server_action",
51
+ "server_action": {"action_id": action_id_value},
52
+ },
53
+ }
salute_api/hooks.py ADDED
@@ -0,0 +1,17 @@
1
+ """Reusable PRE/POST process bindings."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from salute_api.logging import log_info
6
+ from salute_api.process import BoundProcess, ProcessType
7
+ from salute_api.scenario import Dispatch, ScenarioContext
8
+
9
+ pre_log_info = BoundProcess(func=log_info, type=ProcessType.PRE)
10
+
11
+
12
+ def post_auto_listening(ctx: ScenarioContext, _dispatch: Dispatch) -> None:
13
+ if ctx.res.message.get("messageName") == "ANSWER_TO_USER":
14
+ ctx.res.set_auto_listening(True)
15
+
16
+
17
+ post_auto_listening_process = BoundProcess(func=post_auto_listening, type=ProcessType.POST)
salute_api/i18n.py ADDED
@@ -0,0 +1,83 @@
1
+ """Character-aware i18n, including list-valued keys and Russian plural forms."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import random
6
+ from collections.abc import Callable, Mapping
7
+ from typing import Any
8
+
9
+ KeysetKey = str | list[str] | dict[str, str]
10
+ Keyset = Mapping[str, KeysetKey]
11
+ KeysetDictionary = Mapping[str, Keyset]
12
+ I18nFn = Callable[[str, dict[str, Any] | None], str]
13
+
14
+
15
+ def plural_ru(count: int, params: Mapping[str, str]) -> str:
16
+ last_number = count % 10
17
+ last_numbers = count % 100
18
+ if not count:
19
+ return params.get("none") or ""
20
+ if last_number == 1 and last_numbers != 11:
21
+ return params["one"]
22
+ if last_number > 1 and last_number < 5 and (last_numbers < 10 or last_numbers > 20):
23
+ return params["some"]
24
+ return params.get("many") or ""
25
+
26
+
27
+ def generate_text(template: str, options: Mapping[str, Any] | None = None) -> list[Any]:
28
+ options = options or {}
29
+ parts: list[Any] = []
30
+ pos = 0
31
+ length = len(template)
32
+ while pos < length:
33
+ p1 = template.find("{", pos)
34
+ if p1 == -1:
35
+ parts.append(template[pos:])
36
+ return parts
37
+ p2 = template.find("}", p1)
38
+ if p2 == -1:
39
+ parts.append(template[pos:])
40
+ return parts
41
+ parts.append(template[pos:p1])
42
+ value = options.get(template[p1 + 1 : p2])
43
+ if value:
44
+ parts.append(value)
45
+ pos = p2 + 1
46
+ return parts
47
+
48
+
49
+ def _resolve_key(character: str, keyset: KeysetDictionary, key: str) -> KeysetKey | None:
50
+ character_set = keyset.get(character) or {}
51
+ if key in character_set:
52
+ return character_set[key]
53
+ sber = keyset.get("sber") or {}
54
+ return sber.get(key)
55
+
56
+
57
+ def _i18n(
58
+ character: str,
59
+ keyset: KeysetDictionary,
60
+ key: str,
61
+ options: Mapping[str, Any] | None = None,
62
+ ) -> list[Any]:
63
+ options = options or {}
64
+ value = _resolve_key(character, keyset, key)
65
+ if isinstance(value, list):
66
+ template = value[int(random.random() * len(value))]
67
+ return generate_text(template, options)
68
+ if isinstance(value, str):
69
+ return generate_text(value, options)
70
+ if isinstance(value, dict):
71
+ template = plural_ru(int(options.get("count") or 0), value)
72
+ return generate_text(template, options)
73
+ return [key]
74
+
75
+
76
+ def i18n(character: str = "sber") -> Callable[[KeysetDictionary], I18nFn]:
77
+ def for_keyset(keyset: KeysetDictionary) -> I18nFn:
78
+ def translate(key: str, options: dict[str, Any] | None = None) -> str:
79
+ return "".join(str(part) for part in _i18n(character, keyset, key, options))
80
+
81
+ return translate
82
+
83
+ return for_keyset
salute_api/intents.py ADDED
@@ -0,0 +1,34 @@
1
+ """Intent dictionaries and slot-filling helpers."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import random
7
+ from pathlib import Path
8
+ from typing import Any
9
+
10
+ IntentsDict = dict[str, Any]
11
+
12
+
13
+ def create_intents(intents: IntentsDict) -> IntentsDict:
14
+ return intents
15
+
16
+
17
+ def load_intents_model(path: str | Path) -> dict[str, Any]:
18
+ return json.loads(Path(path).read_text(encoding="utf-8"))
19
+
20
+
21
+ def lookup_missing_variables(
22
+ intent: str,
23
+ intents: IntentsDict,
24
+ variables: dict[str, Any],
25
+ ) -> list[dict[str, str]]:
26
+ missing: list[dict[str, str]] = []
27
+ vars_spec = (intents.get(intent) or {}).get("variables") or {}
28
+ for name, spec in vars_spec.items():
29
+ questions = spec.get("questions") or []
30
+ required = spec.get("required")
31
+ if questions and required and name not in variables:
32
+ question_no = int(random.random() * len(questions))
33
+ missing.append({"name": name, "question": questions[question_no]})
34
+ return missing
salute_api/logging.py ADDED
@@ -0,0 +1,196 @@
1
+ """Structured logging for Salute scenario services.
2
+
3
+ JSON output matches the original Winston format so logs can be shipped
4
+ the same way across apps. Extra fields on `logger.info(..., extra=...)`
5
+ are included in the JSON payload.
6
+
7
+ Device id / surface / platform are injected from contextvars when a
8
+ device is bound for the current call.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import json
14
+ import logging
15
+ import sys
16
+ from collections.abc import Sequence
17
+ from datetime import UTC, datetime
18
+ from typing import TYPE_CHECKING, Any
19
+
20
+ from salute_api.device import device_log_fields
21
+ from salute_api.request import SaluteRequest
22
+
23
+ if TYPE_CHECKING:
24
+ from salute_api.scenario import Dispatch, ScenarioContext
25
+
26
+ LOGGER_NAME = "salute_api"
27
+ logger = logging.getLogger(LOGGER_NAME)
28
+ error_logger = logging.getLogger(f"{LOGGER_NAME}.error")
29
+
30
+ _RESERVED_RECORD_KEYS = frozenset(
31
+ {
32
+ "name",
33
+ "msg",
34
+ "args",
35
+ "levelname",
36
+ "levelno",
37
+ "pathname",
38
+ "filename",
39
+ "module",
40
+ "exc_info",
41
+ "exc_text",
42
+ "stack_info",
43
+ "lineno",
44
+ "funcName",
45
+ "created",
46
+ "msecs",
47
+ "relativeCreated",
48
+ "thread",
49
+ "threadName",
50
+ "processName",
51
+ "process",
52
+ "taskName",
53
+ "message",
54
+ "asctime",
55
+ }
56
+ )
57
+
58
+
59
+ class DeviceContextFilter(logging.Filter):
60
+ """Attach bound device fields to every record that does not already set them."""
61
+
62
+ def filter(self, record: logging.LogRecord) -> bool:
63
+ for key, value in device_log_fields().items():
64
+ if not hasattr(record, key):
65
+ setattr(record, key, value)
66
+ return True
67
+
68
+
69
+ class JsonFormatter(logging.Formatter):
70
+ """One JSON object per line, with timestamp and non-reserved extras."""
71
+
72
+ def format(self, record: logging.LogRecord) -> str:
73
+ payload: dict[str, Any] = {
74
+ "timestamp": datetime.fromtimestamp(record.created, tz=UTC).isoformat(),
75
+ "level": record.levelname,
76
+ "logger": record.name,
77
+ "message": record.getMessage(),
78
+ }
79
+ for key, value in record.__dict__.items():
80
+ if key in _RESERVED_RECORD_KEYS or key.startswith("_"):
81
+ continue
82
+ payload[key] = _json_safe(value)
83
+ if record.exc_info:
84
+ payload["exception"] = self.formatException(record.exc_info)
85
+ return json.dumps(payload, ensure_ascii=False, default=str)
86
+
87
+
88
+ class ExtraFormatter(logging.Formatter):
89
+ """Human-readable line with extra fields appended as key=value."""
90
+
91
+ def __init__(self) -> None:
92
+ super().__init__(fmt="%(asctime)s %(levelname)s %(name)s %(message)s")
93
+
94
+ def format(self, record: logging.LogRecord) -> str:
95
+ line = super().format(record)
96
+ extras = []
97
+ for key, value in record.__dict__.items():
98
+ if key in _RESERVED_RECORD_KEYS or key.startswith("_"):
99
+ continue
100
+ extras.append(f"{key}={value}")
101
+ if extras:
102
+ line = f"{line} {' '.join(extras)}"
103
+ return line
104
+
105
+
106
+ def _json_safe(value: Any) -> Any:
107
+ if value is None or isinstance(value, bool | int | float | str):
108
+ return value
109
+ if isinstance(value, dict):
110
+ return {str(key): _json_safe(item) for key, item in value.items()}
111
+ if isinstance(value, list | tuple):
112
+ return [_json_safe(item) for item in value]
113
+ return str(value)
114
+
115
+
116
+ def configure_logging(
117
+ *,
118
+ level: str = "INFO",
119
+ json_logs: bool = True,
120
+ stream: Any | None = None,
121
+ force: bool = False,
122
+ extra_loggers: Sequence[str] = (),
123
+ ) -> None:
124
+ """Attach a stdout handler to the salute_api logger tree.
125
+
126
+ Safe to call more than once. Pass ``force=True`` from a process entrypoint
127
+ to replace handlers after uvicorn has configured logging.
128
+ """
129
+ resolved_level = getattr(logging, level.upper(), logging.INFO)
130
+ formatter: logging.Formatter = JsonFormatter() if json_logs else ExtraFormatter()
131
+ handler = logging.StreamHandler(stream or sys.stdout)
132
+ handler.setFormatter(formatter)
133
+ handler.setLevel(resolved_level)
134
+ handler.addFilter(DeviceContextFilter())
135
+
136
+ for name in (LOGGER_NAME, *extra_loggers):
137
+ target = logging.getLogger(name)
138
+ target.setLevel(resolved_level)
139
+ if force:
140
+ target.handlers.clear()
141
+ target.filters.clear()
142
+ if not target.handlers:
143
+ target.addHandler(handler)
144
+ target.addFilter(DeviceContextFilter())
145
+ target.propagate = False
146
+
147
+
148
+ def request_log_fields(req: SaluteRequest) -> dict[str, Any]:
149
+ device = (req.payload.get("device") or {}) if req.payload else {}
150
+ uuid = req.request.get("uuid") or {}
151
+ path = []
152
+ if req.current_state:
153
+ path = req.current_state.get("path") or []
154
+ original_text = req.message.get("original_text") if req.message else None
155
+ fields = {
156
+ "character": req.character,
157
+ "state": "->".join(path),
158
+ "surface": device.get("surface"),
159
+ "surfaceVersion": device.get("surfaceVersion"),
160
+ "messageId": req.request.get("messageId"),
161
+ "sessionId": req.request.get("sessionId"),
162
+ "userId": uuid.get("userId") if isinstance(uuid, dict) else None,
163
+ "systemIntent": req.system_intent,
164
+ "originalText": original_text,
165
+ }
166
+ fields.update(device_log_fields())
167
+ return fields
168
+
169
+
170
+ def get_log_info(req: SaluteRequest) -> dict[str, Any]:
171
+ """Fields logged on every scenario state, matching the JS helper."""
172
+ fields = request_log_fields(req)
173
+ info = {
174
+ "character": fields["character"],
175
+ "state": fields["state"],
176
+ "surface": fields["surface"],
177
+ "surfaceVersion": fields["surfaceVersion"],
178
+ "messageId": fields["messageId"],
179
+ }
180
+ info.update(device_log_fields())
181
+ return info
182
+
183
+
184
+ def log_info(ctx: ScenarioContext, _dispatch: Dispatch) -> None:
185
+ logger.info("scenario state", extra=get_log_info(ctx.req))
186
+
187
+
188
+ def response_log_fields(message: dict[str, Any]) -> dict[str, Any]:
189
+ payload = message.get("payload") or {}
190
+ items = payload.get("items") or []
191
+ return {
192
+ "messageName": message.get("messageName"),
193
+ "itemCount": len(items),
194
+ "pronounceText": payload.get("pronounceText"),
195
+ "finished": payload.get("finished"),
196
+ }