{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/foresea-ink/json-schema/foresea-ink-predict-response-schema.json",
  "title": "PredictResponse",
  "description": "Prediction result for a single forecasting question.",
  "x-generated": "2026-11-08",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/foresea-ink-openapi.json#/components/schemas/PredictResponse",
  "properties": {
    "question_type": {
      "type": "string",
      "title": "Question Type",
      "description": "Detected type: `binary`, `multiple_choice`, `numeric`, or `date`.",
      "default": "binary"
    },
    "predicted_answer": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Predicted Answer",
      "description": "Headline answer: Yes/No, the top option, or the median estimate."
    },
    "confidence": {
      "anyOf": [
        {
          "type": "number",
          "maximum": 1.0,
          "minimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Confidence",
      "description": "Confidence in the headline answer (binary/MC). Null for numeric."
    },
    "model_probability": {
      "anyOf": [
        {
          "type": "number",
          "maximum": 1.0,
          "minimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Model Probability",
      "description": "Explicit model probability for conversational forecasts, when one was provided."
    },
    "options": {
      "items": {
        "$ref": "#/$defs/OptionProb"
      },
      "type": "array",
      "title": "Options",
      "description": "Per-option probabilities for `multiple_choice`."
    },
    "range_forecast": {
      "anyOf": [
        {
          "$ref": "#/$defs/RangeForecast"
        },
        {
          "type": "null"
        }
      ],
      "description": "p10/p50/p90 estimate for `numeric` and `date`."
    },
    "rationale": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Rationale",
      "description": "2–4 sentence explanation of the prediction."
    },
    "model_rationale": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Model Rationale",
      "description": "Raw rationale as returned by the model (may differ from `rationale` after post-processing)."
    },
    "variant": {
      "type": "string",
      "title": "Variant",
      "description": "Prompt variant used for this prediction."
    },
    "model_key": {
      "type": "string",
      "title": "Model Key",
      "description": "Model identifier (e.g. `gpt-oss-120b`)."
    },
    "served_model_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Served Model Name",
      "description": "Exact upstream model name that served the response, if reported by the provider."
    },
    "evidence_sources": {
      "items": {
        "$ref": "#/$defs/EvidenceSource"
      },
      "type": "array",
      "title": "Evidence Sources",
      "description": "Deduplicated citations used as evidence."
    },
    "evidence_articles": {
      "items": {
        "$ref": "#/$defs/NewsArticle"
      },
      "type": "array",
      "title": "Evidence Articles",
      "description": "Full evidence articles passed to the model."
    },
    "evidence_error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Evidence Error",
      "description": "Non-null if evidence retrieval failed (prediction still returned)."
    },
    "market_analysis": {
      "anyOf": [
        {
          "$ref": "#/$defs/MarketAnalysis"
        },
        {
          "type": "null"
        }
      ],
      "description": "Optional comparison against a supplied prediction-market probability."
    },
    "complexity": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Complexity",
      "description": "Model's own self-reported difficulty for this question: `low` or `high`."
    },
    "bull_factors": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Bull Factors",
      "description": "Decomposed factors favoring the YES / upside outcome."
    },
    "bear_factors": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Bear Factors",
      "description": "Decomposed counter-factors favoring the NO / downside outcome."
    },
    "key_catalysts": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Key Catalysts",
      "description": "Key upcoming events/dates that could trigger thesis revision."
    }
  },
  "type": "object",
  "required": [
    "variant",
    "model_key"
  ],
  "$defs": {
    "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."
    },
    "MarketAnalysis": {
      "properties": {
        "platform": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Platform",
          "description": "Prediction market venue supplied by the caller."
        },
        "market_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Market Url",
          "description": "Prediction market URL supplied by the caller."
        },
        "outcome": {
          "type": "string",
          "title": "Outcome",
          "description": "Outcome being compared against the market price."
        },
        "market_probability": {
          "type": "number",
          "maximum": 1.0,
          "minimum": 0.0,
          "title": "Market Probability",
          "description": "Market-implied probability for the outcome."
        },
        "model_probability": {
          "anyOf": [
            {
              "type": "number",
              "maximum": 1.0,
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Model Probability",
          "description": "Foresea probability for the same outcome (recalibrated from the live track record when warranted)."
        },
        "model_probability_raw": {
          "anyOf": [
            {
              "type": "number",
              "maximum": 1.0,
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Model Probability Raw",
          "description": "Raw model probability before live calibration (only set when calibration was applied)."
        },
        "edge": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Edge",
          "description": "Model probability minus market probability."
        },
        "stance": {
          "type": "string",
          "title": "Stance",
          "description": "`model_above_market`, `model_below_market`, `in_line`, or `not_comparable`."
        },
        "summary": {
          "type": "string",
          "title": "Summary",
          "description": "Short human-readable market comparison."
        }
      },
      "type": "object",
      "required": [
        "outcome",
        "market_probability",
        "stance",
        "summary"
      ],
      "title": "MarketAnalysis",
      "description": "Deterministic comparison between Foresea's forecast and a market price."
    },
    "NewsArticle": {
      "properties": {
        "title": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 500
            },
            {
              "type": "null"
            }
          ],
          "title": "Title",
          "description": "Article headline."
        },
        "summary": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 4000
            },
            {
              "type": "null"
            }
          ],
          "title": "Summary",
          "description": "Short human-written summary."
        },
        "summary_llm": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 4000
            },
            {
              "type": "null"
            }
          ],
          "title": "Summary Llm",
          "description": "LLM-generated summary."
        },
        "text": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 20000
            },
            {
              "type": "null"
            }
          ],
          "title": "Text",
          "description": "Full article body text."
        },
        "source": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 200
            },
            {
              "type": "null"
            }
          ],
          "title": "Source",
          "description": "Publisher name (e.g. Reuters)."
        },
        "credibility": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "title": "Credibility",
          "description": "Credibility score breakdown."
        },
        "frs": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "title": "Frs",
          "description": "Future-Resolution Statement metadata."
        },
        "url": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 2000
            },
            {
              "type": "null"
            }
          ],
          "title": "Url",
          "description": "Canonical article URL."
        },
        "authors": {
          "anyOf": [
            {},
            {
              "type": "null"
            }
          ],
          "title": "Authors",
          "description": "Author name(s)."
        },
        "publish_date": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 100
            },
            {
              "type": "null"
            }
          ],
          "title": "Publish Date",
          "description": "ISO 8601 publish timestamp."
        },
        "keywords": {
          "anyOf": [
            {},
            {
              "type": "null"
            }
          ],
          "title": "Keywords",
          "description": "Extracted keywords."
        },
        "relevance_score": {
          "anyOf": [
            {
              "type": "number",
              "maximum": 1.0,
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Relevance Score",
          "description": "Cosine similarity to the question (0–1)."
        },
        "search_query": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 500
            },
            {
              "type": "null"
            }
          ],
          "title": "Search Query",
          "description": "Query used to retrieve this article."
        }
      },
      "type": "object",
      "title": "NewsArticle",
      "description": "A news article passed as evidence context for the prediction."
    },
    "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."
    },
    "RangeForecast": {
      "properties": {
        "p10": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "P10",
          "description": "10th-percentile (low) estimate."
        },
        "p50": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "P50",
          "description": "50th-percentile (median) estimate."
        },
        "p90": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "P90",
          "description": "90th-percentile (high) estimate."
        },
        "unit": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Unit",
          "description": "Unit of the estimate, e.g. 'USD', '%', 'people'."
        }
      },
      "type": "object",
      "title": "RangeForecast",
      "description": "A numeric or date estimate expressed as percentile bounds."
    }
  }
}