Yandex Alice Skills

https://github.com/yandex/alice-skills
Admin
Provides examples for creating skills for Yandex's Alice voice assistant using Yandex.Dialogs.
Tokens:3,846
Snippets:15
Trust Score:9.5
License:MIT
Update:9 months ago
Show doc for...
Tokens:
Raw
### Build Alice Skills with Alisa Framework (Python)

Source: https://context7.com/yandex/alice-skills/llms.txt

This code demonstrates a high-level framework for building Alice skills using Python. It defines a base `Dialog` class and an `Alisa` helper class to manage requests, responses, intents, and buttons. The `ShowDialog` class provides an example of handling different dialog states and user requests.

```python
from alisa import Alisa, Dialog

class ShowDialog(Dialog):
    def handle_dialog(self, alisa):
        if alisa.is_show_request():
            return self.handle_morning_show(alisa)
        return self.greetings(alisa)

    def handle_morning_show(self, alisa):
        alisa.show_episode(text=get_data())

    def greetings(self, alisa):
        alisa.tts_with_text(get_data())
        alisa.end_session()

# Alisa helper class usage
class Alisa:
    def __init__(self, request, response):
        self.event = request
        self.answer = response['response']
        self.response = response
        self.intents = self.event.get('request', {}).get('nlu', {}).get('intents', {})

    def is_new_session(self):
        return self.event['session']['new']

    def has_intent(self, intent):
        return self.intents.get(intent)

    def button(self, title, handler, hide=False, url=None, payload=None):
        if payload is None:
            payload = {}
        self.answer['buttons'] = self.answer.get('buttons', [])
        payload["__transition__"] = {
            'condition': {"name": 'call_handler', "context": {}},
            'handler': handler
        }
        button = {
            "title": title,
            "payload": payload,
            "hide": hide
        }
        if url:
            button["url"] = url
        self.answer['buttons'].append(button)

    def tts_with_text(self, tts):
        self.answer['text'] = self.answer.get('text', '') + tts
        self.answer['tts'] = self.answer.get('tts', '') + tts

    def end_session(self):
        self.answer['end_session'] = True

# Usage example:
def handle_dialog_yacloud(request, context):
    response = {
        "version": request['version'],
        "response": {
            "end_session": True
        }
    }

    alisa = Alisa(request, response)
    dialog = ShowDialog()
    dialog.handle_dialog(alisa)

    return response

# Example: Adding interactive buttons
# alisa.button(title="Следующий", handler="next_episode", hide=True)
# alisa.tts_with_text("Сегодняшний выпуск готов!")

```

--------------------------------

### Image Gallery Response - Python

Source: https://context7.com/yandex/alice-skills/llms.txt

Generates an ImageGallery response for Yandex Alice, suitable for displaying visual content. This Python example includes a helper function to format image gallery items and a Scene class to structure the skill's reply.

```python
def image_gallery(image_ids):
    return {
        'type': 'ImageGallery',
        'items': [
            {'image_id': image_id} for image_id in image_ids
        ]
    }

class Tower(Scene):
    def reply(self, request):
        tts = ('Спасская башня. Спасская башня — проездная башня Новгородского детинца, '
               'строение конца XV века. Башня шестиярусная, в плане представляет собой '
               'вытянутый прямоугольник 15 × 8,3 м.')

        return self.make_response(
            text='',
            tts=tts,
            card=image_gallery(image_ids=[
                '213044/6d63099949494a74d4a0',
                '997614/89f90bf8bca41f92c85c',
            ])
        )
```

--------------------------------

### Intent Recognition and Slot Extraction in Python

Source: https://context7.com/yandex/alice-skills/llms.txt

Demonstrates how to handle structured intents with slot values for natural language understanding. This snippet defines an Enum for places and a function to transition to corresponding scenes based on extracted slot information.

```python
import enum

class Place(enum.Enum):
    UNKNOWN = 1
    TOWER = 2
    CATHEDRAL = 3

    @classmethod
    def from_request(cls, request, intent_name):
        slot = request.intents[intent_name]['slots']['place']['value']
        if slot == 'tower':
            return cls.TOWER
        elif slot == 'cathedral':
            return cls.CATHEDRAL
        else:
            return cls.UNKNOWN

def move_to_place_scene(request, intent_name):
    place = Place.from_request(request, intent_name)
    if place == Place.TOWER:
        return Tower()
    elif place == Place.CATHEDRAL:
        return Cathedral()
    else:
        return UnknownPlace()

class StartTour(Scene):
    def reply(self, request):
        text = 'Вы в Великом Новгороде, на территории старинного кремля. Возле какого места вы находитесь?'
        return self.make_response(text, state={
            'screen': 'start_tour'
        }, buttons=[
            {'title': 'Спасская башня', 'hide': False},
            {'title': 'Софийский собор', 'hide': False},
        ])

    def handle_local_intents(self, request):
        if 'start_tour_with_place_short' in request.intents:
            return move_to_place_scene(request, 'start_tour_with_place_short')

```

