Current schema 1.0
Lab Coach API Contract
Versioned, field-by-field reference for the lab coach payload. Each version below mirrors the Zod schema and server enforcer used at runtime. Future schema bumps append a new entry — older versions stay here for historical reference.
v1.0current
Released 2025-01-15Initial public contract. Server enforces normalizeLabResult on every response; client runs a runtime guard and rejects incomplete payloads.
Response envelope
| Field | Type | Req | Notes |
|---|---|---|---|
| ok | enum true | false | yes | Whether the request produced a usable lab result. |
| schemaVersion | string | yes | Semver-style wire version (MAJOR.MINOR). Client compares to LAB_COACH_SCHEMA_VERSION; major mismatch → hard error, minor drift → warning. matches /^\d+\.\d+$/ |
| result | object | no | Present when ok === true. See sections below. |
| error | string | no | Present when ok === false. Human-readable error message. |
| validationReasons | string[] | no | Populated when the server's enforcer had to repair the model output. Useful for production diagnostics; absent when no recovery was needed. |
| synthesizedSections | string[] | no | Names of fields the server synthesised because the model omitted them. Empty / absent when the model produced a fully valid payload. |
| usedModels | string[] | no | Models consulted to produce this result (primary + fallbacks). |
Lab summary & alignment
Required narrative fields — always non-empty strings.
| Field | Type | Req | Notes |
|---|---|---|---|
| labSummary | string | yes | Plain-language summary of what the lab does. non-empty |
| alignment | string | yes | How the candidate's profile aligns with the lab. non-empty |
| suggestedOpening | string | yes | Suggested opening line for an outreach email. non-empty |
| fitScore | integer | yes | Overall fit score. 0–100, clamped server-side |
Research context
Optional context arrays — default to [] when absent.
| Field | Type | Req | Notes |
|---|---|---|---|
| researchThemes | string[] | no | Themes the lab pursues. default [] |
| recentPublications | object[] | no | Recent papers from the lab. default [] |
| ↳ title | string | yes | Publication title. |
| ↳ year | string | no | Publication year as a string. |
| ↳ takeaway | string | no | One-line takeaway describing the paper's contribution. default "" |
| strengths | string[] | no | Candidate strengths relative to this lab. default [] |
| gaps | string[] | no | Candidate gaps relative to this lab. default [] |
| hints | object[] | no | Tactical outreach hints. default [] |
| ↳ title | string | yes | Hint title. |
| ↳ suggestion | string | yes | Concrete suggestion text. |
PI analysis (optional block)
Present when PI metrics were available. Entire block is optional; individual fields default to empty strings or [] when synthesised.
| Field | Type | Req | Notes |
|---|---|---|---|
| piName | string | no | Principal investigator name. |
| affiliation | string | no | Institutional affiliation. |
| totalCitations | string | no | Total citation count (string for formatting flexibility). |
| hIndex | string | no | h-index metric. |
| i10Index | string | no | i10-index metric. |
| researchDirection | string | no | Narrative paragraph on overall research direction. default "" |
| coreThemes | string[] | no | Established research themes. default [] |
| emergingDirections | string[] | no | Newer / forward-looking research threads. default [] |
| methodsAndTechniques | string[] | no | Methods and techniques the lab is known for. default [] |
| signatureCollaborations | string[] | no | Notable recurring collaborators. default [] |
| topPublications | object[] | no | Highlight publications. default [] |
| ↳ title | string | yes | Publication title. |
| ↳ year | string | no | Publication year as a string. |
| ↳ takeaway | string | no | One-line takeaway describing the paper's contribution. default "" |
| recentTrajectory | string | no | Where the lab appears to be heading. default "" |
CV fit (optional block)
Present when a CV was supplied. When present, verdict / verdictHeadline / matchScore / reasoning are required.
| Field | Type | Req | Notes |
|---|---|---|---|
| verdict | enum strong_match | moderate_match | weak_match | not_suitable | yes | Categorical CV fit verdict. |
| verdictHeadline | string | yes | Short headline summarising the verdict. |
| matchScore | integer | yes | CV-to-lab match score. 0–100 |
| reasoning | string | yes | Explanation of the verdict. |
| matchingSkills | string[] | no | Skills present in both CV and lab requirements. default [] |
| missingSkills | string[] | no | Lab-required skills missing from the CV. default [] |
| recommendedActions | object[] | no | Concrete next steps to improve fit. default [] |
| ↳ title | string | yes | Action title. |
| ↳ action | string | yes | Description of the recommended action. |
Migration notes
- No prior version — this is the baseline contract.
- Clients MUST read `schemaVersion` and call `checkSchemaCompatibility` before trusting `result`.
- Server-side: every code path must stamp `schemaVersion` (including early error returns).