Core Concepts

August 9, 2026 · View on GitHub

English | 中文

Core Concepts

LLM Space is a desktop workbench for developing, debugging, and evaluating prompts and agents. You can think of a Thread as a saved experiment file: it records the conversation context, the selected model, available tools, and the messages and tool call results produced during a run.

Thread

A Thread is the basic unit of work in LLM Space. A Thread usually contains:

Title: shown in the file tree and tab bar.
Model: the default model used when this Thread runs.
System Prompt: global instructions sent to the model.
Variables: placeholders that can be referenced in the System Prompt, messages, and tool results.
Tools: tool definitions the model can call.
Messages: the conversation history made of User and Assistant messages.
Tool Calls: tool call requests and results recorded on Assistant messages.
Run History: historical run snapshots for replay, comparison, and debugging.
Evaluations: manual evaluation records for comparing different runs.

In the UI, creating, opening, copying, moving, and deleting Threads is essentially managing Thread files in the workspace.

You can also publish a read-only copy with Sharing Threads, or turn the Thread into an editable agent codebase with Generating Projects.

Evaluation Rubrics

Run History lets you select two durable runs and compare their saved evidence. You can keep the simple overall verdict and note workflow, or select a reusable rubric owned by the current Thread.

A rubric contains 2–6 ordered criteria. Each criterion has a name and optional description, and each compared run receives a score from 1 (poor) to 5 (excellent). LLM Space derives the unweighted average for Run A and Run B plus the B - A delta; the overall verdict remains a separate human decision.

Saved evaluations contain an immutable snapshot of the rubric and scores keyed by stable run ID. Editing or deleting the reusable rubric definition does not rewrite historical evaluations. Rubrics, snapshots, scores, verdicts, and notes stay in the local Thread JSON and do not trigger another model call.

Model

A Model is the language model actually called during a run, such as a model ID under OpenAI, Anthropic, Ark, or a custom compatible API.

A Thread can save its own model configuration:

Field	Meaning
`provider`	Model provider ID.
`id`	Model ID.
`params.maxTokens`	Maximum number of tokens the run can generate.
`params.temperature`	Sampling temperature.
`params.reasoning`	Reasoning level or effort, depending on model support.
`params.responseType`	Response type, such as plain text or structured output.
`params.extra`	Extra parameters passed to a specific model.

If a Thread does not save a model, the UI falls back to the currently available model for display and running. Once you manually select a model, that model configuration is saved with the Thread.

Model Provider

A Model Provider is a provider configuration. It tells LLM Space where to call models, which API compatibility mode to use, which API key to use, and which models are available.

Common Provider information includes:

Configuration	Description
Provider name and ID	Used to identify the provider in model selectors and config files.
API Key	The key required to call this provider's models.
Base URL	Custom API endpoint. Leave empty to use the default endpoint.
API compatibility mode	For example Anthropic Messages, OpenAI Chat Completions, or OpenAI Responses.
Models	Models available under this Provider.
Disabled Models	Models hidden or disabled by the user.
Custom Models	Model IDs manually added by the user.

Model Provider is a global setting. Model is the concrete runtime model selected by a specific Thread.

Tools

Tools are capabilities the model can request to call. Tool definitions are sent to the model, and the model decides whether to call them based on their names, descriptions, and parameter schemas.

LLM Space has three main types of tools:

Type	Description	Result source
Built-in	Capabilities implemented by the app runtime, such as files, commands, and web search. Their definitions follow common agent implementation patterns.	Implemented inside LLM Space. The app can run them automatically, or the user can trigger them when confirmation is needed.
Custom Function Tool	User-defined function tool definitions. They describe the tool name, purpose, and parameters, but do not have a built-in execution backend.	The user fills the result manually, or an external workflow supplies it.
MCP	Tools from an MCP Server. After LLM Space connects to an MCP Server, it exposes server-provided tools to the model.	Executed by the corresponding MCP Server.

A tool usually contains:

Field	Meaning
`type`	`builtin`, `function`, or `mcp`.
`name`	Tool name exposed to the model.
`description`	Tells the model when to use this tool.
`parameters`	JSON Schema describing tool parameters.

MCP tools also save which MCP Server they come from, such as serverId, serverName, and the raw toolName.

System Prompt

The System Prompt is the Thread's global instruction. It is usually used to define the assistant's identity, goals, constraints, output format, and tool usage policy.

The System Prompt is not shown as a normal user message, but it is sent to the model as part of the context. Compared with repeating rules in every user message, putting stable behavior requirements in the System Prompt is easier to reuse and compare.

Variables

Variables are placeholders you can reuse in the System Prompt, messages, and tool results. You write {{variable_name}} in the text, and at run time LLM Space replaces it with the variable's real value. This lets you pull out content that changes or is reused (the current date, the list of available skills, common snippets, and so on) and manage it in one place instead of hand-writing and maintaining it in many spots.

The reference syntax is always double curly braces, for example {{current_date}}. There are two kinds of variables: built-in and custom.

Built-in Variables

Built-in variables compute their value automatically from the current environment or configuration. You only reference them; you don't fill in a value:

Variable	Description	Options
`current_date`	The current system date and time, in the local time zone.	Format: readable date, ISO date, or local date and time.
`available_skills`	The list of currently enabled Skills (names and descriptions), so the model knows what capabilities are available.	Format: Markdown list or XML; indentation; includes all enabled Skills by default, or you can pick only some.

