AgentReport

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/foresea-ink/json-schema/foresea-ink-agent-report-schema.json",
  "title": "AgentReport",
  "description": "End-to-end analysis of a live question produced by the agent.",
  "x-generated": "2026-11-08",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/foresea-ink-openapi.json#/components/schemas/AgentReport",
  "properties": {
    "question": {
      "type": "string",
      "title": "Question"
    },
    "options": {
      "items": {
        "$ref": "#/$defs/OptionProb"
      },
      "type": "array",
      "title": "Options",
      "description": "Per-option forecasts, for an event link with several options."
    },
    "served_model_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Served Model Name",
      "description": "Exact upstream model that served the final agent response, when reported by the provider."
    },
    "pipeline": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "Pipeline",
      "description": "Ordered steps the agent ran."
    },
    "platform": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Platform"
    },
    "market_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Market Url"
    },
    "outcome": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Outcome"
    },
    "market_probability": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Market Probability"
    },
    "model_probability": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Model Probability"
    },
    "edge": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Edge"
    },
    "stance": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Stance"
    },
    "recommendation": {
      "type": "string",
      "title": "Recommendation",
      "description": "`buy_yes`, `buy_no`, `hold`, or `no_market_price`."
    },
    "recommendation_detail": {
      "type": "string",
      "title": "Recommendation Detail",
      "default": ""
    },
    "confidence": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Confidence"
    },
    "question_type": {
      "type": "string",
      "title": "Question Type",
      "default": "binary"
    },
    "thesis": {
      "type": "string",
      "title": "Thesis",
      "default": ""
    },
    "evidence_sources": {
      "items": {
        "$ref": "#/$defs/EvidenceSource"
      },
      "type": "array",
      "title": "Evidence Sources"
    },
    "evidence_error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Evidence Error"
    },
    "skills": {
      "items": {
        "$ref": "#/$defs/AgentSkillResult"
      },
      "type": "array",
      "title": "Skills"
    },
    "grounding": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Grounding",
      "description": "Track-record self-calibration note applied to the forecast."
    },
    "effort_tier": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Effort Tier",
      "description": "How much analysis effort this question got: simple, standard, or deep."
    },
    "tool_transcript": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "type": "array",
      "title": "Tool Transcript",
      "description": "Tool calls + observations when the tool loop ran."
    },
    "tool_loop_steps": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Tool Loop Steps",
      "description": "Tool-call steps the loop actually ran, when tool_loop=true."
    },
    "tool_loop_model_calls": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Tool Loop Model Calls",
      "description": "Logical orchestration turns, including finalization; excludes provider retries and nested tools."
    },
    "tool_loop_truncated": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Tool Loop Truncated",
      "description": "True if the loop hit max_tool_steps without the model giving a final answer."
    },
    "tool_loop_tokens_used": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Tool Loop Tokens Used",
      "description": "Total estimated tokens consumed across turns."
    },
    "tool_loop_output_tokens_used": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Tool Loop Output Tokens Used",
      "description": "Estimated completion/output tokens consumed in the tool loop."
    },
    "agent_profile": {
      "anyOf": [
        {
          "$ref": "#/$defs/AgentProfileReference"
        },
        {
          "type": "null"
        }
      ],
      "description": "Immutable private research recipe used for this report, when one was selected."
    },
    "live_trade_intent": {
      "anyOf": [
        {
          "$ref": "#/$defs/LiveTradeIntent"
        },
        {
          "type": "null"
        }
      ],
      "description": "A non-executable research handoff for the authenticated user's live trade terminal."
    },
    "agent_run": {
      "anyOf": [
        {
          "$ref": "#/$defs/AgentRunReference"
        },
        {
          "type": "null"
        }
      ],
      "description": "Private durable run record for this signed-in user's agent research."
    }
  },
  "type": "object",
  "required": [
    "question",
    "recommendation"
  ],
  "$defs": {
    "AgentProfileReference": {
      "properties": {
        "id": {
          "type": "string",
          "title": "Id"
        },
        "source_agent_id": {
          "type": "string",
          "title": "Source Agent Id"
        },
        "model": {
          "type": "string",
          "title": "Model"
        },
        "version": {
          "type": "integer",
          "minimum": 1.0,
          "title": "Version"
        },
        "execution_mode": {
          "type": "string",
          "const": "research_only",
          "title": "Execution Mode"
        }
      },
      "type": "object",
      "required": [
        "id",
        "source_agent_id",
        "model",
        "version",
        "execution_mode"
      ],
      "title": "AgentProfileReference",
      "description": "The profile snapshot that shaped one agent report, without private context."
    },
    "AgentRunReference": {
      "properties": {
        "id": {
          "type": "string",
          "title": "Id"
        },
        "status": {
          "type": "string",
          "enum": [
            "running",
            "completed",
            "failed",
            "interrupted"
          ],
          "title": "Status"
        },
        "created_at": {
          "type": "string",
          "title": "Created At"
        },
        "updated_at": {
          "type": "string",
          "title": "Updated At"
        }
      },
      "type": "object",
      "required": [
        "id",
        "status",
        "created_at",
        "updated_at"
      ],
      "title": "AgentRunReference",
      "description": "The durable, private research run that produced an agent report."
    },
    "AgentSkillResult": {
      "properties": {
        "name": {
          "type": "string",
          "title": "Name"
        },
        "output": {
          "type": "string",
          "title": "Output"
        },
        "verdict": {
          "anyOf": [
            {
              "$ref": "#/$defs/RedTeamVerdict"
            },
            {
              "type": "null"
            }
          ],
          "description": "Structured classification of this skill's own argument, when available (Red team only, best-effort)."
        }
      },
      "type": "object",
      "required": [
        "name",
        "output"
      ],
      "title": "AgentSkillResult"
    },
    "EvidenceSource": {
      "properties": {
        "source": {
          "type": "string",
          "title": "Source",
          "description": "Publisher name."
        },
        "title": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Title",
          "description": "Article headline."
        },
        "url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Url",
          "description": "Article URL."
        },
        "publish_date": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Publish Date",
          "description": "ISO 8601 publish date."
        },
        "relevance_score": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Relevance Score",
          "description": "Relevance to the question (0–1)."
        }
      },
      "type": "object",
      "required": [
        "source"
      ],
      "title": "EvidenceSource",
      "description": "A deduplicated citation drawn from the evidence articles."
    },
    "LiveTradeIntent": {
      "properties": {
        "platform": {
          "type": "string",
          "title": "Platform"
        },
        "ident": {
          "type": "string",
          "title": "Ident"
        },
        "action": {
          "type": "string",
          "title": "Action",
          "default": "buy"
        },
        "outcome": {
          "type": "string",
          "title": "Outcome"
        },
        "market_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Market Url"
        },
        "model_probability": {
          "type": "number",
          "title": "Model Probability"
        },
        "market_probability": {
          "type": "number",
          "title": "Market Probability"
        },
        "edge": {
          "type": "number",
          "title": "Edge"
        },
        "recommendation": {
          "type": "string",
          "title": "Recommendation"
        }
      },
      "type": "object",
      "required": [
        "platform",
        "ident",
        "outcome",
        "model_probability",
        "market_probability",
        "edge",
        "recommendation"
      ],
      "title": "LiveTradeIntent",
      "description": "A chat-to-terminal handoff for a human-reviewed live order.\n\nThis is deliberately not an executable order: it contains no size or limit\nprice, and the trading terminal must still fetch a fresh venue quote, create\na durable `/trading/runs` record, and receive an explicit user confirmation\nbefore an exchange order can be submitted."
    },
    "OptionProb": {
      "properties": {
        "label": {
          "type": "string",
          "title": "Label",
          "description": "The option text."
        },
        "probability": {
          "type": "number",
          "maximum": 1.0,
          "minimum": 0.0,
          "title": "Probability",
          "description": "Probability assigned to this option (0–1)."
        }
      },
      "type": "object",
      "required": [
        "label",
        "probability"
      ],
      "title": "OptionProb",
      "description": "A single option and its probability in a multiple-choice forecast."
    },
    "RedTeamVerdict": {
      "properties": {
        "credible": {
          "type": "boolean",
          "title": "Credible",
          "description": "Whether the argument is well-supported by a real mechanism or evidence, not just contrarian restating."
        },
        "severity": {
          "type": "string",
          "enum": [
            "low",
            "medium",
            "high"
          ],
          "title": "Severity",
          "description": "How much this argument should weigh against the forecast if credible."
        }
      },
      "type": "object",
      "required": [
        "credible",
        "severity"
      ],
      "title": "RedTeamVerdict",
      "description": "Structured classification of a Red team skill's own argument, from a\nseparate follow-up call. Observational only -- nothing in the pipeline\nreads this to gate or adjust the forecast."
    }
  }
}