--------------------------------

### Serverless Handler and Scene Management in Python

Source: https://context7.com/yandex/alice-skills/llms.txt

Defines the main handler function for serverless deployment, which processes incoming events, manages scene transitions based on user requests, and generates appropriate responses. It also includes the abstract base class 'Scene' and a concrete 'Welcome' scene implementation.

```python
import json
from abc import ABC, abstractmethod

# Assuming Request, SCENES, DEFAULT_SCENE, HandleGeolocation, StartTour, Tower, Cathedral, UnknownPlace are defined elsewhere

class Scene(ABC):
    @classmethod
    def id(cls):
        return cls.__name__

    @abstractmethod
    def reply(self, request):
        raise NotImplementedError()

    def move(self, request):
        next_scene = self.handle_local_intents(request)
        if next_scene is None:
            next_scene = self.handle_global_intents(request)
        return next_scene

    def make_response(self, text, tts=None, card=None, state=None, buttons=None, directives=None):
        response = {
            'text': text,
            'tts': tts if tts is not None else text,
        }
        if card is not None:
            response['card'] = card
        if buttons is not None:
            response['buttons'] = buttons
        if directives is not None:
            response['directives'] = directives

        webhook_response = {
            'response': response,
            'version': '1.0',
            'session_state': {
                'scene': self.id(),
            },
        }
        if state is not None:
            webhook_response['session_state'].update(state)
        return webhook_response

class Welcome(Scene):
    def reply(self, request):
        text = ('Добро пожаловать на экскурсию по кремлю Великого Новгорода. '
            'Тут я расскажу вам исторю башен кремя и собора. Но прежде дайте дайте доступ к геолокации, '
            'чтобы я понимала, где вы находитесь.')
        directives = {'request_geolocation': {}}
        return self.make_response(text, buttons=[
            {'title': 'Расскажи экскурсию', 'hide': True},
        ], directives=directives)

    def handle_local_intents(self, request):
        if request.type in ('geolocation_allowed', 'geolocation_rejected'):
            return HandleGeolocation()

    def handle_global_intents(self, request):
        if 'start_tour' in request.intents:
            return StartTour()

def handler(event, context):
    print('Incoming request: ' + json.dumps(event))
    request = Request(event)
    current_scene_id = event.get('state', {}).get('scene')

    if current_scene_id is None:
        return DEFAULT_SCENE().reply(request)

    current_scene = SCENES.get(current_scene_id, DEFAULT_SCENE)()
    next_scene = current_scene.move(request)

    if next_scene is not None:
        print(f'Moving from scene {current_scene.id()} to {next_scene.id()}')
        return next_scene.reply(request)
    else:
        print(f'Failed to parse user request at scene {current_scene.id()}')
        return current_scene.fallback(request)
```

--------------------------------

### Async Serverless Webhook Handler - Node.js

Source: https://context7.com/yandex/alice-skills/llms.txt

A minimal asynchronous webhook handler using the micro framework for serverless deployments. It parses JSON requests and constructs a response adhering to the Yandex Dialogs protocol. Suitable for platforms like Vercel/Now.

```javascript
const { json } = require('micro');

module.exports = async (req, res) => {
    const { request, session, version } = await json(req);

    res.end(JSON.stringify({
        version,
        session,
        response: {
            text: request.original_utterance || 'Hello!',
            end_session: false,
        },
    }));
};
```

--------------------------------

### Session State Management - Python Alice Skill

Source: https://context7.com/yandex/alice-skills/llms.txt

A Flask-based skill that manages conversation state across multiple turns. It uses a dictionary for session storage to track user interactions and dynamically provides button suggestions based on the conversation flow.

