Building The Ultimate Productivity Tool With Espanso + ChatGPT API

I recently discovered Espanso, a text expander. It saves you an incredible amount of time when typing text on the keyboard. As I explored its possibilities, I immediately thought of integrating it with various APIs, notably OpenAI’s, to make it look like you’re interacting with ChatGPT.

Some use cases are, for example, to translate text, or generate text, based on what’s stored in your clipboard.

For example, to translate text:

Or to generate text:

The possibilities are endless.

What Is Espanso

In case you haven’t heard of it, Espanso is a text expander. It lets you type text faster by replacing what you type with text you’ve configured. For example, when I type “@me”, Espanso replaces it with my e-mail address.

Espanso is very flexible and has many options that you can modify to suit your needs. For example, you can create forms that will open when you type a certain text, and whose values will be inserted at your cursor. You can also trigger scripts whose output will be inserted at your cursor. This is what we’re going to use.

If you don’t have Espanso, you can consult the documentation to find out how to install it. It’s pretty straightforward if you’re on Windows.

Creating The Script

We’re going to use Python to run our scripts, so if you don’t have Python, start by installing it: https://www.python.org/downloads/.

Next, go to your Espanso configuration folder (on Linux, ~/.config for example). If you don’t find this folder, just open a command line and run the following command:

espanso path

In this config folder, Create a “scripts” folder to store files related to scripts.

Create a ask.pyfile in this scriptsfolder, open it with a text editor, and insert the following code:

import yaml
import openai
import argparse

parser = argparse.ArgumentParser()
parser.add_argument("--prompt", type=str)
parser.add_argument("--config", type=str)
args = parser.parse_args()

with open(args.config, "r") as config_file:
 config = yaml.load(config_file, Loader=yaml.FullLoader)

openai_key = config["openai_key"]
openai_model = config["openai_model"]

openai.api_key = openai_key
model = openai_model
prompt = args.prompt
completion = openai.ChatCompletion.create(
 model=model,
 messages=[
 {
 "role": "user",
 "content": prompt
 }
 ]
)
print(completion.choices[0].message.content)

Don’t forget to install the necessary dependencies for this script to work with the following command:

pip install yaml openai

Here’s what this script does:

1. Gets the arguments passed on the command line
2. Reads the configuration file (we’ll create this file next)
3. Set AI parameters.
4. Text generation with Openai API.
5. Display of generated text (this display will be retrieved by Espanso).

Config File

The configuration file is a YAML file containing just two parameters: the template to be used for text generation, and your OpenAI API key. Start by creating a config.yamlfile in the scriptsfolder, and paste the following code into it:

openapi_model: gpt-3.5-turbo
openapi_key: YOUR_KEY

If you wish to use GPT4 instead of GPT3.5, simply set gpt-4 instead of gpt-3.5-turbo .

To retrieve your API key, log on to OpenAI and go to this page: https://platform.openai.com/account/api-keys. Here you can click on “Create new secret key” and then copy your API key. Once you have it, add it to your configuration file.

If you want to try the script, you can run the following command by opening a terminal from the scripts directory:

python ask.py --config ABSOLUTE_PATH_TO_CONFIG --prompt "Hey, how are you?"

Espanso Config

The last thing to do is to add the triggering of this script to Espanso’s config. Go to the Espanso configuration folder, then to the matchfolder, and then you can create a YAML file that you call whatever you like, for example gpt.yml .

Paste the following text into it:

matches:
  - trigger: ':ask'
    replace: '{{output}}'
    label: ChatGPT - Ask
    vars:
      - name: form1
        type: form
        params:
          layout: |
            Prompt: [[prompt]]
          fields:
            prompt:
              multiline: true
      - name: output
        type: shell
        params:
          cmd: 'python $CONFIG/scripts/ask.py --config $CONFIG/scripts/config.yaml
            --prompt "{{form1.prompt}}"'

Of course, you’re free to modify this as you see fit.

Now, if you type anywhere “:ask”, it will open a small window asking you to enter a prompt, and will write the answer to your cursor.

Going Further

Let’s say you want to translate the text stored in your clipboard and insert the translation under your cursor. It’s almost the same as before, but you just need to add an argument for the language if necessary.

Let’s start by creating a new file named translate.pyin our scripts directory. Here is the code of this script:

import yaml
import openai
import argparse


parser = argparse.ArgumentParser()
parser.add_argument("--prompt", type=str)
parser.add_argument("--config", type=str)
parser.add_argument("--to", type=str)

args = parser.parse_args()


with open(args.config, "r") as config_file:
    config = yaml.load(config_file, Loader=yaml.FullLoader)


openai_key = config["openai_key"]
openai_model = config["openai_model"]


openai.api_key = openai_key
model = openai_model
to = args.to
prompt = args.prompt

messages = [
    { 'role': 'system', 'content': f'Act as a translator translating the text you receive to {to}' },
    { 'role': 'user', 'content': prompt }
]

completion = openai.ChatCompletion.create(
    model=model,
    messages=messages
)

print(completion.choices[0].message.content)

As you can see, it’s easy to add a new argument. Our messages are now different, we’ve added a system message. It allows us to tell the LLM how it should behave.

Now, we can add our trigger to our gpt.yml file:

matches:
  - trigger: ':translate'
    replace: '{{output}}'
    label: ChatGPT - Translate
    vars:
      - name: form1
        type: form
        params:
          layout: |
            To: [[to]]
          fields:
            prompt:
              multiline: true
      - name: clipboard
        type: clipboard
      - name: output
        type: shell
        params:
          cmd: 'python $CONFIG/scripts/ask.py --config $CONFIG/scripts/config.yaml
            --prompt "{{clipboard}}" --to "{{form1.to}}"'

And now we can translate any text in any language by just copying it to the clipboard, and then typing “:translate”.

Final Note

I’ve tried to explain the process a little so that even people who don’t know Python can follow this article. However, if you still can’t get the hang of it, leave a comment and I’ll try to help!

Thanks for reading! Here are some links that may interest you:

• 🚀 All my productivity articles
• ❓ Know more about me and my articles!
• 🔔 Become an email subscriber!
• 🤝 Support me by subscribing with my referal link: