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.