AiContextGenerationJobReadSchema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/getoneprofile-ai/json-schema/getoneprofile-ai-ai-context-generation-job-read-schema-schema.json",
  "title": "AiContextGenerationJobReadSchema",
  "description": "A generation job's current state. Poll this until `status` is terminal.",
  "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/AiContextGenerationJobReadSchema",
  "properties": {
    "created_at": {
      "format": "date-time",
      "title": "Created At",
      "type": "string"
    },
    "domain": {
      "description": "The domain this job is researching.",
      "title": "Domain",
      "type": "string"
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Why generation failed: infra trouble, or too little public content.",
      "title": "Error"
    },
    "id": {
      "format": "uuid",
      "title": "Id",
      "type": "string"
    },
    "status": {
      "$ref": "#/$defs/AiContextGenerationStatus"
    },
    "steps": {
      "description": "What the research did, one step per piece of work once it is done: the documents and pages it read, the sections it wrote. Grows while the job runs; kept once it finishes.",
      "items": {
        "$ref": "#/$defs/AiStep"
      },
      "maxItems": 40,
      "title": "Steps",
      "type": "array"
    },
    "updated_at": {
      "format": "date-time",
      "title": "Updated At",
      "type": "string"
    }
  },
  "required": [
    "id",
    "domain",
    "status",
    "error",
    "created_at",
    "updated_at"
  ],
  "type": "object",
  "$defs": {
    "AiContextGenerationStatus": {
      "description": "Where a context-generation job has got to.\n\nJobs are stored ``PENDING``: committed, with the workflow that will work on\nthem not yet started, which a crash between the two can leave for ever. The\nresearch's first step claims the job (``RUNNING``), and the deadline sweep\nfails one nothing ever claimed. A reader never sees ``PENDING``: to everyone\noutside the repository a job waiting for its workflow is already running.\nThe two terminal states are absorbing: a job never leaves them.",
      "enum": [
        "pending",
        "running",
        "succeeded",
        "failed"
      ],
      "title": "AiContextGenerationStatus",
      "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"
    }
  }
}