├── .gitignore ├── CHANGELOG.md ├── README.md └── img ├── api-keys.webp ├── first-conversation-success.webp ├── first-conversation.webp ├── first-question.webp ├── hello-cat.webp ├── hello-genz.webp ├── hello-m6r.webp ├── hello-toddler.webp ├── hello-world.webp ├── new-mindspace.webp ├── report-outline.webp ├── start-screen.webp └── updated-m6r.webp /.gitignore: -------------------------------------------------------------------------------- 1 | # Ignore temp files 2 | *~ 3 | *.swp 4 | 5 | # Ignore virtual environment 6 | venv 7 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog for getting-started-with-metaphor 2 | 3 | ## v0.4 (2025-05-15) 4 | 5 | - Correct a grammar mistake. 6 | 7 | ## v0.3 (2025-05-12) 8 | 9 | - Update the instructions for setting up Humbug to match Humbug v0.12 10 | - Improve section headings. 11 | 12 | ## v0.2 (2025-05-01) 13 | 14 | - Add commentary on the importance of "role". 15 | - Add "PS" section about more advanced uses of m6rc. 16 | - Fixed spelling mistake. 17 | 18 | ## v0.1 (2025-05-01) 19 | 20 | This is the initial release. 21 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Getting started with Metaphor 2 | 3 | Version 0.4 - 2025-05-13 4 | 5 | ## Introduction 6 | 7 | Prompting AIs can be hard. 8 | While they sometimes do exactly what you want, they often get it wrong. 9 | Even when you do get what you want, it's far too easy to lose track of what worked and why. 10 | It's even harder when you want to work with multiple AIs. 11 | 12 | Metaphor is a simple, open-source, prompt creation language that lets you create consistent, reusable prompts that 13 | work across a variety of AI platforms. 14 | It lets you capture what you need your AI to understand so it has a clear idea what you want it to do, without 15 | needing to guess (hallucinate) any details. 16 | 17 | Metaphor solves three key problems that plague direct prompting: inconsistency across different AI models, 18 | difficulty maintaining prompt history, and challenges in collaboration. 19 | By structuring prompts with clear rules, Metaphor creates a standardized approach that works reliably across 20 | different AI platforms while making prompts reusable and shareable with team members. 21 | 22 | Metaphor is AI agnostic. 23 | It works the same way with large language models from all major AI vendors, including Anthropic, DeepSeek, Google, 24 | Mistral, OpenAI, and xAI, making it easy to switch between them and find the right one for your needs. 25 | 26 | The Metaphor language is easy to learn. 27 | It has only a few keywords and takes only a few minutes to get started. 28 | This guide will show you how. 29 | 30 | You can find out more about Metaphor at [https://m6r.ai/metaphor](https://m6r.ai/metaphor). 31 | 32 | ## Who is this for? 33 | 34 | Metaphor has many uses. 35 | Here are some examples of users it can help: 36 | 37 | - Software developers who want consistent, reliable AI assistance 38 | - Teams collaborating on AI-assisted projects 39 | - Technical writers creating documentation with AI help 40 | - Researchers who need reproducible AI interactions 41 | - Anyone who wants their AI interactions to be more structured and reliable 42 | 43 | While no programming experience is required to use Metaphor, basic familiarity with text editors and file systems 44 | will be helpful for following this guide. 45 | 46 | ## How is Metaphor used? 47 | 48 | Metaphor is designed to be used at the start of a new conversation with an AI large language model (LLM). 49 | It sets the scene for the LLM, ensuring it knows how you want it behave, what you want it to do, and allows you to 50 | tell it everything it needs to know to do that. 51 | Throughout this document you'll see AI and LLM used interchangeably. 52 | 53 | You might ask "AIs know almost everything - why do I need to do this?" 54 | The answer is surprisingly simple. 55 | AI models know a huge amount but they have no idea what you're trying achieve or how you want them to help us unless 56 | you tell them. 57 | 58 | One way to think about this is if you want to ask another human how to do something, you have to explain these things 59 | to them. 60 | AIs are no different. 61 | Unlike most people, however, LLMs don't remember what you've said to them before. 62 | Fortunately, they are incredibly fast at reading so they can get up to speed in a few seconds if you give 63 | them the full picture from the outset. 64 | 65 | While forgetfulness might seem like a nuissance, working with LLMs this way can have surprising benefits. 66 | Here are a few: 67 | 68 | - Each new conversation is a fresh start so the LLM doesn't bring misunderstandings or disagreements from 69 | previous conversations into the new one. 70 | - You can have the same conversation with different LLMs and see what new insights come from each one. 71 | - It's possible to start a conversation with one AI and finish it with a different one. 72 | 73 | ## A first Metaphor prompt 74 | 75 | All Metaphor prompts start with the same structure. 76 | First, there's a "role" that describes the role you want your AI to play. 77 | Second, there's a "context" that tells the AI everything it needs to know that's specific to what you want it to do. 78 | Third (and last), there's an "action" that tells the AI what you want it to do. 79 | 80 | Each of these has a special keyword in the Metaphor language, specifically, `Role`, `Context`, and `Action`. 81 | The capital letters at the start of each keyword are important. 82 | 83 | Here's an example: 84 | 85 | ```metaphor 86 | Role: 87 | You are a world-class python programmer. 88 | 89 | Context: 90 | I need a simple program to demonstrate using the Metaphor language to solve a programming problem. 91 | 92 | Action: 93 | Build me a "hello world" program. 94 | ``` 95 | 96 | If you give this simple example to an AI (perhaps via a web chat interface) you'll probably find it does the right 97 | thing without any extra work, but to use Metaphor properly you need to use the `m6rc` prompt compiler. 98 | 99 | ## The m6rc prompt compiler 100 | 101 | The `m6rc` prompt compiler is a software tool that checks your Metaphor language prompt is structured the right way 102 | and translates that into the actual prompt your AI requires. 103 | It also has functionality to allow you to build more sophisticated prompts. 104 | For now, you don't need to worry about that - we'll get to it later. 105 | 106 | In case you're wondering, "m6r" is short for Metaphor - it's an "m", 6 letters, and an "r", so `m6rc` is short for 107 | "Metaphor compiler". 108 | 109 | There are currently two versions of the `m6rc` software. 110 | One is a command line version and you can find this at [https://github.com/m6r-ai/m6rc](https://github.com/m6r-ai/m6rc). 111 | The other is built into a GUI-based application called "Humbug". 112 | If you don't have this already you can find instructions on how to download the latest free (open source) version 113 | from [https://m6r.ai/humbug](https://m6r.ai/humbug). 114 | 115 | For this getting started guide you're going to be using Humbug. 116 | 117 | ## Getting started with Humbug 118 | 119 | Humbug is a front end for LLMs, but doesn't contain an LLM. 120 | It supports many popular LLMs from Anthropic, DeepSeek, Google, Mistral, OpenAI, and xAI. 121 | It also supports local installations of Ollama. 122 | With the exception of Ollama, all the others are commercial services that require API (application programming interface) 123 | keys to use them. 124 | 125 | Generally commercial LLM providers require you to pay in advance. 126 | The costs can be very low, but both Google and Mistral currently offer a free tier of API access for testing and you 127 | can use them. 128 | 129 | You can follow these sign up links: 130 | 131 | - Google: [https://ai.google.dev/gemini-api/docs/api-key](https://ai.google.dev/gemini-api/docs/api-key) 132 | - Mistral: [https://docs.mistral.ai/getting-started/quickstart/](https://docs.mistral.ai/getting-started/quickstart/) 133 | 134 | Next you can start Humbug. 135 | 136 | ### First steps 137 | 138 | Once it's running for the first time you'll see something a little like this: 139 | 140 | ![start screen](img/start-screen.webp) 141 | 142 | If you go to the "Humbug" menu and select "Preferences" you will see a user settings page. There are quite a lot of 143 | settings so this page scrolls up and down: 144 | 145 | ![API key settings](img/api-keys.webp) 146 | 147 | Find the Google and/or Mistral (or any other) sections. 148 | For each one, enable the backend by selecting the checkbox and then copy your matching API keys into the appropriate lines. 149 | You don't need to put anything in the optional API URL setting as those are advanced options for using private LLMs. 150 | Once you're done, click OK. 151 | 152 | You'll want to check the API keys are working properly. 153 | The easiest way to do this is to start a conversation, but Humbug needs you to do one thing first. 154 | 155 | ### Mindspaces 156 | 157 | Humbug is designed to let you work on lots of different projects and have different settings and preferences for each. 158 | It does this by using a "Mindspace". 159 | Each project uses a different mindspace. 160 | For this getting started guide the easiest choice is to create a new mindspace using the "New Mindspace" option from 161 | the "File" menu. 162 | You can use an existing folder for your mindspace, but it's probably best to create a new folder when you click 163 | "New Mindspace". 164 | 165 | Once you've selected the location for your new mindspace, you'll see a new dialog that looks something like this: 166 | 167 | ![New Mindspace](img/new-mindspace.webp) 168 | 169 | The dialog shows Humbug will always create a "conversations" folder, and defaults to creating a "metaphor" folder. 170 | It has an option to also create a "src" folder for software development if you want it. 171 | 172 | ### Humbug Directory Structure 173 | 174 | When you create a new mindspace, Humbug sets up a directory structure like this: 175 | 176 | ```plaintext 177 | my-project/ # Your mindspace root folder 178 | ├── conversations/ # Where conversation records are stored 179 | ├── metaphor/ # Where your .m6r files should be saved 180 | │ ├── Hello.m6r # Example file we'll create later 181 | │ └── python-rules.m6r # Example include file we'll create later 182 | └── src/ # (Optional) For source code files 183 | ``` 184 | 185 | Throughout this guide, when we refer to saving files in the "metaphor folder," we mean this specific directory 186 | within your mindspace. 187 | 188 | ### A test conversation 189 | 190 | To test your API keys, start a conversation by selecting "New Conversation" from the "File" menu. 191 | Humbug will choose a default AI model and conversations settings for you to use. 192 | You can change these using the "Mindspace Settings" option in "Edit" menu, and you can also change them on a 193 | conversation-by-conversation basis by using the "Conversation Settings" option. 194 | When you do either of these you will be presented with AI models that are available with your API keys. 195 | 196 | You'll see a screen something like this: 197 | 198 | ![First conversation screen](img/first-conversation.webp) 199 | 200 | You can type a message to the AI in the message box at the bottom. 201 | When you're done, you submit the message by pressing Cmd+J on Mac OS, or Ctrl+J on Windows or Linux. 202 | The return/enter key doesn't submit messages because this message box is designed to let you write very complex 203 | messages to the AI and you don't want to accidently submit them when you're trying to lay out text. 204 | 205 | If you say something like "Hello", you should see a response back from the AI. 206 | If you get a system error message then re-check your API keys have been entered correctly in the Preferences dialog. 207 | 208 | ![First conversation screen with a reply from the AI](img/first-conversation-success.webp) 209 | 210 | ## Using m6rc 211 | 212 | The `m6rc` Metaphor compiler works on files you create. 213 | By convention these have a `.m6r` file extension type. 214 | 215 | ### Working with Metaphor files 216 | 217 | You can create and edit Metaphor files using the file editor within Humbug. 218 | To create a new file, use the "New File" option in the "File" menu. 219 | 220 | Until you save a file, the editor isn't sure what sort of a file it is and so won't highlight the different parts of 221 | the Metaphor language, but if you use the "Save As" option in the "File" menu you can save your new file as 222 | something like `Hello.m6r`. 223 | An ideal place to save this is in the `metaphor` folder that was created when you created the new mindspace. 224 | 225 | To get started, let's go back to the simple Metaphor file from earlier: 226 | 227 | ```metaphor 228 | Role: 229 | You are a world-class python programmer. 230 | 231 | Context: 232 | I need a simple program to demonstrate using the Metaphor language to solve a programming problem. 233 | 234 | Action: 235 | Build me a "hello world" program. 236 | ``` 237 | 238 | Copy and paste this into your new `Hello.m6r` file, then save it, and you should see it looks something like this: 239 | 240 | ![A simple metaphor prompt file](img/hello-m6r.webp) 241 | 242 | ### Compiling a prompt 243 | 244 | There are a couple of different ways to use the Metaphor compiler inside Humbug. 245 | The most powerful one is to use the "System Shell" as that lets you compile your Metaphor prompt and start a 246 | conversation with your AI using that compiled prompt in one command. 247 | The simpler option, however, is to use the "New Metaphor Conversation" option in the "File" menu. 248 | 249 | When the dialog appears, choose your `Hello.m6r` file and click OK. 250 | 251 | If all goes well you will see a new conversation tab opened and the output of `m6rc` will be shown in the message box. 252 | This isn't automatically sent to the AI so you can change the AI model and conversation settings if you want to. 253 | Once you're happy with those settings you submit the prompt with Cmd+J (Mac OS) or Ctrl+J (Windows or Linux). 254 | 255 | If everything works, the AI will respond with a simple one-line python program - the famous "Hello, world!". 256 | The format may be a little different, as AIs will not respond the same way every time. 257 | 258 | ![Hello, world output](img/hello-world.webp) 259 | 260 | ### A slight aside about Humbug 261 | 262 | You may have noticed that Humbug has a `conversations` folder. 263 | If you expand this you'll see both of the conversations you've had with the AI are stored there. 264 | You can safely delete these if you no longer want them, but they can be a great record of your conversations with 265 | different LLMs. 266 | You can also give them more meaningful names, as by default they have the date and time of the conversation as their name. 267 | 268 | You may also have seen there are icons/buttons on the right hand side of parts of the conversations. 269 | These let you copy or save sections of conversations. 270 | This is really useful when they contain file contents or code fragments you want to use elsewhere. 271 | There are also some powerful conversation management features, although they are out of scope for this tutorial. 272 | 273 | ### Metaphor conversations are just conversations 274 | 275 | If you look at your Metaphor conversation you'll see that after the AI responds you can carry on the conversation. 276 | This is just like you would do with an app or web-based chat interface. 277 | 278 | For example, you can ask the AI questions about what it has just done: 279 | 280 | ![Asking about the hello world program](img/first-question.webp) 281 | 282 | This ability to ask questions is incredibly useful. 283 | Here are some benefits: 284 | 285 | - You can ask the AI any questions you might have about what you gave it in the Metaphor prompt. 286 | - You can ask the AI explain any part of what it generates. 287 | - You can ask it how confident it is in its answers. 288 | - You can even ask how to improve your prompt if want to be able to use it again in the future. 289 | 290 | ## More about Metaphor's syntax 291 | 292 | Here's the simple example again: 293 | 294 | ```metaphor 295 | Role: 296 | You are a world-class python programmer. 297 | 298 | Context: 299 | I need a simple program to demonstrate using the Metaphor language to solve a programming problem. 300 | 301 | Action: 302 | Build me a "hello world" program. 303 | ``` 304 | 305 | There are a few more important parts to this: 306 | 307 | - After each keyword is a `:`. 308 | This is because all Metaphor keywords allow additional information on the keyword line. 309 | - Each block of text is indented by 4 spaces. 310 | This spacing is important because it lets the Metaphor compiler check the contents of the Metaphor file. 311 | All indentations within Metaphor files are 4, or multiples of 4 spaces. 312 | 313 | After each of these 3 types of keyword, Metaphor lets you specify a section/subsection heading. 314 | This is like the section headings in a normal document. 315 | These are useful because they let you structure things more clearly. 316 | They are also useful because you can discuss specific parts of the Metaphor prompt with the AI. 317 | 318 | Within a `Role` section, you can have other `Role` sub-sections. 319 | Similarly, within a `Context` section, you can have other `Context` sub-sections, and you can have `Action` 320 | sub-sections within an `Action` section. 321 | In most cases, you probably won't use sub-sections in anything other than the `Context` section. 322 | This is because it's the `Context` section where you provide all the details of what you want, why you want it, 323 | and how you want it. 324 | 325 | ### The importance of role 326 | 327 | You may find some tutorials that try to downplay the importance of being clear about the role you wish your 328 | AI to take, but it can have very dramatic effects. 329 | 330 | For fun, here is the output of our "hello, world" Metaphor prompt again, but where the role has been changed to 331 | tell the AI to adopt 3 very different roles! 332 | 333 | We'll leave it to your personal sense of humour to decide which one you like the most. 334 | 335 | #### You are a cat 336 | 337 | ![Hello from a cat](img/hello-cat.webp) 338 | 339 | #### You are a Gen Z 340 | 341 | ![Hello from a Gen Z](img/hello-genz.webp) 342 | 343 | #### You are a 2 year old toddler 344 | 345 | ![Hello from a toddler](img/hello-toddler.webp) 346 | 347 | ### Adding context 348 | 349 | So far we've seen a very simple example, but real-world problems are more complex and need more information. 350 | You can do with this by expanding the context section. 351 | 352 | Here's a simple example where more context is being provided: 353 | 354 | ```metaphor 355 | Role: 356 | You are a world-class python programmer. 357 | 358 | Context: 359 | I need a simple program to demonstrate using the Metaphor language to solve a programming problem. 360 | 361 | Context: Python implementation rules 362 | As an engineer working with the application, I want the application to be easy to use and understand, 363 | so I can maintain and enhance it over time. 364 | 365 | Context: Implement in Python 3 366 | The application will be written in the latest version of Python 3. Assume a baseline of Python 3.10. 367 | 368 | Context: Indentation of code 369 | Code must be indented by 4 spaces. 370 | 371 | Context: Use docstrings 372 | Docstrings must be used to describe all modules, classes, and functions. This should follow PEP 257 guidelines. 373 | 374 | Context: Use type hints 375 | Type hints must be used for function arguments and return values. 376 | 377 | Context: Use comments 378 | Comments must be used to describe any complex logic, or rationale that would not be obvious from 379 | simply reading the code. This ensures that anyone reading the code for the first time will be able 380 | to understand why the code is the way it is. 381 | 382 | Context: PEP 8 imports 383 | The import list in any module should follow PEP 8 guidelines, including the ordering of imports. 384 | 385 | Action: 386 | Build me a "hello world" program. 387 | ``` 388 | 389 | The simple example now includes guidance to the LLM about how it should structure its Python code. 390 | For our simple "Hello, world!" program, this doesn't matter too much, but if you want something more interesting, 391 | then these are the sorts of things a developer would likely care about. 392 | 393 | One thing to note is the AI understands all of these things but it also understands lots of other ways it could 394 | achieve a working program. 395 | By being more precise, the Metaphor prompt helps make sure any resulting software follows in that specific form. 396 | 397 | ### When to use context subsections 398 | 399 | Context subsections help organize information in a hierarchical structure. 400 | The form is not fixed, but here are some example of how you might want to use them. 401 | 402 | The more complex your task, the more valuable structured context subsections become. 403 | 404 | The text inside the square brackets indicates the sort of detail you might include 405 | 406 | #### Categorizing information 407 | 408 | Group related information under descriptive headings: 409 | 410 | ```metaphor 411 | Context: User requirements 412 | [User requirement details] 413 | 414 | Context: Technical constraints 415 | [Technical constraint details] 416 | ``` 417 | 418 | #### Establishing priorities 419 | 420 | Structure information from most to least important: 421 | 422 | ```metaphor 423 | Context: Must-have features 424 | [Critical feature details] 425 | 426 | Context: Nice-to-have features 427 | [Optional feature details] 428 | ``` 429 | 430 | #### Creating relationships 431 | 432 | Show how different pieces of information relate to each other: 433 | 434 | ```metaphor 435 | Context: Database structure 436 | [Database overview] 437 | 438 | Context: User table 439 | [User table details] 440 | 441 | Context: Product table 442 | [Product table details] 443 | ``` 444 | 445 | #### Separating concerns 446 | 447 | Keep different aspects of the problem distinct: 448 | 449 | ```metaphor 450 | Context: Frontend requirements 451 | [Frontend details] 452 | 453 | Context: Backend requirements 454 | [Backend details] 455 | ``` 456 | ### Comments 457 | 458 | Sometimes it's useful to make notes in a Metaphor prompt that won't be passed to the AI. 459 | These are comments for the benefit of anyone who might want to understand, reuse, or update the prompt. 460 | 461 | In Metaphor, comments start with a `#` symbol. 462 | Everything after that symbol on the same line is completely ignored by `m6rc`. 463 | 464 | You could add comments like this: 465 | 466 | ```metaphor 467 | Role: 468 | # We want the AI to be a world-class programmer so it does its best work. We don't want it to act like a novice. 469 | You are a world-class python programmer. 470 | 471 | Context: 472 | I need a simple program to demonstrate using the Metaphor language to solve a programming problem. 473 | 474 | # Ensure the AI follows our coding standards. 475 | Context: Python implementation rules 476 | As an engineer working with the application, I want the application to be easy to use and understand, 477 | so I can maintain and enhance it over time. 478 | 479 | Context: Implement in Python 3 480 | The application will be written in the latest version of Python 3. Assume a baseline of Python 3.10. 481 | 482 | Context: Indentation of code 483 | Code must be indented by 4 spaces. 484 | 485 | Context: Use docstrings 486 | Docstrings must be used to describe all modules, classes, and functions. This should follow PEP 257 guidelines. 487 | 488 | Context: Use type hints 489 | Type hints must be used for function arguments and return values. 490 | 491 | Context: Use comments 492 | Comments must be used to describe any complex logic, or rationale that would not be obvious from 493 | simply reading the code. This ensures that anyone reading the code for the first time will be able 494 | to understand why the code is the way it is. 495 | 496 | Context: PEP 8 imports 497 | The import list in any module should follow PEP 8 guidelines, including the ordering of imports. 498 | 499 | Action: 500 | # Ask the AI to do exactly one thing. 501 | Build me a "hello world" program. 502 | ``` 503 | 504 | Humbug's syntax highlighting makes this all a little easier to read! 505 | 506 | ![Updated hello world metaphor file](img/updated-m6r.webp) 507 | 508 | There are a couple of important rules to note here: 509 | 510 | - Text descriptions are indented by 4 spaces from the `Context` keyword that starts the sub-section. 511 | This gives a strong visual cue about the relationship between different sub-sections. 512 | - Text descriptions must come immediately after the `Context` keyword. 513 | It's possible to add multiple paragraphs, but once a new `Context` subsection is started it's no longer 514 | possible to add more description text afterwards. 515 | 516 | As an example, the following is not valid in Metaphor: 517 | 518 | ```metaphor 519 | Context: Python implementation rules 520 | As an engineer working with the application, I want the application to be easy to use and understand, 521 | so I can maintain and enhance it over time. 522 | 523 | Context: Implement in Python 3 524 | The application will be written in the latest version of Python 3. Assume a baseline of Python 3.10. 525 | 526 | Here's some more text. The compiler will generate an error if we try to do this. 527 | ``` 528 | 529 | ## Embedding content 530 | 531 | The Metaphor syntax you've seen so far is quite limited as it's just simple text. 532 | For many problems, and almost all software development work, you need to give your AI other information. 533 | 534 | One way to do this is to use three backticks to introduce structured information. 535 | This is very similar to Markdown and is very useful for introducing things like document or source code snippets. 536 | 537 | For example, you can insert a segment of Python source code into a `Context` block like this: 538 | 539 | ```metaphor 540 | Context: Existing code 541 | The following function implements path validation: 542 | 543 | ```python 544 | def validate_include_paths(paths: List[str]) -> Optional[str]: 545 | if not paths: 546 | return None 547 | 548 | for path in paths: 549 | if not os.path.isdir(path): 550 | return f"Not a valid directory: {path}" 551 | 552 | return None 553 | ``` 554 | ``` 555 | 556 | This approach is great for short fragments, but complex applications may have many thousands of lines of documents 557 | or code. 558 | To address this, Metaphor has an `Embed` keyword. 559 | 560 | The `Embed` keyword takes the name of a file after the colon that follow it. 561 | When `m6rc` encounters this it will read the file and embed the contents of the file into the prompt. 562 | This means each time the prompt is compiled, the current version of the file is used. 563 | 564 | Here's an example: 565 | 566 | ```metaphor 567 | Context: Existing code 568 | The following file implements the start of the application: 569 | 570 | Embed: src/m6rc/m6rc.py 571 | ``` 572 | 573 | The `Embed` keyword can use wildcard matches, so one `Embed` statement can embed multiple files. 574 | For example, the following statement will embed all the Python files in a folder: 575 | 576 | ```metaphor 577 | Embed: src/m6rc/*.py 578 | ``` 579 | 580 | ### Good practices for embedding content 581 | 582 | When using the `Embed` keyword, you should keep these guidelines in mind: 583 | 584 | #### Size limitations 585 | 586 | While LLMs can process large amounts of text, they all have "token" limits. 587 | Tokens are the way LLMs break down your message. 588 | There's no easy way to predict how many tokens are used in a conversation, but in English a 589 | token is typically about 3/4 of a word, and each unit of punctuation is often a token too. 590 | 591 | LLM pricing is usually based on the numbers of tokens used, so the more tokens you use, the more expensive the 592 | prompt is. 593 | 594 | For best results: 595 | 596 | - Prioritize the most relevant files 597 | - Consider splitting very large files into smaller, focused components 598 | 599 | If you are using an AI to help with software development you will want to add all the details your AI needs to 600 | understand your code, but you should look to avoid supplying large files that aren't relevant to the problem you 601 | want to solve. 602 | 603 | #### Organization patterns 604 | 605 | Organizing embedded files into logical groupings can make things easier for an AI to understand: 606 | 607 | - Group related files together in your prompt structure 608 | - Provide context before embedding files (e.g. explain what they are for) 609 | - Add commentary after embedded content to highlight key points 610 | 611 | For example, you might do something like this: 612 | 613 | ```metaphor 614 | Context: Project codebase 615 | The system consists of several key components: 616 | 617 | Context: Core data structures 618 | Here are the core data structures that define our domain model: 619 | Embed: src/models/*.py 620 | 621 | The User and Product classes are the most important to understand. 622 | 623 | Context: API endpoints 624 | These are the main API endpoints: 625 | Embed: src/api/routes.py 626 | ``` 627 | 628 | #### When to avoid embedding 629 | 630 | Not all file types are currently supported. 631 | For now only human-readable text files can be embedded successfully. 632 | If you have a binary file then consider using a description instead. 633 | 634 | ## Another example: a data analysis report 635 | 636 | Let's look at a different type of problem - creating a data analysis report. 637 | This demonstrates how Metaphor helps with a complex, structured task that would be difficult to achieve with a single 638 | ad-hoc prompt. 639 | 640 | ```metaphor 641 | Role: 642 | You are a data analyst specializing in business insights. 643 | 644 | Context: 645 | I need to create a quarterly sales report for my company's management team. 646 | 647 | Context: Report requirements 648 | The report must include: 649 | 650 | - Executive summary (1 paragraph) 651 | - Sales trends for Q1 2025 compared to Q1 2024 652 | - Top 5 performing products 653 | - Regional breakdown of sales 654 | - Recommendations for Q2 2025 655 | 656 | Context: Data source 657 | ```csv 658 | region,product,q1_2024_sales,q1_2025_sales 659 | North,Widget A,120000,145000 660 | North,Widget B,85000,91000 661 | South,Widget A,95000,102000 662 | South,Widget B,110000,105000 663 | East,Widget C,78000,92000 664 | West,Widget C,65000,88000 665 | ``` 666 | 667 | Action: 668 | Create a structured report outline with placeholders for the required sections. 669 | ``` 670 | 671 | With this Metaphor prompt, the AI knows exactly what role to play, has all the necessary context including the data, 672 | and has clear instructions for the specific task. 673 | You could then follow up with additional ad-hoc prompts to refine specific sections of the report. 674 | By structuring this using Metaphor, we've made it easy to change aspects of the prompt as the need arises. 675 | Maybe the sales data changes, perhaps you are asked for the output in a different format. 676 | Whatever the change, you can now update the Metaphor prompt to meet your needs. 677 | 678 | Here's an example of what you might see if your run this Metaphor prompt: 679 | 680 | ![A report outline generated by AI](img/report-outline.webp) 681 | 682 | ## Including other Metaphor files 683 | 684 | The `Embed` keyword is a powerful way to add content to a `Context` block, but it really just attaches files to 685 | the prompt sent to the AI. 686 | It doesn't allow for extending Metaphor descriptions. 687 | 688 | There are many reasons you might want to do this, but here are a few: 689 | 690 | - You might want to reuse them same Metaphor elements in multiple prompts. 691 | E.g. you might want to use the same coding rules in all your projects. 692 | - Some parts of a Metaphor prompt might come from different people or teams. 693 | E.g. some parts might come from product managers, or security experts, while others come from software developers. 694 | - You may wish to use the same context information for different purposes. 695 | E.g. you may wish to have the AI offer advice as a product manager instead of as a developer, or you may want to have 696 | an action that asks the AI to review the context instead of using it to do something using it. 697 | 698 | To solve this type of problem, Metaphor has an `Include` keyword. 699 | 700 | `Include` statements have a file name that follows the `:` and the `m6rc` compiler inserts that file where the 701 | `Include` statement is. 702 | The compiler automatically adds indentation to each included line to ensure the document-like structure of the prompt 703 | is maintained. 704 | 705 | If you wanted to split our last example, here's how you could do it! 706 | First split out the Python rules into a new file, called `python-rules.m6r` and put it in the `metaphor` folder: 707 | 708 | ```metaphor 709 | # Ensure the AI follows our coding standards. 710 | Context: Python implementation rules 711 | As an engineer working with the application, I want the application to be easy to use and understand, 712 | so I can maintain and enhance it over time. 713 | 714 | Context: Implement in Python 3 715 | The application will be written in the latest version of Python 3. Assume a baseline of Python 3.10. 716 | 717 | Context: Indentation of code 718 | Code must be indented by 4 spaces. 719 | 720 | Context: Use docstrings 721 | Docstrings must be used to describe all modules, classes, and functions. This should follow PEP 257 guidelines. 722 | 723 | Context: Use type hints 724 | Type hints must be used for function arguments and return values. 725 | 726 | Context: Use comments 727 | Comments must be used to describe any complex logic, or rationale that would not be obvious from 728 | simply reading the code. This ensures that anyone reading the code for the first time will be able 729 | to understand why the code is the way it is. 730 | 731 | Context: PEP 8 imports 732 | The import list in any module should follow PEP 8 guidelines, including the ordering of imports. 733 | ``` 734 | 735 | Then include those rules in your `Hello.m6r` file: 736 | 737 | ```metaphor 738 | Role: 739 | # We want the AI to be a world-class programmer so it does its best work. We don't want it to act like a novice. 740 | You are a world-class python programmer. 741 | 742 | Context: 743 | I need a simple program to demonstrate using the Metaphor language to solve a programming problem. 744 | 745 | Include: metaphor/python-rules.m6r 746 | 747 | Action: 748 | # Ask the AI to do exactly one thing. 749 | Build me a "hello world" program. 750 | ``` 751 | 752 | Now you have a set of reusable rules. 753 | 754 | You can also use `Include` inside other files that you include to encourage modularity and reusability. 755 | 756 | ## More on roles and actions 757 | 758 | The keywords `Role` and `Action` are singular for a reason! 759 | 760 | Your AI can't try to fulfil two different roles, so don't try to confuse it by asking it to take on more 761 | than one role in a prompt. 762 | If you need two roles to be played, then that's two prompts. 763 | 764 | Likewise, if you ask your AI to do more than one thing at a time, then just like most people, it's unlikely to 765 | do any of them the way you want. Instead think about how to break down the things you want into steps that 766 | can be done in sequence. 767 | 768 | Some reasoning/thinking AI models can attempt to break things down automatically but the danger is they get 769 | some intermediate step wrong and the end result isn't what you want. 770 | 771 | You can still have your AI help you break problems down, just make this an explicit part of the process. 772 | You can ask an LLM to give you a plan to review and then use that as the basis of a series of steps. 773 | It won't remember the plan unless you tell it, so don't forget to capture the details in the follow-on Metaphor prompts. 774 | 775 | It's also worth remembering that Humbug doesn't automatically submit a prompt when you start a Metaphor conversation. 776 | Another reason for this is so you can use the same base Metaphor prompt but make small changes manually. 777 | If you have a 5 step plan you can create a prompt that includes all 5 steps and then just tell it which step to start 778 | from each time you use the prompt. 779 | 780 | ## More on context 781 | 782 | The majority of the content in a Metaphor prompt is the context section. 783 | This where you get to have the greatest impact on what your AI can do, but it's also where you can confuse it 784 | if you're not careful. 785 | 786 | Here are a few more tips and tricks for the context blocks: 787 | 788 | - Be descriptive - describe things and why you want them, so the AI understands what you're trying to achieve. 789 | Try to avoid unconditional statements that might look like actions. 790 | - Restructure your works so that there's a single clear description of anything you want the AI to know. 791 | If you're unsure then ask the AI for help in clarifying and simplifying things. 792 | - Don't include unless it serves a purpose. 793 | For example, don't include descriptions of things that are purely of historical interest unless you need the 794 | AI to specifically act on them in some way. 795 | 796 | ## Building up the structure 797 | 798 | You've now got a clearer understanding of how Metaphor works, but it can be pretty daunting to start with an almost 799 | empty Metaphor file and try to do something. Metaphor can help you with this too. 800 | 801 | If you imagine starting with just one or two bullet points in the `Context` and an `Action` that says something like: 802 | 803 | ```metaphor 804 | Action: 805 | Please review the requirements and tell me what's unclear, confusing, or ambiguous. 806 | ``` 807 | 808 | When you compile and use this prompt, you're essentially asking your LLM to help you fill in the missing parts. 809 | If it knows 10 ways to do something, this is where it can help you narrow it down to the one you want. 810 | If it doesn't understand some part of what you're trying to achieve, this is where it can ask you to clarify. 811 | 812 | These sorts of meta-conversations are incredibly powerful because they help us to get the AI to ask questions. 813 | Humans do this naturally, but LLMs need nudging. 814 | 815 | If you reach a consensus on what you want in some area, you can also ask the AI to write up some new elements for 816 | the `Context` section. 817 | Once you have enough new context then you can start the process again, but this time starting from the newly expanded 818 | Metaphor prompt. 819 | 820 | The ability to iterate towards a well-structured prompt is one of the great strengths of the Metaphor model because 821 | it allows you to have one or more AIs assist you in assisting them! 822 | 823 | ## One last thing... 824 | 825 | You've now seen how to get started with Metaphor (and Humbug) and how it can be very effective at communicating 826 | your needs to an AI. 827 | 828 | In software development, the norm is to store earlier versions in a revision control system so you can evaluate 829 | earlier versions of the code and see how it evolves. 830 | Metaphor now lets you do the same thing with the prompts that help you use with your AI too. 831 | If you capture the resulting conversations, you get a thorough audit trail of your AI-assisted work too. 832 | 833 | These are all key elements of improving quality and repeatability. 834 | They help us put the "engineering" in "prompt engineering". 835 | 836 | What you might want to think about is what impact this could have for any of your human peers? 837 | 838 | By being very explicit about needs and requirements, you've also started to structure things 839 | in a way that will make them much easier for them to understand too. 840 | 841 | And you thought you were just trying to help your AI! 842 | 843 | ## PS 844 | 845 | You've seen how `m6rc` can compile Metaphor prompts into a format to start a conversation with an AI. 846 | It can also inject command line parameters making it possible to build a Metaphor problem where names of files 847 | or directories can also be added by the compiler. 848 | 849 | This is a "getting started" guide and that's more of an advance topic, but you can find out more about this 850 | in a blog post: [Introducing Metaphor commands](https://m6r.ai/blog/000011-Introducing-Metaphor-commands). 851 | 852 | ## Join us on Discord 853 | 854 | Join us on [Discord](https://discord.gg/GZhJ7ZtgwN) and look for the Metaphor channel to get help or share your ideas. 855 | 856 | -------------------------------------------------------------------------------- /img/api-keys.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/m6r-ai/getting-started-with-metaphor/538db9d85e49d2bd37576a7900bb7dfa28bd99bc/img/api-keys.webp -------------------------------------------------------------------------------- /img/first-conversation-success.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/m6r-ai/getting-started-with-metaphor/538db9d85e49d2bd37576a7900bb7dfa28bd99bc/img/first-conversation-success.webp -------------------------------------------------------------------------------- /img/first-conversation.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/m6r-ai/getting-started-with-metaphor/538db9d85e49d2bd37576a7900bb7dfa28bd99bc/img/first-conversation.webp -------------------------------------------------------------------------------- /img/first-question.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/m6r-ai/getting-started-with-metaphor/538db9d85e49d2bd37576a7900bb7dfa28bd99bc/img/first-question.webp -------------------------------------------------------------------------------- /img/hello-cat.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/m6r-ai/getting-started-with-metaphor/538db9d85e49d2bd37576a7900bb7dfa28bd99bc/img/hello-cat.webp -------------------------------------------------------------------------------- /img/hello-genz.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/m6r-ai/getting-started-with-metaphor/538db9d85e49d2bd37576a7900bb7dfa28bd99bc/img/hello-genz.webp -------------------------------------------------------------------------------- /img/hello-m6r.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/m6r-ai/getting-started-with-metaphor/538db9d85e49d2bd37576a7900bb7dfa28bd99bc/img/hello-m6r.webp -------------------------------------------------------------------------------- /img/hello-toddler.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/m6r-ai/getting-started-with-metaphor/538db9d85e49d2bd37576a7900bb7dfa28bd99bc/img/hello-toddler.webp -------------------------------------------------------------------------------- /img/hello-world.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/m6r-ai/getting-started-with-metaphor/538db9d85e49d2bd37576a7900bb7dfa28bd99bc/img/hello-world.webp -------------------------------------------------------------------------------- /img/new-mindspace.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/m6r-ai/getting-started-with-metaphor/538db9d85e49d2bd37576a7900bb7dfa28bd99bc/img/new-mindspace.webp -------------------------------------------------------------------------------- /img/report-outline.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/m6r-ai/getting-started-with-metaphor/538db9d85e49d2bd37576a7900bb7dfa28bd99bc/img/report-outline.webp -------------------------------------------------------------------------------- /img/start-screen.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/m6r-ai/getting-started-with-metaphor/538db9d85e49d2bd37576a7900bb7dfa28bd99bc/img/start-screen.webp -------------------------------------------------------------------------------- /img/updated-m6r.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/m6r-ai/getting-started-with-metaphor/538db9d85e49d2bd37576a7900bb7dfa28bd99bc/img/updated-m6r.webp --------------------------------------------------------------------------------