There are a few different CLI utilities used for interacting with Neon AI in different scenarios. This guide provides a summary of these different programs, their advantages and disadvantages, and examples of where they may be used.
Definitions:
- AI Core: neon-core, ovos-core, mycroft-core, or another compatible system
- Remote Core: An AI Core running on a different computer, in containers, or in a VM
- Messagebus: A websocket-based communication standard used by compatible AI Cores
- Message: A Message object as defined by mycroft-messagebus-client
The Neon CLI is a modified version of the Mycroft CLI. The CLI works with an AI Core running on the same computer (or VM) as the client, providing log output, text input/output, and local mic level monitoring. Logs and mic level are accessed via the local file system and text input/output use the messagebus.
pip install neon-cli-client
neon-cli
| Feature | Supported |
|---|---|
| Log Monitoring | Yes |
| Messagebus activity monitoring | No |
| Remote (or containerized) core interaction | No* |
| Text Inputs | Yes |
| Audio File Inputs | No |
| Arbitrary Message Injection | No |
* Containers that bind the messagebus to the local host will be able to handle text input and output, but logs and mic level will not be reported.
The CLI client is best used for debugging locally running AI Cores.
Neon Mana (Message Application for Neon AI) is a CLI that was created to address limitations of the Neon CLI Client. Mana provides utilities for monitoring messagebus activity and for sending messages into the messagebus. Mana also provides simple bus configuration to connect to different messagebus instances for monitoring and message-based interactions.
pip install neon-mana-utils
mana
| Feature | Supported |
|---|---|
| Log Monitoring | No |
| Messagebus activity monitoring | Yes |
| Remote (or containerized) core interaction | Yes* |
| Text Inputs | Yes |
| Audio File Inputs | Yes |
| Arbitrary Message Injection | Yes |
* The messagebus port must be accessible by mana for interacting with remote systems
Mana is best used if you are trying to detect or send a specific Message object.
It is also particularly useful for sending a recorded utterance as if it was
spoken, for testing STT in a language you don't speak.
Neon Iris (Interactive Relay for Intelligence Systems) is a CLI client and extensible Python client for interacting with Neon Core via an MQ Connector Module. Iris was created to interact with remote Neon Cores without exposing the messagebus directly.
pip install neon-iris
iris
| Feature | Supported |
|---|---|
| Log Monitoring | No |
| Messagebus activity monitoring | No |
| Remote (or containerized) core interaction | Yes* |
| Text Inputs | Yes |
| Audio File Inputs | Yes |
| Arbitrary Message Injection | Yes** |
* The remote core must be connected to the same MQ server as iris
** Not all messages generate responses that will route back through the Messagebus-MQ Connector
Iris is best used to connect to Neon Core "server" instances, but the module could be used to connect to a different core that implements the MQ Connector Module.
| Use Case | Recommended Package | Explanation |
|---|---|---|
| Debugging a local core | neon-cli, mana | neon-cli provides the simplest UI for monitoring overall core activity. If a particular message is expected, mana provides a better option for inspecting or injecting a Message |
| Developing a skill using a local core | neon-cli | neon-cli provides log monitoring as well as text input/output in one place |
| Developing a skill using a Docker core | mana | mana provides utilities for sending text inputs to a core running in Docker containers and for monitoring messagebus activity. For logs, docker logs can be used to inspect the skills container |
| Integration testing an STT Plugin | mana | mana provides utilities for starting listening (isolate STT from WW testing) and for sending an audio file for STT and skill intent processing |
| Integration testing a TTS Plugin | mana | mana provides a utility for passing text to the audio module for TTS directly |
| Testing in a foreign language | mana, iris | mana provides a utility for sending an audio file for STT and skills processing; translated audio can be pre-generated and then sent via the messagebus (or via MQ with iris) |
| Interacting with a remote core | iris | iris securely connects to a remote core via MQ; it is recommended to not expose the messagebus outside of the host device (and especially not outside of the local network). MQ handles authentication and encryption for sessions connected over the internet. |
| Implementing a client application | iris | iris provides a base class that can be extended for alternate MQ clients |