```python
from flask import Flask, request
import json

app = Flask(__name__)
sessionStorage = {}

@app.route("/", methods=['POST'])
def main():
    response = {
        "version": request.json['version'],
        "session": request.json['session'],
        "response": {
            "end_session": False
        }
    }

    handle_dialog(request.json, response)

    return json.dumps(response, ensure_ascii=False, indent=2)

def handle_dialog(req, res):
    user_id = req['session']['user_id']

    if req['session']['new']:
        # Initialize new session
        sessionStorage[user_id] = {
            'suggests': [
                "Не хочу.",
                "Не буду.",
                "Отстань!",
            ]
        }

        res['response']['text'] = 'Привет! Купи слона!'
        res['response']['buttons'] = get_suggests(user_id)
        return

    # Process user response
    if req['request']['original_utterance'].lower() in ['ладно', 'куплю', 'покупаю', 'хорошо']:
        res['response']['text'] = 'Слона можно найти на Яндекс.Маркете!'
        return

    # Continue convincing
    res['response']['text'] = 'Все говорят "%s", а ты купи слона!' % (
        req['request']['original_utterance']
    )
    res['response']['buttons'] = get_suggests(user_id)

def get_suggests(user_id):
    session = sessionStorage[user_id]

    suggests = [
        {'title': suggest, 'hide': True}
        for suggest in session['suggests'][:2]
    ]

    session['suggests'] = session['suggests'][1:]
    sessionStorage[user_id] = session

    if len(suggests) < 2:
        suggests.append({
            "title": "Ладно",
            "url": "https://market.yandex.ru/search?text=слон",
            "hide": True
        })

    return suggests
```

--------------------------------

### Basic Webhook Handler - Node.js Alice Skill

Source: https://context7.com/yandex/alice-skills/llms.txt

A simple Express.js webhook endpoint that echoes user input back to them. It demonstrates the fundamental request/response structure required for Yandex Alice skills, handling incoming JSON requests and sending back a JSON response.

```javascript
const express = require('express');

const port = process.env.PORT || 3000;
const app = express();

app.use(express.json());

app.post('/', function (req, res) {
  // Basic echo response
  res.json({
    version: req.body.version,
    session: req.body.session,
    response: {
      text: req.body.request.command || 'Hello!',
      end_session: false,
    },
  });
});

app.listen(port);
```

--------------------------------

### Translate Text Using Yandex Translate API (Python)

Source: https://context7.com/yandex/alice-skills/llms.txt

This snippet shows how to integrate with the Yandex Translate API to detect the language of a given text and translate it to a specified target language. It uses the `requests` library for HTTP calls and handles API key management and error responses. The `handler` function processes incoming events to perform translations.

```python
import requests
import json
import re

API_KEY = 'your_yandex_translate_api_key'

def detect_lang(text, hint='ru', key=API_KEY):
    pattern = 'https://translate.yandex.net/api/v1.5/tr.json/detect?key={}&text={}&hint={}'
    req = pattern.format(key, text, hint)
    resp = requests.get(req)
    if resp.status_code != 200:
        return None
    j = json.loads(resp.text)
    return j['lang']

def translate(text, lang_to='ru', lang_from=None, key=API_KEY):
    pattern = 'https://translate.yandex.net/api/v1.5/tr.json/translate?key={}&text={}&lang={}'
    if lang_from is None:
        lang_from = detect_lang(key=key, text=text)
        if lang_from is None:
            return 'Не поняла, на каком языке это.', ''

    direction = lang_from + '-' + lang_to
    req = pattern.format(key, text, direction)
    resp = requests.get(req)

    if resp.status_code != 200:
        return 'Не достучалась до переводчика. ' + req, ''

    j = json.loads(resp.text)
    return None, j['text'][0]

def handler(event, context):
    translate_state = event.get('state', {}).get('session', {}).get('translate', {})
    intents = event.get('request', {}).get('nlu', {}).get('intents', {})

    text = 'Привет! Скажите, какое слово вы хотите перевести.'

    translate_main = intents.get('translate_main')
    if translate_main:
        api_req = {
            'text': translate_main['slots'].get('phrase', {}).get('value'),
            'lang_from': translate_main['slots'].get('from', {}).get('value'),
            'lang_to': translate_main['slots'].get('to', {}).get('value'),
        }
        translate_state.update({k: v for k, v in api_req.items() if v})

        if 'text' in translate_state:
            tran_error, tran_result = translate(**translate_state)
            text = tran_error or tran_result

    return {
        'version': event['version'],
        'session': event['session'],
        'response': {
            'text': text,
            'end_session': False
        },
        'session_state': {'translate': translate_state, 'last_phrase': text}
    }

# Example usage:
# User: "Переведи hello на русский"
# Slots extracted: phrase="hello", lang_to="русский"
# API call: translate(text="hello", lang_to="ru")
# Response: "Привет"

```
Tokens:
Raw