Brainiall Pack for StackStorm

Run two explicit Brainiall API operations from StackStorm:

• brainiall.text_to_speech converts text to a WAV file.
• brainiall.pdf_to_markdown converts one local PDF to Markdown or structured JSON.

Both actions call the hosted, metered Brainiall API. Only the text or PDF explicitly supplied to an action is sent to the service. Review the current Brainiall pricing, privacy, and data-handling terms before processing sensitive material.

Install

Install the public repository:

st2 pack install https://github.com/fasuizu-br/stackstorm-brainiall.git

Copy the example configuration, replace the placeholder locally, restrict its permissions, and register the configuration:

sudo cp brainiall.yaml.example /opt/stackstorm/configs/brainiall.yaml
sudo chmod 600 /opt/stackstorm/configs/brainiall.yaml
sudo st2ctl reload --register-configs

Create an API key at app.brainiall.com. Never commit the populated configuration file. The schema marks api_key as secret: true.

Text to speech

st2 run brainiall.text_to_speech \
  text="This is a non-sensitive example." \
  voice="af_heart" \
  speed=1.0 \
  output_path="/tmp/brainiall-speech.wav"

The text action parameter is also marked secret so StackStorm masks it in execution views. Your interactive shell can still retain commands in its own history, so pass sensitive text from a secured workflow rather than a terminal command.

PDF to Markdown

st2 run brainiall.pdf_to_markdown \
  pdf_path="/srv/stackstorm/input/manual.pdf" \
  output_path="/srv/stackstorm/output/manual.md" \
  page_range="1-20" \
  output_format="markdown"

Input and output paths must be absolute. The PDF must be a regular, non-symlink file no larger than 25 MiB. Output is written atomically with mode 0600; an existing output is replaced only after a successful API response.

Security behavior

• The API key is read only from StackStorm pack configuration.
• Requests use fixed HTTPS Brainiall endpoints and do not accept an override URL.
• Authentication is sent in headers, never in a URL or action result.
• Action code does not log request content, response content, file content, or credentials.
• HTTP failures return only a status code; response bodies are not echoed.
• Requests are not retried, avoiding duplicate metered work after an ambiguous failure.
• TTS accepts 1-5,000 characters and validates WAV output.
• PDF conversion validates the file signature, size, page range, and output format.

Local validation

python3 scripts/validate_pack.py
python3 -m unittest discover -s tests -v

The tests mock all network calls. They use no Brainiall key and send no content externally.

License

Apache License 2.0.