AiContextDocumentReadSchema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/getoneprofile-ai/json-schema/getoneprofile-ai-ai-context-document-read-schema-schema.json",
  "title": "AiContextDocumentReadSchema",
  "description": "One reference document: what it is, how far it got, and what prompts read.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/getoneprofile-ai-ai-context-api-openapi.yml#/components/schemas/AiContextDocumentReadSchema",
  "properties": {
    "content_type": {
      "title": "Content Type",
      "type": "string"
    },
    "created_at": {
      "format": "date-time",
      "title": "Created At",
      "type": "string"
    },
    "drive_file_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Drive File Id"
    },
    "drive_web_view_link": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Where to open the original in Google Drive, for linked documents.",
      "title": "Drive Web View Link"
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Why the document could not be read, written for the reader.",
      "title": "Error"
    },
    "filename": {
      "title": "Filename",
      "type": "string"
    },
    "id": {
      "format": "uuid",
      "title": "Id",
      "type": "string"
    },
    "in_prompt_budget": {
      "default": true,
      "description": "Whether this document's summary actually fits the prompt budget alongside the documents before it. Computed on the list; a single read reports true.",
      "title": "In Prompt Budget",
      "type": "boolean"
    },
    "included_in_context": {
      "description": "Whether this document's summary joins the business context.",
      "title": "Included In Context",
      "type": "boolean"
    },
    "size_bytes": {
      "title": "Size Bytes",
      "type": "integer"
    },
    "source": {
      "$ref": "#/$defs/AiContextDocumentSource",
      "description": "Whether the file was uploaded or linked from Google Drive."
    },
    "status": {
      "$ref": "#/$defs/AiContextDocumentStatus",
      "description": "Poll the list while any document is still `processing`."
    },
    "steps": {
      "description": "What the last read did, one step per piece of work once it is done: the document read, the summary written. Grows while the document is `processing`; starts empty again when it is read again.",
      "items": {
        "$ref": "#/$defs/AiStep"
      },
      "maxItems": 40,
      "title": "Steps",
      "type": "array"
    },
    "summary": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "The markdown summary that stands in for this document in AI prompts.",
      "title": "Summary"
    },
    "summary_edited": {
      "description": "True once somebody saved over the written summary by hand.",
      "title": "Summary Edited",
      "type": "boolean"
    },
    "summary_generated_at": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Summary Generated At"
    },
    "title": {
      "title": "Title",
      "type": "string"
    },
    "updated_at": {
      "format": "date-time",
      "title": "Updated At",
      "type": "string"
    }
  },
  "required": [
    "id",
    "source",
    "status",
    "error",
    "title",
    "filename",
    "content_type",
    "size_bytes",
    "summary",
    "summary_edited",
    "summary_generated_at",
    "included_in_context",
    "drive_file_id",
    "drive_web_view_link",
    "created_at",
    "updated_at"
  ],
  "type": "object",
  "$defs": {
    "AiContextDocumentSource": {
      "description": "Where a reference document came from.",
      "enum": [
        "upload",
        "google_drive"
      ],
      "title": "AiContextDocumentSource",
      "type": "string"
    },
    "AiContextDocumentStatus": {
      "description": "How far a reference document has got through extraction and summarizing.\n\nUnlike a generation job, ``PENDING`` IS observed here: the row commits\nfirst and its workflow starts after that commit, so a reader can catch the\ngap. The two terminal states are absorbing.",
      "enum": [
        "pending",
        "processing",
        "ready",
        "failed"
      ],
      "title": "AiContextDocumentStatus",
      "type": "string"
    },
    "AiStep": {
      "additionalProperties": false,
      "description": "One thing an AI turn did, as the wire spells it.\n\nField-for-field identical to ``table_live_updates.TableCellActivityStepSchema``\nON PURPOSE, and the duplication is the design. That schema sits in the table\nstratum's kernel, which the lead search, inbox and sequence surfaces have no\nbusiness importing; this one sits under every surface equally. Because the\ntwo agree exactly, the frontend's ``TimelineStep`` renders both with no\nconversion and no second component, which is the property worth protecting.\n``test_ai_step_mirrors_the_cell_activity_step`` pins them together.\n\nPlain strings rather than enums, for the same reason the cell schema uses\nthem: the vocabulary is open, clients must tolerate tokens they have not\nlearned yet, and a new action should never be able to break a running\ndashboard.",
      "properties": {
        "action": {
          "description": "What kind of move this was, e.g. `read_table`, `plan`, `write_column`.",
          "title": "Action",
          "type": "string"
        },
        "detail": {
          "default": "",
          "description": "The step's input: the instruction, the column it read, the query it ran.",
          "title": "Detail",
          "type": "string"
        },
        "duration_ms": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "description": "Wall clock for the work this step describes, never an estimate.",
          "title": "Duration Ms"
        },
        "observation": {
          "default": "",
          "description": "One line on what came back. The half that makes a step worth reading.",
          "maxLength": 500,
          "title": "Observation",
          "type": "string"
        },
        "outcome": {
          "default": "completed",
          "description": "`completed`, `failed`, `refused` or `stopped`. Clients must tolerate new tokens.",
          "title": "Outcome",
          "type": "string"
        },
        "thought": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "The model's stated reasoning for choosing this step. Set by the agent loop; the assistant surfaces leave it null, and the renderer simply omits the rung.",
          "title": "Thought"
        }
      },
      "required": [
        "action"
      ],
      "title": "AiStep",
      "type": "object"
    }
  }
}