Reference: Configuration Keys

This document provides a reference for all the keys available in Lectic’s YAML configuration, including the main .lec file frontmatter and any included configuration files.

Top-Level Keys

  • interlocutor: A single object defining the primary LLM speaker.
  • interlocutors: A list of interlocutor objects for multiparty conversations.
  • kits: A list of named tool kits you can reference from interlocutors.
  • macros: A list of macro definitions. See Macros.
  • hooks: A list of hook definitions. See Hooks.

The interlocutor Object

An interlocutor object defines a single LLM “personality” or configuration.

  • name: (Required) The name of the speaker, used in the :::Name response blocks.
  • prompt: (Required) The base system prompt that defines the LLM’s personality and instructions. The value can be a string, or it can be loaded from a file (file:./path.txt) or a command (exec:get-prompt). See External Prompts for details and examples.
  • hooks: A list of hook definitions. See Hooks. These hooks fire only when this interlocutor is active.

Model Configuration

  • provider: The LLM provider to use. Supported values include anthropic, anthropic/bedrock, openai (Responses API), openai/chat (legacy Chat Completions), gemini, ollama, and openrouter.
  • model: The specific model to use, e.g., claude-3-opus-20240229.
  • temperature: A number between 0 and 1 controlling the randomness of the output.
  • max_tokens: The maximum number of tokens to generate in a response.
  • max_tool_use: The maximum number of tool calls the LLM is allowed to make in a single turn.
  • thinking_effort: Optional hint (used by the openai Responses provider, and by gemini-3-pro) about how much effort to spend reasoning. One of none, low, medium, or high.
  • thinking_budget: Optional integer token budget for providers that support structured thinking phases (Anthropic, Anthropic/Bedrock, Gemini). Ignored by the openai and openai/chat providers.

Providers and defaults

If you don’t specify provider, Lectic picks a default based on your environment. It checks for known API keys in this order and uses the first one it finds:

  1. ANTHROPIC_API_KEY
  2. GEMINI_API_KEY
  3. OPENAI_API_KEY
  4. OPENROUTER_API_KEY

AWS credentials for Bedrock are not considered for auto‑selection. If you want Anthropic via Bedrock, set provider: anthropic/bedrock explicitly and ensure your AWS environment is configured.

OpenAI has two provider options:

  • openai uses the Responses API. You’ll want this for native tools like search and code.
  • openai/chat uses the legacy Chat Completions API. You’ll need this for certain audio workflows that still require chat‑style models.

For a more detailed discussion of provider and model options, see Providers and Models.

Context Management

  • reminder: A string that is invisibly added to the user’s message on every turn. Useful for reinforcing key instructions without cluttering the conversation history.

Tools

  • tools: A list of tool definitions that this interlocutor can use. The format of each object in the list depends on the tool type. See the Tools section for detailed configuration guides for each tool. All tools support a hooks array for tool_use_pre hooks scoped to that particular tool.

MCP tool keys

For tools that connect to Model Context Protocol (MCP) servers, these keys are recognized:

  • One of: mcp_command, mcp_ws, mcp_sse, or mcp_shttp.
  • name: Optional server name used for namespacing and resource scheme.
  • sandbox: Optional wrapper for mcp_command to isolate the server.
  • roots: Optional list of root objects for file access (each with uri and optional name).
  • exclude: Optional list of server tool names to hide.

If you add keys to an interlocutor object that are not listed in this section, Lectic will still parse the YAML, but the LSP marks those properties as unknown with a warning. This is usually a sign of a typo in a key name.

The macro Object

  • name: (Required) The name of the macro, used when invoking it with :macro[name].
  • expansion: (Required) The content to be expanded. Can be a string, or loaded via file: or exec:. See External Prompts for details.

The hook Object

  • on: (Required) A single event name or a list of event names to trigger the hook. Supported events are user_message, assistant_message, error, and tool_use_pre.
  • do: (Required) The command or inline script to run when the event occurs. If multi‑line, it must start with a shebang (e.g., #!/bin/bash). Event context is provided as environment variables. See the Hooks guide for details.
  • inline: (Optional) Boolean. If true, the output of the hook is captured and injected into the conversation. Defaults to false.