How maintainer64/skills-search-tram works
Project Type and Purpose
• This is a voice‐assistant skill (“Навык для умных устройств”) built on Python 3.12, deployed as a Yandex Serverless function.
• Its purpose is to accept user requests via Yandex Dialogs, determine the nearest public‐transport schedule using DoubleGIS APIs, and respond through the voice interface.
High‐Level Architecture
• The system lives entirely inside a single Serverless Function, logically divided into layers:
a. EntryPoint (yandex_serverless.handler)
b. Dependency Injection Container
c. Handlers (intent dispatch, state management)
d. Services (business logic)
e. Clients (external DoubleGIS API calls)
f. External Service (DoubleGIS)
Main Components & Their Relationships
• Yandex Dialogs Platform
• Receives user voice input → transcribes to intent JSON → invokes your function over HTTP.
• Serverless Function (application/yandex_serverless.py)
• handler(event, context) is the entrypoint.
• Loads configuration (application/config.py + env vars).
• Instantiates the DI container (application/container/container.py).
• Routes the incoming intent to the correct Handler.
• Handlers Layer (application/handlers)
• intents.py defines intent IDs (CONFIRM, REJECT, etc.).
• states.py defines conversational states.
• handlers.py maps intents & states to business‐logic calls.
• Services Layer (application/services)
• address_to_geo_service_double_gis.py implements geocoding via DoubleGIS.
• search_schedule_service_double_gis.py implements schedule lookup.
• language.py handles localization or text formatting.
• Abstract interfaces (e.g., address_to_geo_service_abs.py) ensure easy swapping.
• Clients Layer (application/clients/doublegis)
• base/client.py: shared HTTP client config.
• routings, suggests, webapi submodules define REST endpoints + data models.
• utils.py contains common helpers (e.g., parameter building, error handling).
• External DoubleGIS API
• Receives HTTP requests from Clients → returns JSON responses.
Data Flow
1. User speaks → Yandex Dialogs → HTTP JSON request.
2. Serverless handler parses the event → calls DI container to get Handler instance.
3. Handler consults Services, passing user slots & session state.
4. Service calls appropriate Client module → issues HTTP to DoubleGIS.
5. DoubleGIS responds → Client parses into Python models.
6. Service transforms models into user‐friendly text.
7. Handler packs the response into Yandex Dialogs JSON format.
8. Function returns JSON → Yandex speaks the reply.
Architectural Patterns & Principles
• Layered/Clean Architecture: Handlers → Services → Clients → External API
• Dependency Injection for easy testing and swapping of service implementations.
• Separation of concerns:
• Clients do only external communication & model mapping.
• Services encapsulate business rules.
• Handlers orchestrate conversation flow.
What to Label and Emphasize
• Each layer’s name and primary modules/files.
• Entrypoint signature handler(event, context) and env var loading.
• DI container supplies concrete implementations for abstract services.
• That scheduling logic lives in search_schedule_service_double_gis.py, and geocoding in address_to_geo_service_double_gis.py.