---
title: "ai.research@1 · OpenVibe.Services"
canonical: "https://openvibe.services/docs/contracts/ai.research"
updated: null
---

# ai.research@1 · OpenVibe.Services

HTML: [ai.research@1 · OpenVibe.Services](https://openvibe.services/docs/contracts/ai.research)

# AiResearch `ai.research@1`

Generated at 2026-11-17 06:52:56 UTC from [`openvibe-contracts v0.443.0`](https://github.com/OpenVibers/OpenVibe.Contracts/tree/v0.443.0) and [`openvibe-sdk v0.177.0`](https://github.com/OpenVibers/OpenVibe.SDK/tree/v0.177.0).

- Version: 1.0.0
- Owner: ai
- Visibility: public
- Status: active
- Compatibility: backward
- Decision: [ADR-015](/docs/adr/ADR-015)
- Schema: [`https://openvibe.network/contracts/ai/research.v1.json`](/docs/contracts/ai.research.json)

ai.research v1 (OpenVibe.AI workflow research.deep\_dive, server/deep-dive/research.js): the general deep dive's report. Any question, researched the way an expert would: the plan's questions, every source the searches found, every page chosen and read as text (or why it could not be), the notes on each page (what it says, short exact quotes, what kind of source it is), and the answer, where every claim cites the pages it rests on by source id: a summary, key points, an answer per question with its confidence, a comparison when the question compares, where the sources disagree, what is still open and the next steps. The receipt lists every model call. OpenVibe.Exchange shows it (/deep-dive); OpenVibe.Design's design deep dive carries the same research block (ai.deep-dive@1 research).

## Fields

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `id` | string | yes |  | - `maxLength 40` |
| `schema` | const | yes |  | - `= "ai.research@1"` |
| `run_id` | string | yes |  | - `maxLength 40` |
| `status` | enum | yes |  | - `one of "queued", "running", "succeeded", "failed", "cancelled"` |
| `input` | object | yes |  | - `no other fields` |
| `input.question` | string | yes |  | - `maxLength 500` |
| `input.depth` | enum | yes |  | - `one of "quick", "thorough", "expert"` |
| `input.max_pages` | integer | yes |  | - `minimum 1`<br>- `maximum 40` |
| `input.sites` | array of string |  |  | - `maxItems 30`<br>- `items: maxLength 2048` |
| `steps` | array of object | yes |  | - `maxItems 6`<br>- `items: no other fields` |
| `steps[].key` | enum | yes |  | - `one of "plan", "search", "choose", "read", "analyse", "write"` |
| `steps[].status` | enum | yes |  | - `one of "pending", "running", "done", "skipped", "failed"` |
| `steps[].detail` | string \| null |  |  | - `maxLength 300` |
| `steps[].started_at` | string \| null |  |  |  |
| `steps[].finished_at` | string \| null |  |  |  |
| `questions` | array of object | yes |  | - `maxItems 12`<br>- `items: no other fields` |
| `questions[].key` | string | yes |  | - `maxLength 40` |
| `questions[].question` | string | yes |  | - `maxLength 400` |
| `sources` | array of object | yes |  | - `maxItems 200`<br>- `items: no other fields` |
| `sources[].id` | string | yes |  | - `maxLength 40` |
| `sources[].kind` | enum | yes |  | - `one of "web", "picture", "icon", "project", "rules", "component", "named"` |
| `sources[].title` | string | yes |  | - `maxLength 400` |
| `sources[].url` | string | yes |  | - `maxLength 2048` |
| `sources[].publisher` | string \| null |  |  | - `maxLength 200` |
| `sources[].engine` | string \| null |  |  | - `maxLength 80` |
| `sources[].snippet` | string \| null |  |  | - `maxLength 2000` |
| `sources[].license` | string \| null |  |  | - `maxLength 120` |
| `sources[].read_at` | string | yes |  | - `maxLength 40` |
| `reads` | array of object | yes |  | - `maxItems 40`<br>- `items: no other fields` |
| `reads[].id` | string | yes |  | - `maxLength 40` |
| `reads[].source_id` | string | yes |  | - `maxLength 40` |
| `reads[].url` | string | yes |  | - `maxLength 2048` |
| `reads[].final_url` | string \| null |  |  | - `maxLength 2048` |
| `reads[].title` | string \| null |  |  | - `maxLength 400` |
| `reads[].site` | string \| null |  |  | - `maxLength 200` |
| `reads[].published` | string \| null |  |  | - `maxLength 40` |
| `reads[].read_at` | string | yes |  | - `maxLength 40` |
| `reads[].words` | integer |  |  | - `minimum 0` |
| `reads[].status` | enum | yes |  | - `one of "read", "skipped"` |
| `reads[].reason` | string \| null |  |  | - `maxLength 300` |
| `reads[].relevant` | boolean \| null |  |  |  |
| `reads[].summary` | string \| null |  |  | - `maxLength 1500` |
| `reads[].kind` | enum |  |  | - `one of "primary", "reference", "news", "opinion", "vendor", "forum", "other", null` |
| `reads[].findings` | array of object |  |  | - `maxItems 10`<br>- `items: no other fields` |
| `reads[].findings[].point` | string | yes |  | - `maxLength 600` |
| `reads[].findings[].quote` | string \| null |  |  | - `maxLength 400` |
| `answer` | object | yes |  | - `no other fields` |
| `answer.summary` | string | yes |  | - `maxLength 3000` |
| `answer.key_points` | array of object | yes |  | - `maxItems 12`<br>- `items: no other fields` |
| `answer.key_points[].text` | string | yes |  | - `maxLength 800` |
| `answer.key_points[].sources` | array of string | yes |  | - `maxItems 8`<br>- `items: maxLength 40` |
| `answer.answers` | array of object | yes |  | - `maxItems 12`<br>- `items: no other fields` |
| `answer.answers[].question` | string | yes |  | - `maxLength 400` |
| `answer.answers[].answer` | string | yes |  | - `maxLength 2000` |
| `answer.answers[].confidence` | enum | yes |  | - `one of "high", "medium", "low"` |
| `answer.answers[].sources` | array of string | yes |  | - `maxItems 8`<br>- `items: maxLength 40` |
| `answer.comparison` | object \| null | yes |  |  |
| `answer.disagreements` | array of object | yes |  | - `maxItems 10`<br>- `items: no other fields` |
| `answer.disagreements[].what` | string | yes |  | - `maxLength 800` |
| `answer.disagreements[].sources` | array of string | yes |  | - `maxItems 8`<br>- `items: maxLength 40` |
| `answer.open_questions` | array of string | yes |  | - `maxItems 10`<br>- `items: maxLength 400` |
| `answer.next_steps` | array of string | yes |  | - `maxItems 10`<br>- `items: maxLength 400` |
| `receipt` | object | yes |  | - `no other fields` |
| `receipt.price_usd` | number | yes |  | - `minimum 0` |
| `receipt.held_usd` | number | yes |  | - `minimum 0` |
| `receipt.cost_usd` | number | yes |  | - `minimum 0` |
| `receipt.pages_read` | integer | yes |  | - `minimum 0` |
| `receipt.synthetic` | boolean | yes |  |  |
| `receipt.models` | array of object | yes |  | - `maxItems 200`<br>- `items: no other fields` |
| `receipt.models[].step` | enum | yes |  | - `one of "plan", "choose", "analyse", "write"` |
| `receipt.models[].provider` | string \| null | yes |  | - `maxLength 80` |
| `receipt.models[].model` | string \| null | yes |  | - `maxLength 200` |
| `receipt.models[].tokens_in` | integer | yes |  | - `minimum 0` |
| `receipt.models[].tokens_out` | integer | yes |  | - `minimum 0` |
| `receipt.models[].cost_usd` | number | yes |  | - `minimum 0` |
| `receipt.models[].ms` | integer | yes |  | - `minimum 0` |
| `gaps` | array of string | yes |  | - `maxItems 40`<br>- `items: maxLength 400` |
| `created_at` | string | yes |  | - `maxLength 40` |
| `updated_at` | string | yes |  | - `maxLength 40` |
| `finished_at` | string \| null |  |  |  |

## Examples

From the contract's own test fixtures: valid ones validate, rejected ones must fail.

 Valid: heat-pumps

~~~~
{
  "id": "run_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "schema": "ai.research@1",
  "run_id": "run_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "status": "succeeded",
  "input": {
    "question": "Are heat pumps worth it in a cold climate?",
    "depth": "quick",
    "max_pages": 8
  },
  "steps": [
    {
      "key": "plan",
      "status": "done",
      "detail": null,
      "started_at": "2026-11-15T22:00:10.000Z",
      "finished_at": "2026-11-15T22:00:10.000Z"
    },
    {
      "key": "search",
      "status": "done",
      "detail": null,
      "started_at": "2026-11-15T22:00:10.000Z",
      "finished_at": "2026-11-15T22:00:10.000Z"
    },
    {
      "key": "choose",
      "status": "done",
      "detail": null,
      "started_at": "2026-11-15T22:00:10.000Z",
      "finished_at": "2026-11-15T22:00:10.000Z"
    },
    {
      "key": "read",
      "status": "done",
      "detail": null,
      "started_at": "2026-11-15T22:00:10.000Z",
      "finished_at": "2026-11-15T22:00:10.000Z"
    },
    {
      "key": "analyse",
      "status": "done",
      "detail": null,
      "started_at": "2026-11-15T22:00:10.000Z",
      "finished_at": "2026-11-15T22:00:10.000Z"
    },
    {
      "key": "write",
      "status": "done",
      "detail": null,
      "started_at": "2026-11-15T22:00:10.000Z",
      "finished_at": "2026-11-15T22:00:10.000Z"
    }
  ],
  "questions": [
    {
      "key": "cold",
      "question": "How efficient are they in the cold?"
    },
    {
      "key": "cost",
      "question": "What do they cost to run?"
    }
  ],
  "sources": [
    {
      "id": "src_1",
      "kind": "web",
      "title": "Heat pumps, part 1",
      "url": "https://example.org/heat-pumps-1",
      "publisher": "example.org",
      "engine": "openvibe",
      "snippet": null,
      "license": null,
      "read_at": "2026-11-15T22:00:10.000Z"
    },
    {
      "id": "src_2",
      "kind": "web",
      "title": "Heat pumps, part 2",
      "url": "https://example.org/heat-pumps-2",
      "publisher": "example.org",
      "engine": "openvibe",
      "snippet": null,
      "license": null,
      "read_at": "2026-11-15T22:00:10.000Z"
    },
    {
      "id": "src_3",
      "kind": "web",
      "title": "Heat pumps, part 3",
      "url": "https://example.org/heat-pumps-3",
      "publisher": "example.org",
      "engine": "openvibe",
      "snippet": null,
      "license": null,
      "read_at": "2026-11-15T22:00:10.000Z"
    }
  ],
  "reads": [
    {
      "id": "read_1",
      "source_id": "src_1",
      "url": "https://example.org/heat-pumps-1",
      "final_url": "https://example.org/heat-pumps-1",
      "title": "Heat pumps, part 1",
      "site": "Example",
      "published": "2026-03-01",
      "read_at": "2026-11-15T22:00:10.000Z",
      "words": 1200,
      "status": "read",
      "reason": null,
      "relevant": true,
      "summary": "How a heat pump moves heat, and how well it does in the cold.",
      "kind": "reference",
      "findings": [
        {
          "point": "Efficiency drops below -15 C but stays above 1.",
          "quote": "a COP of 1.8 at -20 C"
        }
      ]
    },
    {
      "id": "read_2",
      "source_id": "src_2",
      "url": "https://example.org/heat-pumps-2",
      "final_url": "https://example.org/heat-pumps-2",
      "title": "Heat pumps, part 2",
      "site": "Example",
      "published": "2026-03-01",
      "read_at": "2026-11-15T22:00:10.000Z",
      "words": 1200,
      "status": "read",
      "reason": null,
      "relevant": true,
      "summary": "How a heat pump moves heat, and how well it does in the cold.",
      "kind": "news",
      "findings": [
        {
          "point": "Efficiency drops below -15 C but stays above 1.",
          "quote": "a COP of 1.8 at -20 C"
        }
      ]
    },
    {
      "id": "read_3",
      "source_id": "src_3",
      "url": "https://example.org/heat-pumps-3",
      "final_url": null,
      "title": "Heat pumps, part 3",
      "site": "Example",
      "published": null,
      "read_at": "2026-11-15T22:00:10.000Z",
      "words": 0,
      "status": "skipped",
      "reason": "robots.txt disallows this page",
      "relevant": null,
      "summary": null,
      "kind": null,
      "findings": []
    }
  ],
  "answer": {
    "summary": "Yes, in most cold climates: modern heat pumps keep working well below freezing.",
    "key_points": [
      {
        "text": "They keep a COP above 1 at -20 C.",
        "sources": [
          "src_1"
        ]
      }
    ],
    "answers": [
      {
        "question": "How efficient are they in the cold?",
        "answer": "Less efficient, still better than resistance heat.",
        "confidence": "high",
        "sources": [
          "src_1"
        ]
      }
    ],
    "comparison": {
      "columns": [
        "Option",
        "Cost"
      ],
      "rows": [
        [
          "Heat pump",
          "$$"
        ],
        [
          "Gas",
          "$"
        ]
      ]
    },
    "disagreements": [
      {
        "what": "How much grants cover.",
        "sources": [
          "src_2"
        ]
      }
    ],
    "open_questions": [
      "Long-term reliability at -30 C."
    ],
    "next_steps": [
      "Get two quotes."
    ]
  },
  "receipt": {
    "price_usd": 0.1,
    "held_usd": 0.1,
    "cost_usd": 0.0123,
    "pages_read": 2,
    "synthetic": false,
    "models": [
      {
        "step": "plan",
        "provider": "deepseek",
        "model": "deepseek-v4-flash",
        "tokens_in": 900,
        "tokens_out": 300,
        "cost_usd": 0.001,
        "ms": 900
      }
    ]
  },
  "gaps": [
    "example.org: robots.txt disallows this page"
  ],
  "created_at": "2026-11-15T22:00:00.000Z",
  "updated_at": "2026-11-15T22:01:10.000Z",
  "finished_at": "2026-11-15T22:01:10.000Z"
}
~~~~

Rejected: uncited-key-point

~~~~
{
  "id": "run_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "schema": "ai.research@1",
  "run_id": "run_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "status": "succeeded",
  "input": {
    "question": "Are heat pumps worth it in a cold climate?",
    "depth": "quick",
    "max_pages": 8
  },
  "steps": [
    {
      "key": "plan",
      "status": "done",
      "detail": null,
      "started_at": "2026-11-15T22:00:10.000Z",
      "finished_at": "2026-11-15T22:00:10.000Z"
    },
    {
      "key": "search",
      "status": "done",
      "detail": null,
      "started_at": "2026-11-15T22:00:10.000Z",
      "finished_at": "2026-11-15T22:00:10.000Z"
    },
    {
      "key": "choose",
      "status": "done",
      "detail": null,
      "started_at": "2026-11-15T22:00:10.000Z",
      "finished_at": "2026-11-15T22:00:10.000Z"
    },
    {
      "key": "read",
      "status": "done",
      "detail": null,
      "started_at": "2026-11-15T22:00:10.000Z",
      "finished_at": "2026-11-15T22:00:10.000Z"
    },
    {
      "key": "analyse",
      "status": "done",
      "detail": null,
      "started_at": "2026-11-15T22:00:10.000Z",
      "finished_at": "2026-11-15T22:00:10.000Z"
    },
    {
      "key": "write",
      "status": "done",
      "detail": null,
      "started_at": "2026-11-15T22:00:10.000Z",
      "finished_at": "2026-11-15T22:00:10.000Z"
    }
  ],
  "questions": [
    {
      "key": "cold",
      "question": "How efficient are they in the cold?"
    },
    {
      "key": "cost",
      "question": "What do they cost to run?"
    }
  ],
  "sources": [
    {
      "id": "src_1",
      "kind": "web",
      "title": "Heat pumps, part 1",
      "url": "https://example.org/heat-pumps-1",
      "publisher": "example.org",
      "engine": "openvibe",
      "snippet": null,
      "license": null,
      "read_at": "2026-11-15T22:00:10.000Z"
    },
    {
      "id": "src_2",
      "kind": "web",
      "title": "Heat pumps, part 2",
      "url": "https://example.org/heat-pumps-2",
      "publisher": "example.org",
      "engine": "openvibe",
      "snippet": null,
      "license": null,
      "read_at": "2026-11-15T22:00:10.000Z"
    },
    {
      "id": "src_3",
      "kind": "web",
      "title": "Heat pumps, part 3",
      "url": "https://example.org/heat-pumps-3",
      "publisher": "example.org",
      "engine": "openvibe",
      "snippet": null,
      "license": null,
      "read_at": "2026-11-15T22:00:10.000Z"
    }
  ],
  "reads": [
    {
      "id": "read_1",
      "source_id": "src_1",
      "url": "https://example.org/heat-pumps-1",
      "final_url": "https://example.org/heat-pumps-1",
      "title": "Heat pumps, part 1",
      "site": "Example",
      "published": "2026-03-01",
      "read_at": "2026-11-15T22:00:10.000Z",
      "words": 1200,
      "status": "read",
      "reason": null,
      "relevant": true,
      "summary": "How a heat pump moves heat, and how well it does in the cold.",
      "kind": "reference",
      "findings": [
        {
          "point": "Efficiency drops below -15 C but stays above 1.",
          "quote": "a COP of 1.8 at -20 C"
        }
      ]
    },
    {
      "id": "read_2",
      "source_id": "src_2",
      "url": "https://example.org/heat-pumps-2",
      "final_url": "https://example.org/heat-pumps-2",
      "title": "Heat pumps, part 2",
      "site": "Example",
      "published": "2026-03-01",
      "read_at": "2026-11-15T22:00:10.000Z",
      "words": 1200,
      "status": "read",
      "reason": null,
      "relevant": true,
      "summary": "How a heat pump moves heat, and how well it does in the cold.",
      "kind": "news",
      "findings": [
        {
          "point": "Efficiency drops below -15 C but stays above 1.",
          "quote": "a COP of 1.8 at -20 C"
        }
      ]
    },
    {
      "id": "read_3",
      "source_id": "src_3",
      "url": "https://example.org/heat-pumps-3",
      "final_url": null,
      "title": "Heat pumps, part 3",
      "site": "Example",
      "published": null,
      "read_at": "2026-11-15T22:00:10.000Z",
      "words": 0,
      "status": "skipped",
      "reason": "robots.txt disallows this page",
      "relevant": null,
      "summary": null,
      "kind": null,
      "findings": []
    }
  ],
  "answer": {
    "summary": "Yes, in most cold climates: modern heat pumps keep working well below freezing.",
    "key_points": [
      {
        "text": "A point with no sources field."
      }
    ],
    "answers": [
      {
        "question": "How efficient are they in the cold?",
        "answer": "Less efficient, still better than resistance heat.",
        "confidence": "high",
        "sources": [
          "src_1"
        ]
      }
    ],
    "comparison": {
      "columns": [
        "Option",
        "Cost"
      ],
      "rows": [
        [
          "Heat pump",
          "$$"
        ],
        [
          "Gas",
          "$"
        ]
      ]
    },
    "disagreements": [
      {
        "what": "How much grants cover.",
        "sources": [
          "src_2"
        ]
      }
    ],
    "open_questions": [
      "Long-term reliability at -30 C."
    ],
    "next_steps": [
      "Get two quotes."
    ]
  },
  "receipt": {
    "price_usd": 0.1,
    "held_usd": 0.1,
    "cost_usd": 0.0123,
    "pages_read": 2,
    "synthetic": false,
    "models": [
      {
        "step": "plan",
        "provider": "deepseek",
        "model": "deepseek-v4-flash",
        "tokens_in": 900,
        "tokens_out": 300,
        "cost_usd": 0.001,
        "ms": 900
      }
    ]
  },
  "gaps": [
    "example.org: robots.txt disallows this page"
  ],
  "created_at": "2026-11-15T22:00:00.000Z",
  "updated_at": "2026-11-15T22:01:10.000Z",
  "finished_at": "2026-11-15T22:01:10.000Z"
}
~~~~

## Validate

~~~~
const contracts = require('openvibe-contracts');
contracts.validate('ai.research@1', value);   // { valid, errors: [{ path, message }] }
~~~~
