Prompt Engine JSON Prompt

This page explains how Synthetic Heart builds the structured JSON prompt used by Cortex engines, plugin instances, and downstream LLM integrations.

The JSON prompt is generated by core.prompt_engine.build_json_prompt and is the central contract between SyntH’s runtime and LLM-capable engines.

Overview

The JSON prompt builder performs these major steps:

• Extract the incoming message text and interface metadata.

• Resolve tags and optional memory search results.

• Gather recon contributions and tone/language hints.

• Build the context payload via HistoryEngine.

• Apply static plugin injections and extract persona information.

• Create the input payload and attach media or reply metadata.

• Assemble the final prompt structure with instructions and minified actions.

• Optionally reduce the prompt to fit LLM character limits.

Prompt structure

The resulting JSON prompt is a dictionary with these top-level keys:

• context: message history, memories, recon metadata, and plugin-provided injections.

• input: the current message payload, source metadata, timestamp, and input type.

• instructions: a compact single-line JSON response instruction string.

• actions: a minified action schema block describing allowed response actions.

• instructions_verbose: optional unminified chat instructions for chat-style interfaces.

• __pre_reduction_size: the prompt size before reduction, used for logging and diagnostics.

Input section

The input section includes:

• type: always message for user-driven input.

• interface: the interface_name provided to build_json_prompt.

• payload.text: the raw incoming user message text.

• payload.input_source: voice when the active context marks voice input, otherwise text.

• payload.source: interface metadata including interface_path, message_id, username, usertag, and interface.

• payload.timestamp: the message timestamp in ISO format.

• payload.privacy: currently set to default.

• payload.scope: the effective history scope used for this prompt.

When the message contains additional media or reply context, the builder also adds:

• payload.image: structured image metadata when image data is present.

• payload.attachments: multimodal attachments if provided.

• payload.video: synthesized video metadata for the first video attachment.

• reply_message_id: rich reply metadata for replied-to messages.

Context section

The context section is built by core.history_engine.HistoryEngine.build_context. This includes chat history, memory search results, and any plugin contributions that should be preserved for the current response.

Additional context items may include:

• memories: tag-based recall results from core.synth_core_memory.search_memories.

• recon: language, message tone, and conversation tone hints from recon processing.

• recon_instructions: extra recon-generated instruction strings.

• plugin-provided injections from core.action_parser.gather_static_injections.

For a deeper developer view of how memory search results are gathered and managed, see docs/memory_search_and_management.rst. Persona handling —————-

Persona text is extracted separately from the static injections returned by gather_static_injections().

The builder ensures that:

• persona is removed from context.

• The persona text is prepended to instructions.

This guarantees that the assistant identity is delivered as part of the prompt instructions and not buried in context data.

Recon contributions

Recon contributions are gathered from core.recon.gather_recon_contributions unless the message is an internal G.R.I.L.L.O. beat.

Recon output may add:

• context.recon: structured snippets and metadata.

• context.recon_instructions: extra instruction strings.

• language/tone hints that are prepended into the final instructions string.

Instructions and chat mode

The prompt builder loads the standard JSON instructions using load_json_instructions(). These instructions are kept deliberately compact and single-line for token efficiency.

For chat interfaces, the builder may also add instructions_verbose:

• instructions_verbose is a human-readable, unminified instruction block.

• It is preserved through prompt reduction and later sent as a system message by LLM wrappers and Cortex bridges.

• Chat interface detection is performed dynamically by inspecting available message_* action owners, not by hardcoded interface names.

Actions block

The builder injects actions from core_initializer.actions_block. Actions are minified via minify_actions_block() before being included in the prompt.

Minification rules:

• By default, action schemas are converted into compact prompt-ready format.

• When PROMPT_LITE_MODE is enabled, the builder applies aggressive stripping: - Only essential actions remain. - Detailed schema objects are replaced with brief summaries.

Prompt reduction

If the prompt exceeds allowed LLM character limits, build_json_prompt calls reduce_prompt_for_llm_limit().

Reduction priority:

1. Trim context.history_recent.

2. Trim context.history_current_chat.

3. Remove context.memories entirely.

4. Remove other non-protected context fields.

5. Emergency: remove the entire context section.

Protected data that is never removed:

• instructions

• instructions_verbose (if present)

• persona text embedded in instructions

The reducer excludes attachment base64 data from the size calculation, since LLM engines send multimodal content natively and not as part of the character budget.

Developer notes

Key implementation references:

• core.prompt_engine.build_json_prompt

• core.prompt_engine.reduce_prompt_for_llm_limit

• core.prompt_engine.minify_actions_block

• core.action_parser.gather_static_injections

• core.history_engine.HistoryEngine.build_context

• core.recon.gather_recon_contributions

• core.core_initializer.core_initializer.actions_block

This page is intended for developers who need to understand how SyntH constructs its structured LLM prompt from message input, context memory, and available actions.