Introducing Metaphor commands

Metaphor and the m6rc Metaphor compiler

Metaphor predates Humbug, and has been a part of the Humbug design since v0.1. It allows you to define the role, detailed context, and action you require for your AI to do its work. It also allows you to partition these elements into separate files and join them together and compile all the elements into a prompt using m6rc.

This modular approach, familiar to software developers, allows you to independently maintain and version important Metaphor components, allowing them to be used across many projects and tasks. Equally, these components can be maintained by different teams allowing them to bring their unique expertise to bear.

As with programming language compilers, m6rc also gets to perform correctness checks on the Metaphor files it processes. This helps ensure the structure you present as a prompt will make sense to your AI models.

The v0.10 improvement

The m6rc approach has been very powerful, but the user experience was a little awkward as you invariably had to edit one or more Metaphor source files each time you wanted to do something slightly different. With v0.10 of Humbug it's now possible to eliminate the major problem.

The new compiler can take "argument references" in Include and Embed statements. These take the form of $<number> where <number> is the number of the positional command line argument passed to m6rc. That may sound a little odd, so here's an example:

m6rc script.m6r -m gpt-4.1 cat.m6r dog.md

Positional arguments are the ones that don't have option flags (things starting with a -) and their associated option values (if they have them). In this example, the option -m has an option value of gpt-4.1, since it specifies the AI model to be used, and m6rc is our command. This leaves script.m6r, cat.m6r, and dog.md as our 3 positional arguments. By convention we start numbering them from 0, script.m6r is argument 0, cat is argument 1, and dog is argument 2.

If our script.m6r file contains the statement: Embed: $2 then the compiler will replace $2 with dog.md and will try to embed a file called dog.md into our compiled prompt. Similarly, if script.m6r contains the statement Include: $1 then this will try to include another Metaphor file called cat.m6r.

This very simple change makes it possible to define completely reusable AI-powered tools that need no changes to be used for different purposes. We simply pass extra parameters on the m6rc command line.

Revisiting commit-critic

Last year we introduced an example of a Metaphor-powered tool, commit-critic. This is an AI-powered software code review tool. To make this useful in November we had to build a custom command line tool that could handle the positional argument handling. With Humbug v0.10 we no longer need to do this, instead allowing commit-critic's functionality to be completely described in Metaphor!

Here's what a pure Metaphor version looks like:

Role:
    You are an expert software reviewer, highly skilled in reviewing code written by other engineers.  You are
    able to provide insightful and useful feedback on how their software might be improved.

Context: Review guidelines
    Include: $1

    Context: Files to review
        The software to be reviewed is found in the files provided here:

        Embed: $2

Action: Review code
    I would like you to do all of the following:

    1. Summarise how the software works.

    2. Review each file individually and comment on how it might be improved, based on the guidelines I
       have provided.  When you do this, you should tell me the name of the file you believe may want to be
       modified, the modification you believe should happen, and which of the guidelines the change would align
       with.  If any change you envisage might conflict with a guideline then please highlight this and the
       guideline that might be impacted.

    The review guidelines include generic guidance that should be applied to all file types, and guidance
    that should only be applied to a specific language type.  In some cases the specific guidance may not be
    relevant to the files you are asked to review, and if that's the case you need not mention it.  If, however,
    there is no specific guideline file for the language in which a file is written then please note that the
    file has not been reviewed against a detailed guideline.

    Where useful, I would like you to write new software to show me how any modified code should look.

    For each review item, I want you to rank the importance of any proposed change.  This should be ranked from 1
    to 4, where 1 is a critical issue, 2 is a major issue, 3 is a minor issue, and 4 is an observation.

If you're a keen observer, you may notice this has an enhancement on the original tool. This version ranks the importance of any issues it identifies to help you judge how serious any issues might be.

An introspection tool

Now you've seen how you can solve an earlier problem in a simpler way, let's look at how you can solve a new problem.

A common question people have asked about Humbug is "how easy is it to have one AI review the work of another AI?" It turns out you can now solve this sort of problem quite easily with Humbug v0.10.

Humbug has always supported .conv files. These are JSON files that hold details of the conversations you have with our AIs when using Humbug. These are stored in the conversations directory of any Humbug mindspace.

The approach outlined here took about 5 minutes to write, so it's not refined, but you can see the potential!

Role:
    You are a world class software architect, expert in performing a critical review of work performed
    by both human and AI software developers.

Context:
    The following is a conversation between a human developer and an AI assistant.

    Embed: $1

Action:
    Please review the conversation carefully and tell me what was learned between the original prompt
    and the end of the conversation.

Here's a screenshot of codestral (one of the Mistral models) reviewing a design change Metaphor conversation I had with Claude Sonnet 3.7 about an aspect of the system shell design from a few days ago!

What do you want to build?

We've seen how m6rc within the Humbug system shell can now enable you to build a whole series of new AI-powered tools. Couple this with the ability to now embed elements from previous conversations as well as other documents and source code and the possibilities are amazing.

We're excited to see what you will be able to build!

If you want to share your ideas, join us on Discord! For help with Metaphor and Humbug, check out our YouTube channel.