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

FieldTypeRequiredDescriptionConstraints
idstringyes
  • maxLength 40
schemaconstyes
  • = "ai.research@1"
run_idstringyes
  • maxLength 40
statusenumyes
  • one of "queued", "running", "succeeded", "failed", "cancelled"
inputobjectyes
  • no other fields
input.questionstringyes
  • maxLength 500
input.depthenumyes
  • one of "quick", "thorough", "expert"
input.max_pagesintegeryes
  • minimum 1
  • maximum 40
input.sitesarray of string
  • maxItems 30
  • items: maxLength 2048
stepsarray of objectyes
  • maxItems 6
  • items: no other fields
steps[].keyenumyes
  • one of "plan", "search", "choose", "read", "analyse", "write"
steps[].statusenumyes
  • one of "pending", "running", "done", "skipped", "failed"
steps[].detailstring | null
  • maxLength 300
steps[].started_atstring | null
steps[].finished_atstring | null
questionsarray of objectyes
  • maxItems 12
  • items: no other fields
questions[].keystringyes
  • maxLength 40
questions[].questionstringyes
  • maxLength 400
sourcesarray of objectyes
  • maxItems 200
  • items: no other fields
sources[].idstringyes
  • maxLength 40
sources[].kindenumyes
  • one of "web", "picture", "icon", "project", "rules", "component", "named"
sources[].titlestringyes
  • maxLength 400
sources[].urlstringyes
  • maxLength 2048
sources[].publisherstring | null
  • maxLength 200
sources[].enginestring | null
  • maxLength 80
sources[].snippetstring | null
  • maxLength 2000
sources[].licensestring | null
  • maxLength 120
sources[].read_atstringyes
  • maxLength 40
readsarray of objectyes
  • maxItems 40
  • items: no other fields
reads[].idstringyes
  • maxLength 40
reads[].source_idstringyes
  • maxLength 40
reads[].urlstringyes
  • maxLength 2048
reads[].final_urlstring | null
  • maxLength 2048
reads[].titlestring | null
  • maxLength 400
reads[].sitestring | null
  • maxLength 200
reads[].publishedstring | null
  • maxLength 40
reads[].read_atstringyes
  • maxLength 40
reads[].wordsinteger
  • minimum 0
reads[].statusenumyes
  • one of "read", "skipped"
reads[].reasonstring | null
  • maxLength 300
reads[].relevantboolean | null
reads[].summarystring | null
  • maxLength 1500
reads[].kindenum
  • one of "primary", "reference", "news", "opinion", "vendor", "forum", "other", null
reads[].findingsarray of object
  • maxItems 10
  • items: no other fields
reads[].findings[].pointstringyes
  • maxLength 600
reads[].findings[].quotestring | null
  • maxLength 400
answerobjectyes
  • no other fields
answer.summarystringyes
  • maxLength 3000
answer.key_pointsarray of objectyes
  • maxItems 12
  • items: no other fields
answer.key_points[].textstringyes
  • maxLength 800
answer.key_points[].sourcesarray of stringyes
  • maxItems 8
  • items: maxLength 40
answer.answersarray of objectyes
  • maxItems 12
  • items: no other fields
answer.answers[].questionstringyes
  • maxLength 400
answer.answers[].answerstringyes
  • maxLength 2000
answer.answers[].confidenceenumyes
  • one of "high", "medium", "low"
answer.answers[].sourcesarray of stringyes
  • maxItems 8
  • items: maxLength 40
answer.comparisonobject | nullyes
answer.disagreementsarray of objectyes
  • maxItems 10
  • items: no other fields
answer.disagreements[].whatstringyes
  • maxLength 800
answer.disagreements[].sourcesarray of stringyes
  • maxItems 8
  • items: maxLength 40
answer.open_questionsarray of stringyes
  • maxItems 10
  • items: maxLength 400
answer.next_stepsarray of stringyes
  • maxItems 10
  • items: maxLength 400
receiptobjectyes
  • no other fields
receipt.price_usdnumberyes
  • minimum 0
receipt.held_usdnumberyes
  • minimum 0
receipt.cost_usdnumberyes
  • minimum 0
receipt.pages_readintegeryes
  • minimum 0
receipt.syntheticbooleanyes
receipt.modelsarray of objectyes
  • maxItems 200
  • items: no other fields
receipt.models[].stepenumyes
  • one of "plan", "choose", "analyse", "write"
receipt.models[].providerstring | nullyes
  • maxLength 80
receipt.models[].modelstring | nullyes
  • maxLength 200
receipt.models[].tokens_inintegeryes
  • minimum 0
receipt.models[].tokens_outintegeryes
  • minimum 0
receipt.models[].cost_usdnumberyes
  • minimum 0
receipt.models[].msintegeryes
  • minimum 0
gapsarray of stringyes
  • maxItems 40
  • items: maxLength 400
created_atstringyes
  • maxLength 40
updated_atstringyes
  • maxLength 40
finished_atstring | 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 }] }