Hey Athena

Overview

Your personal voice assistant. Written in Python.

"Hey Athena" is a 100% open-source, modular voice assistant framework. We aim to do everything that Siri, Cortana, and Echo can do - and more.

Website: https://heyathena.com

Documentation: https://heyathena.com/docs/

Forum: https://heyathena.com/forum/

GitHub: https://github.com/hey-athena/hey-athena-client

Usage Examples:

Say "Athena" (wait for double beep) then...

• "Play some music"
• "Text [Joe] [Wow, Hey Athena is so cool!]"
• "Tweet [Hello world!]" (IFTTT key required)
• "Define [artificial intelligence]"
• "Show me pictures of [Taj Mahal]"
• "Open facebook.com"

Write a simple "module" to control your house with your voice. See documentation: https://heyathena.com/docs/

Don't like the name "Athena"? Change it to anything you want, like "Joe" or "Swagger Bot".

Module Ideas

• Smart-Home Control
  • Power Outlets (Hook)
  • Thermostat (Nest)
• IFTTT Recipes (use Maker channel to trigger)
• Grades/Homework Assignments (see Canvas)
• Cooking Recipe Assistant (hands-free)
• Facebook, Twitter, GMail
• Timer/Stopwatch
• Calendar
• Games (Zork, etc.)
• Robot Movement

If you create a module, submit a pull request! We'd love to add it to the repository. You can also email it to [email protected]

Roadmap

Hey Athena is just getting started. We plan to build an open-source community built around a quality voice assistance framework. Here are some features you can expect to see in the future:

• Bigger Community: we are working on building a bigger open-source community
• Passive Modules: useful for voice/text notifications (e.g. - "You have an important unread email from Professor Valvano")
• Module Database: developers will be able to easily create and submit modules for other people to use
• Machine Learning: we are looking into libraries like Scikit to help Athena learn how to respond better
• Natural Language Processing (NLP): we are constantly working on improving NLP techniques with services like wit.ai

HTTP RESTful API

We are currently developing a cloud-hosted RESTful API (JSON) service. Users will be able to send HTTP requests and receive a voice/text JSON response.

Current: https://heyathena.com/api?q=test

Future: HTTP GET https://heyathena.com/api/{api_key}/q=list%20bitcoin%20price

Response: {"success": true, "response": "359.7", "intent": "bitcoin"}

How can I make my own Athena?

• Download and install Hey Athena using the directions below
• Write your own modules so Athena can respond to different commands
• Install Hey Athena on a Raspberry Pi to turn your house into a smart-home with voice control

Installation

For installation notes, please use: https://heyathena.com/docs/intro/install.html

How can I help?

• Write modules and contribute them by submitting a pull request to this repository
• Find errors and post issues
• If you modify the framework software, submit a pull request
• Give feedback and help us build a community!

Core Dependencies

• Python 3
• Pocketsphinx (SWIG required in your PATH during installation)
• SpeechRecognition
• Pyglet (AVBin required)
• PyAudio
• gTTS
• PyYAML
• Selenium

Active Modules

An active module is simply a collection of tasks. Tasks look for patterns in user text input (generally through "regular expressions"). If a pattern is matched, the task executes its action. Note: module priority is taken into account first, then task priority.

"""
File Name: hello_world.py
Finds and returns the latest bitcoin price

Usage Examples:
- "What is the price of bitcoin?"
- "How much is a bitcoin worth?"
    """

    from athena.classes.module import Module
    from athena.classes.task import ActiveTask
    from athena.api_library import bitcoin_api

    class GetValueTask(ActiveTask):

            def __init__(self):
                    # Matches any statement with the word "bitcoin"
                    super().__init__(words=['bitcoin'])

            # This default match method can be overridden
            # def match(self, text):
            #    # "text" is the STT translated input string
            #    # Return True if the text matches any word or pattern
            #    return self.match_any(text)

            def action(self, text):
                     # If 'bitcoin' was found in text, speak the bitcoin price
                    bitcoin_price = str(bitcoin_api.get_data('last'))
                    self.speak(bitcoin_price)

    # This is a bare-minimum module
    class Bitcoin(Module):

            def __init__(self):
                    tasks = [GetValueTask()]
                    super().__init__('bitcoin', tasks, priority=2)

Passive Modules

(soon-to-be implemented)

• Passive modules will be collections of scheduled/event-triggered tasks
• Useful for notifications (e.g. - Twitter, Facebook, GMail updates)

Athena APIs

An "Api" object is simply a separate library of functions for "Modules" to use. Athena stores a library of "Api" objects during runtime. Moreover, "Api" objects make it easy to load user configuration data at runtime. This is useful if your modules require username/password authentication (e.g. - logging into Spotify)

Usage example:

from athena.apis import api_lib

api_lib['your_api_handle'].your_awesome_func()

Common Errors

Error: "no module named athena"

Fix: Make sure the athena project directory is in your PYTHONPATH

Error: "AVbin is required to decode compressed media"

Fix: Pyglet needs the avbin.dll file to be installed. On Windows, sometimes the file is wrongfully placed in System32 instead of SysWOW64.

Other errors can be found by searching the issues on our GitHub page.