# Google AI Studio JSON Architecture & Factory Rules **Target Audience:** Code Custodian & Sidecar Code Monkeys **Purpose:** Defines the strict schema rules for manipulating Google AI Studio chat files without breaking backend Protobuf validation. ## 1. The Core Schema Chat files do NOT have a `.json` extension on disk, but they are strict JSON files representing a conversation. The root structure contains: - `runSettings`: (Dictionary) Model config. - `systemInstruction`: (Dictionary) Contains a `text` key for the system prompt. - `chunkedPrompt`: (Dictionary) The main wrapper. - `chunks`: (Array of Dictionaries) The actual turns of the conversation. - `pendingInputs`: (Array of Dictionaries) Draft inputs. ## 2. Chunk Structure & Protobuf Constraints Every object in the `chunks` array is a turn. **CRITICAL:** Google uses strict Protocol Buffers. You **CANNOT** invent custom keys at the root of a chunk. ### User Turns (Text) ```json { "text": "Hello world", "role": "user", "tokenCount": 2, "createTime": "2026-06-16T14:09:19.406Z" } ``` ### Model Turns (Text & Typing Effects) Model turns often contain a `"finishReason": "STOP"` key and a bloated `parts` array used to render the typing effect in the UI. ```json { "text": "The complete response text goes here.", "role": "model", "finishReason": "STOP", "tokenCount": 320, "parts": [ { "text": "The complete" }, { "text": " response text goes here." }, { "text": "", "thoughtSignature": "ErUgC... << BASE64 >> ...GTs" } ], "createTime": "2026-06-17T04:35:05.114Z" } ``` **RULE FOR MODEL PARTS:** We do not need the typing effect snippets. The ONLY dictionary we care about inside a model's `parts` array is the one containing `"thoughtSignature"`. All other typing dictionaries should be deleted to save tokens. ## 3. Metadata Smuggling (The `parts` Array) To store custom metadata (like unique Turn IDs or local image cache paths) without breaking the schema, we smuggle our metadata using string values inside `"text"` keys within the `parts` array of **User Turns**. **Example of a properly tagged User Turn:** ```json { "text": "[TURN_0145]\nActual message...", "role": "user", "tokenCount": 12, "parts": [ { "text": "turn_id: [TURN_0145]" }, { "text": "tx_id: [TX_ID: TX_P6VJ3H55]" }, { "text": "cache_file: chat_img_Mike 12.0_TX_P6VJ3H55_0.dat" } ] } ``` ## 4. Model "Thoughts" & Signatures - Any chunk with `"isThought": true` is UI fluff. **We delete these entirely.** - Model text chunks have a `parts` array containing a `"thoughtSignature"`. - **RULE:** We retain the `"thoughtSignature"` part for the **5 most recent** model chunks. Older thought signatures must be deleted. ## 5. Image Handling & The "Necromancer" Protocol Images appear as separate chunks preceding a text chunk. - **`driveImage`**: Reference to Drive upload (e.g., `{"driveImage": {"id": "1wC8..."}}`). *These IDs expire.* - **`inlineImage`**: Raw base64 string. **The Necromancer Protocol (Image Resurrection):** Because `driveImage` IDs expire, our system relies on local `.dat` files stored on an SSD. If an image chunk is missing/expired, the Janitor must: 1. Detect a `TX_ID` associated with the current text chunk. 2. Scan the SSD (`FactoryPaths.imageCache`) for files matching `chat_img___*.dat`. 3. Read the data, determine the mime type, convert to base64, and dynamically insert brand new `inlineImage` chunks into the JSON sequence *before* the text chunk.