AiResearch ai.research@1
Generated at from
openvibe-contracts v0.443.0 and
openvibe-sdk v0.177.0.
- Version
- 1.0.0
- Owner
- ai
- Visibility
- public
- Status
- active
- Compatibility
- backward
- Decision
- ADR-015
- Schema
https://openvibe.network/contracts/ai/research.v1.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 |
| |
schema | const | yes |
| |
run_id | string | yes |
| |
status | enum | yes |
| |
input | object | yes |
| |
input.question | string | yes |
| |
input.depth | enum | yes |
| |
input.max_pages | integer | yes |
| |
input.sites | array of string |
| ||
steps | array of object | yes |
| |
steps[].key | enum | yes |
| |
steps[].status | enum | yes |
| |
steps[].detail | string | null |
| ||
steps[].started_at | string | null | |||
steps[].finished_at | string | null | |||
questions | array of object | yes |
| |
questions[].key | string | yes |
| |
questions[].question | string | yes |
| |
sources | array of object | yes |
| |
sources[].id | string | yes |
| |
sources[].kind | enum | yes |
| |
sources[].title | string | yes |
| |
sources[].url | string | yes |
| |
sources[].publisher | string | null |
| ||
sources[].engine | string | null |
| ||
sources[].snippet | string | null |
| ||
sources[].license | string | null |
| ||
sources[].read_at | string | yes |
| |
reads | array of object | yes |
| |
reads[].id | string | yes |
| |
reads[].source_id | string | yes |
| |
reads[].url | string | yes |
| |
reads[].final_url | string | null |
| ||
reads[].title | string | null |
| ||
reads[].site | string | null |
| ||
reads[].published | string | null |
| ||
reads[].read_at | string | yes |
| |
reads[].words | integer |
| ||
reads[].status | enum | yes |
| |
reads[].reason | string | null |
| ||
reads[].relevant | boolean | null | |||
reads[].summary | string | null |
| ||
reads[].kind | enum |
| ||
reads[].findings | array of object |
| ||
reads[].findings[].point | string | yes |
| |
reads[].findings[].quote | string | null |
| ||
answer | object | yes |
| |
answer.summary | string | yes |
| |
answer.key_points | array of object | yes |
| |
answer.key_points[].text | string | yes |
| |
answer.key_points[].sources | array of string | yes |
| |
answer.answers | array of object | yes |
| |
answer.answers[].question | string | yes |
| |
answer.answers[].answer | string | yes |
| |
answer.answers[].confidence | enum | yes |
| |
answer.answers[].sources | array of string | yes |
| |
answer.comparison | object | null | yes | ||
answer.disagreements | array of object | yes |
| |
answer.disagreements[].what | string | yes |
| |
answer.disagreements[].sources | array of string | yes |
| |
answer.open_questions | array of string | yes |
| |
answer.next_steps | array of string | yes |
| |
receipt | object | yes |
| |
receipt.price_usd | number | yes |
| |
receipt.held_usd | number | yes |
| |
receipt.cost_usd | number | yes |
| |
receipt.pages_read | integer | yes |
| |
receipt.synthetic | boolean | yes | ||
receipt.models | array of object | yes |
| |
receipt.models[].step | enum | yes |
| |
receipt.models[].provider | string | null | yes |
| |
receipt.models[].model | string | null | yes |
| |
receipt.models[].tokens_in | integer | yes |
| |
receipt.models[].tokens_out | integer | yes |
| |
receipt.models[].cost_usd | number | yes |
| |
receipt.models[].ms | integer | yes |
| |
gaps | array of string | yes |
| |
created_at | string | yes |
| |
updated_at | string | yes |
| |
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 }] }