available_skills expands to all enabled Skills by default. If you only want to expose a subset, select specific Skills in the variable settings; an empty selection means "all enabled Skills."

Custom Variables

A custom variable is a "name → value" pair you define manually, where the value is a fixed piece of text. It suits snippets you reuse in multiple places, such as a shared tone-of-voice note, company information, or common constraints. Once defined, you reference it with {{variable_name}} as well.

A variable name must start with a letter or underscore and contain only letters, digits, and underscores.

Resolution and Storage

At run time, {{variable_name}} in the text is replaced with the variable's current value, while the stored Thread template stays unchanged.
Built-in variable definitions are stored under context.variables, and custom variable values are stored under context.variableVariants.
If you reference a variable that doesn't exist or has an empty value, the UI shows a hint.

Beyond plain substitution, you can also add logic — file includes (@include), conditionals, and loops. See Variables and Templates for the template language.

Messages

Messages are the conversation history of a Thread. LLM Space currently uses two main message roles:

Role	Description	Content
User	Messages entered by the user.	Text, and optionally image data.
Assistant	Messages generated by the model.	Text, reasoning, tool calls, and token usage.

User message content can be:

Text: { "type": "text", "text": "..." }
Image data: { "type": "image", "mimeType": "image/png", "data": "..." }

Assistant message content is mainly text, and may also include:

thinking: reasoning or thinking content returned by the model, depending on provider support.
toolCalls: records of tool calls requested by the model.
usage: token usage returned by the model provider.

When a Thread becomes long, Conversation Compaction can replace older turns with a structured checkpoint while keeping recent turns unchanged. Compaction is previewed first and applied to a new Thread file, so the source conversation remains available.

Tool Calls

A Tool Call is a tool invocation recorded on an Assistant message. It means the model decided to call a tool and supplied arguments.

A Tool Call usually contains:

Field	Meaning
`id`	Tool call ID, used to match request and result.
`input.name`	Tool name to call.
`input.arguments`	Tool argument object.
`input.partialArguments`	Raw argument text that could not be fully parsed, usually kept for debugging.
`output.content`	Text returned by the tool.
`output.isError`	Whether the tool runtime reported an error.

Tool call results are saved in the Thread, so you can inspect why the model called a tool, what arguments it used, and what the tool returned.

File Storage

LLM Space is a desktop app, and user data is stored locally. The default root directory is:

~/.llm-space

You can override it with an environment variable:

LLM_SPACE_HOME=/path/to/data

Common directories:

Path	Content
`workspace/`	Thread files.
`settings/models.json`	Model Provider and model settings.
`settings/mcp.json`	MCP Server settings.
`settings/window.json`	Desktop window state.
`settings/skills.json`	Skill discovery settings.
`traces/`	Trace and debugging workbench data.

Thread files are stored in:

~/.llm-space/workspace/

Subdirectories in the workspace map to the file tree on the left side of the app. Thread files use the .json extension. The file name is the source of the title shown in the UI; when saving, the app keeps the Thread title aligned with the file name.

Thread JSON Format

A native Thread file is formatted JSON. The core structure looks like this:

{
  "title": "core-concepts",
  "model": {
    "provider": "openai",
    "id": "gpt-4.1",
    "params": {
      "temperature": 0.7,
      "maxTokens": 4096
    }
  },
  "context": {
    "systemPrompt": "You are a helpful assistant.",
    "tools": [
      {
        "type": "function",
        "name": "lookup_order",
        "description": "Look up an order by ID.",
        "parameters": {
          "type": "object",
          "properties": {
            "orderId": {
              "type": "string"
            }
          },
          "required": ["orderId"]
        }
      }
    ],
    "messages": [
      {
        "id": "msg_1",
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Look up order A123 for me."
          }
        ]
      },
      {
        "id": "msg_2",
        "role": "assistant",
        "content": [
          {
            "type": "text",
            "text": "I will look it up."
          }
        ],
        "toolCalls": [
          {
            "id": "call_1",
            "input": {
              "name": "lookup_order",
              "arguments": {
                "orderId": "A123"
              }
            },
            "output": {
              "content": [
                {
                  "type": "text",
                  "text": "Order A123 has shipped."
                }
              ]
            }
          }
        ]
      }
    ]
  }
}

Actual files may also contain runHistory, evaluationRubrics, and evaluations. These fields are mainly used for debugging, replay, and manual evaluation, and are usually maintained by the app automatically. Rubric-backed evaluations store their own rubric snapshot so later definition changes do not alter historical results.

Supported Import Schemas

The import entry point selects parsers by file extension. .json and .jsonl are supported. LLM Space attempts to recognize and normalize the following formats:

Format	Description
Native Thread JSON	JSON that already matches the LLM Space Thread structure.
OpenAI Chat Completions-style JSON	Chat exports containing fields such as `messages`, `role`, `content`, and `tool_calls`.
Anthropic Messages-style JSON	Chat exports containing fields such as `system`, `messages`, content blocks, `tool_use`, `tool_result`, and `input_schema`.
Aurora-style JSON	Aurora Thread exports containing `Messages` and `Tools`.
DeerFlow run-event JSONL	Persisted run events containing human, assistant, and tool messages.

After import, external formats are converted to the LLM Space Thread structure and written as new .json files under the current workspace directory. Files that cannot produce messages, System Prompt, Tools, or model information are skipped.