{"id":17680720,"url":"https://github.com/elbywan/hermes-reason","last_synced_at":"2025-03-30T19:12:51.379Z","repository":{"id":152587969,"uuid":"221456288","full_name":"elbywan/hermes-reason","owner":"elbywan","description":"ReasonML / Ocaml bindings to the Hermes protocol used by the Snips platform. 🐪","archived":false,"fork":false,"pushed_at":"2019-11-14T11:40:16.000Z","size":133,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-05T21:36:04.163Z","etag":null,"topics":["hermes-protocol","reasonml","snips"],"latest_commit_sha":null,"homepage":null,"language":"OCaml","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elbywan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-13T12:39:03.000Z","updated_at":"2020-07-05T00:57:13.000Z","dependencies_parsed_at":null,"dependency_job_id":"6ceaf8de-3573-4af9-87da-b64ff0611ff0","html_url":"https://github.com/elbywan/hermes-reason","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elbywan%2Fhermes-reason","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elbywan%2Fhermes-reason/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elbywan%2Fhermes-reason/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elbywan%2Fhermes-reason/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elbywan","download_url":"https://codeload.github.com/elbywan/hermes-reason/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246365645,"owners_count":20765546,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hermes-protocol","reasonml","snips"],"created_at":"2024-10-24T09:08:41.947Z","updated_at":"2025-03-30T19:12:51.360Z","avatar_url":"https://github.com/elbywan.png","language":"OCaml","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hermes-reason\n\n#### A ReasonML wrapper around the hermes protocol\n\n[![Docs](https://img.shields.io/badge/docs-available-brightgreen.svg)](https://elbywan.github.io/hermes-reason/)\n[![GitHub release](https://img.shields.io/github/release/elbywan/hermes-reason.svg)](https://github.com/elbywan/hermes-reason/releases)\n[![Build Status](https://travis-ci.org/elbywan/hermes-reason.svg?branch=master)](https://travis-ci.org/elbywan/hermes-reason)\n\n## Context\n\nThe `hermes-reason` library provides bindings for the [Hermes protocol](https://docs.snips.ai/reference/hermes) that [Snips](https://snips.ai/) components use to communicate together. `hermes-reason` allows you to interface seamlessly with the Snips platform and create Voice applications with ease!\n\n`hermes-reason` abstracts away the connection to the MQTT bus and the parsing of incoming and outcoming messages from and to the components of the platform and provides a high-level API as well.\n\n## Installation\n\n`esy add hermes-reason`\n\n## Usage\n\n```reason\nopen HermesReason;\n```\n\n### Minimal use case\n\n```reason\nopen HermesReason;\n\n// Instantiate a Hermes object connecting to the default MQTT address (localhost:1883).\nlet hermes = Hermes.make();\n\n// Declare a callback function\nlet callback = (msg: Structs.CIntentMessage.t_view, flow) =\u003e {\n  open Flow;\n\n  // End the session and speak.\n  flow |\u003e speak(\n    \"Received message for intent \" ++ msg.intent.intent_name\n  );\n};\n\n// Register the callback to trigger when intent 'myIntent' is detected.\nhermes |\u003e Flow.entry(\n  ~intent=\"myIntent\",\n  ~callback\n);\n\n// To prevent the process from exiting, you can use sleep.\nwhile (true) {\n  Unix.sleep(60);\n};\n```\n\n### Expanded use case\n\n#### High-level `Flow` api.\n\n```reason\nopen HermesReason;\n\nlet hermes = Hermes.make();\n\n/*\n  Using the high level API is strongly recommended for building complex dialog flows.\n\n  The goal is to register the following dialog paths:\n\n  A\n  ├── B\n  │   └─ D\n  └── C\n\n  In plain words, intent 'A' starts the flow, then restrain the next intents to 'B' or 'C'.\n  If 'B' is the next intent detected, then next intent must be 'D' (and end the flow after 'D').\n  If it was 'C', end the flow.\n*/\n\nhermes |\u003e Flow.entry(~intent=\"A\", ~callback=(msg, flow) =\u003e {\n  open Flow;\n\n  print_string(\"Intent A received. Session started.\");\n\n  /*\n  At each step of the dialog flow, you have the choice of\n  registering the next intents, or end the flow by not\n  registering any continuations.\n\n  We then subscribe to both intent B or C so that the dialog\n  flow will continue with either one or the other next.\n  */\n\n  flow\n  // Mark intent 'B' as one of the next dialog intents. (A -\u003e B)\n  |\u003e continue(~intent=\"B\", ~callback=(msg, flow) =\u003e {\n    print_string(\"Intent B received. Session continued.\");\n\n    // Mark intent 'D'. (A -\u003e B -\u003e D)\n    flow |\u003e continue(~intent=\"D\", ~callback=(_, flow) =\u003e {\n        print_string(\"Intent D received. Session is ended.\");\n        flow |\u003e speak(\"Finished the session with intent D.\");\n    });\n  })\n  // Mark intent 'C' as one of the next dialog intents. (A -\u003e C)\n  |\u003e continue(~intent=\"C\", ~callback=(msg, flow) =\u003e {\n      open Structs;\n\n      // Retrieve the first slot value, assuming it is a slot of type String.\n      let Some(SlotValue.String(slotValue)) = msg.slots |\u003e Option.map(slots =\u003e CSlot.((slots |\u003e List.hd).value.value))\n      print_string(\"Intent C received. Session is ended.\");\n      flow |\u003e speak(\"Finished the session with intent C having value \" ++ slotValue ++\" .\");\n  })\n  // Speak.\n  |\u003e speak(\"Continue with B or C.\");\n});\n```\n\n#### Low-level subscriber \u0026 publisher api.\n\n```reason\nopen HermesReason;\nopen Structs;\n\nlet hermes = Hermes.make();\n\n/*\n  Every API facade can publish and receive data based on a list of events.\n\n  For the purpose of this example, we will only use the Dialog facade, and the\n  events related to a dialog session.\n\n  Note that more events are available for each facade.\n*/\n\n// You can subscribe to an event triggered when the intent 'some_intent' is detected like this:\nhermes\n|\u003e Dialog.Subscribe.intent(~intent=\"some_intent\", ~callback=message =\u003e {\n\n  // The 'message' argument contain all the data you need to perform an action based on what the user said.\n\n  // For instance, you can grab a slot and its value like this.\n  [@warning \"-8\"] // For the sake of brevity, we ignore the exhaustive pattern matching warning.\n  let Some(someSlot) = message.slots |\u003e Option.map(List.find(slot =\u003e CSlot.(slot.slot_name) === \"some_slot\"));\n  [@warning \"-8\"]\n  let SlotValue.String(slotValue) = someSlot.value.value;\n  print_string(\"Slot value: \" ++ slotValue);\n\n  // And here is how to grab the intent name.\n  let intentName = message.intent.intent_name;\n  print_string(\"Received intent: \" ++ intentName);\n\n  let sessionShouldGoOn = true\n  // Then, you can either (but not both):\n  if (sessionShouldGoOn) {\n    // Continue the current dialogue session.\n    hermes |\u003e Dialog.Publish.continueSession(CContinueSessionMessage.{\n      // Session id is the same as the current session.\n      session_id: message.session_id,\n      // This is what is going to be spoken between this and the next session round.\n      text: Some(\"The session lives on…\"),\n      // A list of possible intent continuations for the next round.\n      intent_filter: Some([\"next_intent\"]),\n      // Unused by the reasonml wrapper.\n      custom_data: None,\n      // An optional slot filler argument. Not needed for this example.\n      slot: None,\n      // If true, then a custom behaviour can be determined if no intents are recognized for the next round of dialogue.\n      send_intent_not_recognized: false,\n    });\n  } else {\n    // End the dialogue session.\n    hermes |\u003e Dialog.Publish.endSession(CEndSessionMessage.{\n      session_id: message.session_id,\n      text: Some(\"The session has ended.\")\n    });\n  }\n});\n\n// You can also unsubscribe to a registered event.\nlet rec callback = msg =\u003e {\n  hermes |\u003e Dialog.Unsubscribe.intents(~callback,);\n};\nhermes |\u003e Dialog.Subscribe.intents(~callback);\n\n// Or process a subscription only once:\nhermes |\u003e Dialog.Subscribe.intents(~callback, ~once=true);\n```\n\n## Documentation\n\n*(Badly) autogenerated. Incomplete.*\n\nHosted [here](https://elbywan.github.io/hermes-reason).\n\n## Developing:\n\n```\nnpm install -g esy\ngit clone \u003cthis-repo\u003e\nesy install\nesy build\n```\n\n## Running Tests:\n\n```\n# Runs the \"test\" command in `package.json`.\nesy test\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felbywan%2Fhermes-reason","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felbywan%2Fhermes-reason","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felbywan%2Fhermes-reason/lists"}