Hraesvelgr

From Wikiedia:

In Vafþrúðnismál (The Lay of Vafþrúðnir), Odin questions the wise jötunn Vafþrúðnir about the origin of the wind, and the jötunn answers:

He is called Hræsvelg,
who sits at heaven’s end,
a giant, in the shape of an eagle;
from his wings
they say the wind comes over all people.

(translated by John Lindow in Norse Mythology: A Guide to Gods, Heroes, Rituals, and Beliefs 2002)

Hraesvelgr provides a command-line tool and pipe filter for processing text with large language models using premade instructions (aka system and user prompts), either on local files or on input from a pipe.

A goal of this implementation is to work without any dependencies outside the set of packages provided by the Debian project. The history behind this project was published in a blog post 2026-05-23.

Inspired by and partly based on https://github.com/danielmiessler/fabric/ . The premade instructions were fetched from this project.

The latest edition can be found at https://codeberg.org/pere/hraesvelgr/ .

A simple example

Assuming you have a llama.cpp server running, for example using the Debian package and started like this:

LC_ALL=C llama-server -ngl 256  -c $(( 42 * 1024)) --temp 0.7 \
  --repeat_penalty 1.1 -n -1 \
  -m ~/src/llama-models/Qwen3-Coder-30B-A3B-Instruct-Q5_K_S.gguf

(this is my current command line running my local LLM)

When the server is running and accepting connections, you can ask the LLM to summarize the content of the Python script like this:

bin/hraesvelgr --baseurl http://localhost:8080/ \
  --pattern explain_code bin/hraesvelgr

The list of available patterns can be found by running bin/hraesvelgr --list-patterns.

The result I got back while writing this simple example was this:

EXPLANATION:
This Python script is a command-line utility designed to interact
with OpenAI-compatible Large Language Model (LLM) APIs. It processes
text input using predefined prompt templates ("patterns") that
define system and optional user instructions. The tool can read from
standard input, pipe data, or process files, making it suitable for
scripting and automation workflows.

**Key Components & Workflow:**
1. **Layered Configuration System:**
   - The script reads configuration from multiple `config.ini`
     locations in a specific priority order (system-wide → `/etc/` →
     user-specific → local). Settings in later files override
     earlier ones using Python's `configparser`.
   - It dynamically builds a list of directories (`datadirs`) where
     prompt patterns are stored, allowing administrators or users to
     extend default paths via configuration.

2. **Pattern Management:**
   - Patterns are organized as subdirectories containing `system.md`
     (required) and optionally `user.md`.
   - The `--list-patterns` flag scans these directories and prints
     available pattern names in a columnized format using an
     internal method from Python's `cmd` module.
   - The `read_file()` function loads prompt templates and performs
     placeholder substitution, currently supporting only
     `{{lang_code}}` (defaulting to `nb-no`).

3. **Command-Line Interface:**
   - Accepts an optional input file (defaults to stdin).
   - Provides flags for API configuration (`--baseurl`, `--apikey`,
     `--model`), pattern selection (`--pattern`), debugging, and
     pattern inspection (`--show-pattern`).
   - Ensures the base URL ends with a `/` and issues a security
     warning if non-loopback HTTP endpoints are used (to prevent
     accidental plaintext transmission of API keys).

4. **LLM API Interaction:**
   - Constructs an OpenAI-compatible JSON payload containing
     `system` and `user` messages, plus the actual input query.
   - Sends a synchronous POST request to
     `{baseurl}chat/completions`. Streaming is disabled for
     simplicity.
   - Parses the JSON response, safely navigating nested dictionaries
     to extract the generated content from
     `choices[0].message.content`.
   - Includes robust error handling for HTTP failures, malformed
     responses, and missing fields.

5. **Input & Output Handling:**
   - Reads input text with a UTF-8 fallback to ISO-8859-1/Latin1 if
     decoding fails.
   - Sets `max_tokens` heuristically: it uses the character length
     of the input query, enforcing a minimum of 11,264 tokens to
     accommodate most translation or summarization tasks. (Note:
     This counts characters, not actual LLM tokens.)
   - Outputs the model's response directly to stdout.

**Dependencies & Compatibility:**
- Relies on standard Python libraries (`argparse`, `configparser`,
  `os`, `sys`, etc.) plus `requests` for HTTP communication. The
  docstring notes it aims to run within Debian's default package
  ecosystem, which includes `python3-requests`.
- Designed as a pipe filter or batch processor, making it highly
  integrable into shell scripts and data processing pipelines.

License

The source code is licensed under the GNU General Public License version 2 or later versions at the user's choice (see LICENSE-GPL2). The data/ directory is licensed according to the MIT license, matching the origin from the AI Fabric project (see LICENSE-MIT copied from this project).