The Lectic Conversation Format

Lectic conversations are stored in plain markdown files, typically with a .lec extension. They use a superset of CommonMark, adding two specific conventions: a YAML frontmatter block for configuration and “container directives” for assistant responses.

1. YAML Frontmatter

Every Lectic file begins with a YAML frontmatter block, enclosed by three dashes (---). This is where you configure the conversation, defining the interlocutor(s), their models, prompts, and any tools they might use.

A minimal header looks like this:

---
interlocutor:
  name: Assistant
  prompt: You are a helpful assistant.
  provider: anthropic
  model: claude-3-haiku-20240307
---

The frontmatter can be closed with either three dashes (---) or three periods (...). For a complete guide to all available options, see the Configuration page.

2. User Messages

Anything in the file that is not part of the YAML frontmatter or an assistant response block is considered a user message. You write your prompts, questions, and instructions here as plain text or standard markdown.

This is a user message.

So is this. You can include any markdown you like, such as **bold text** or
`inline code`.

3. Assistant Responses

Lectic uses “container directives” to represent messages from the LLM. These are fenced blocks that start with a run of colons, followed immediately by the name of the interlocutor.

The canonical form is exactly three colons on open and close, like this:

:::Name

Some content.

:::

Markdown code fences inside assistant blocks can also use three backticks.

Inline attachments at the top - Lectic may insert one or more inline attachment blocks at the very start of an assistant block. These are XML chunks beginning with <inline-attachment ...>. They are used to cache computed content from directives like :cmd[...]. - When sending a request to the provider, these attachments are treated as if they were a user message that immediately precedes the assistant’s round.

Example

Here is a complete, simple conversation file showing all the parts together:

---
interlocutor:
  name: Oggle
  prompt: You are a skeptical assistant.
---

I'd like to know more about container directives.

:::Oggle

Are you sure? It seems like a rather niche topic. They are part of a
proposed extension to CommonMark that allows for custom block-level
elements.

Inside one of these blocks, standard markdown is still supported:

```python
# This is a regular code block
print("Hello from inside a directive!")
```

Is that all you wanted to know?

:::

When you run lectic, it reads the entire file, sends the content to the LLM, and then appends the next assistant response in a new directive block.