* raven
~raven~ enables querying large language models via email. It retrieves messages from an IMAP mailbox, generates replies using an OpenAI API compatible LLM, and sends them via SMTP. LLMs can optionally invoke user defined external tools.

This project is under active development and breaking changes are possible.  The ~go-imap/v2~ dependency is also still in development.

** Features
- Monitor mailboxes with IMAP IDLE or polling
- Query LLMs with an OpenAI API (hosted or local)
- Multimodal input (text and images, inline or attached)
- Configurable concurrency for serializing access to a GPU, or to allow parallel message processing
- Sender allowlist for access control
- Tools defined with YAML, parsed with Go templates, and executed as subprocesses

** Limitations
- ~raven~ can handle replies, but does not attempt to reconstruct the conversation history for the OpenAI API. The quoted body, if provided, is sent alongside the user's latest message.
- Tools do not support variadic arguments. The ~{{ json . }}~ template function may serve as a workaround when a tool accepts a JSON blob.
- Messages may be reprocessed if:
  - ~raven~ fails to compose the reply.
  - SMTP send fails.
  - Marking the message as seen fails.
  - The process crashes during processing.
- Reply attribution (='On <date>, <sender> wrote:'=) is a constant string in English.
- Attachments are size-limited per MIME part (~maxPartSize~ = 32MB).

** Security
~raven~ can expose its host to a variety of security risks:

- Denial-of-Service: local LLM inference consumes significant compute; hosted providers incur billing. The volume of email and size of individual emails is another avenue of attack.
- Prompt injection ([[https://genai.owasp.org/llmrisk/llm01-prompt-injection/][direct, indirect, and crescendo attacks]])
- Unexpected costs (from tokens, tools, retries)
- Data exposure, if using a hosted LLM provider, or via manipulated tools.
- Arbitrary command execution and all its consequences, depending on the tools exposed.

The primary mitigation ~raven~ offers is the sender allowlist, which assumes (a) the email provider does not deliver unauthenticated (spoofed) email to the inbox (b) senders can be trusted with access, (c) senders secure access to their accounts.

Other mitigations which a user can consider include:
- Constraining the runtime and sandboxing ~raven~
- Sandboxing tools (jails, containers)
- Opting for narrow tools over broad ones (e.g., scripts versus bash -c).
- Monitoring and constraining resource usage or LLM API costs
- Auditing logs
- Defensive system prompts that constrain model behavior

This software is provided as-is; refer to the license.

** Requirements
- Go 1.25+
- An LLM server with OpenAI-compatible API (e.g., llama.cpp's ~llama-server~)
- IMAP/SMTP email account (or alias)
  - IMAP server must support at least two connections.

** Installation
From source:

#+begin_src sh
git clone https://code.chimeric.al/raven.git
cd raven
make
#+end_src

The binary is written to ~bin/raven~.

To install to ~$GOBIN~:

#+begin_src sh
make install
#+end_src

** Configuration

Environment variables can be referenced with ~${VAR}~ syntax.

Reference ~config.example.yaml~ for all options.

The path of least resistance is to either use a dedicated email account for ~raven~, or use an alias.

** Deployment

The path to the configuration file is required:

#+begin_src sh
raven -c ~/.config/raven/config.yaml # or /etc/raven/config.yaml
#+end_src

Example ~systemd~ service files for system or user-level services are in ~init/systemd/~.

** License

MIT
