Marusia API

Неофициальное SDK навыков для голосового ассистента Маруси.

Документация: https://pkg.go.dev/github.com/neonxp/marusia

Использование

Импорт библиотеки:

import "github.com/neonxp/marusia"

Создание функции обработчика (имплементирующий интерфейс marusia.MessageHandler ):

func messageHandler(ctx context.Context, req *marusia.Request) (*marusia.Response, error) {
    ...
}

Создание экземпляра API и http сервера, обрабатывающего колбеки:

m := marusia.New(messageHandler)
server := http.Server{
    Addr:    ":8080",
    Handler: m.Handler(),
}
if err := server.ListenAndServe(); err != http.ErrServerClosed {
    log.Fatal(err)
}

Суть работы с API заключается в том, что при получении колбека с запросом типа *marusia.Request в течении максимум 10 секунд следует ответить вернув сформированный объект типа *marusia.Response.

Содержимое запроса

type Request struct {
    Command           string 
    OriginalUtterance string 
    Type              string 
    Payload           Payload
    Nlu               struct {
        Tokens   []string    
        Entities []interface{}
    }
}

Command — служебное поле: запрос пользователя, преобразованный для внутренней обработки Марусей. В ходе преобразования текст, в частности, очищается от знаков препинания, а числительные преобразуются в числа. При завершении скилла по команде "стоп", "выход" и т.д. в скилл будет передано "on_interrupt", чтобы у скилла была возможность попрощаться с пользователем.
OriginalUtterance — полный текст пользовательского запроса, максимум 1024 символа.
Type — тип ввода, обязательное свойство. Возможные значения: "SimpleUtterance" — голосовой ввод, "ButtonPressed" — нажатие кнопки.
Payload — JSON, полученный с нажатой кнопкой от обработчика скилла (в ответе на предыдущий запрос), максимум 4096 байт.
Nlu.Tokens — слова и именованные сущности, которые Маруся извлекла из запроса пользователя.
Nlu.Entities — здесь пока будет пустой массив или какие-то экспериментальные вещи, на которые не стоит смотреть.

Содержимое ответа

type Response struct {
    Text       string    
    TTS        string    
    Buttons    []*button 
    EndSession bool      
}

Методы:

NewResponse(text string) *Response - конструктор объекта, где text - текст ответа пользователю
Response.SetText(text string) *Response - задание текста ответа
Response.SetTTS(tts string) *Response - текст с раставленными ударениями (знак "+")
Response.SetEndSession(endSession bool) *Response - задает признак конца диалога
Response.AddButton(title string, payload Payload, URL string) *Response - добавляет кнопку в диалог