What you can send
-Everything a caller can give Iris. The settings above are fixed by the deployment.
- +The API
+Every endpoint, from GET /v1/openapi.json, the exact contract. Open one to see what it does, try it on real data, and read its answer explained.
Loading…
Share
+ ''; } - // Every input the API takes. test/how-it-works.test.ts fails if a route reads a request field - // that is not listed here. - const INPUTS = [ - { method: 'POST', path: '/sessions', field: 'images', where: 'form upload', what: 'The document: one PDF, or page images in reading order. Required.' }, - { method: 'POST', path: '/sessions/{id}/feedback', field: 'feedback', where: 'JSON body', what: 'What to fix, in words. Iris works on the document again, as a new run.' }, - { method: 'POST', path: '/sessions/{id}/pdf', field: 'values', where: 'JSON body', what: 'Optional form values for the tagged PDF, by field name. Never stored or logged.' }, - { method: 'POST', path: '/sessions/{id}/close', field: null, where: '', what: 'Accept the document. Its pages become examples that future changes to the page agent are checked against.' }, - { method: 'GET', path: '/sessions', field: 'limit', where: 'query', what: 'How many sessions to list at once.' }, - { method: 'GET', path: '/sessions', field: 'status', where: 'query', what: 'List only sessions with this status.' }, - { method: 'GET', path: '/sessions', field: 'cursor', where: 'query', what: 'Where the next page of the list starts.' }, - { method: 'GET', path: '/quality', field: 'days', where: 'query', what: 'How many days the quality tally covers. Needs its own key, and is off unless set.' }, - ]; const modelName = (m) => String(m || '').replace(/^us\./, ''); // The model an agent used in this run (from its log), or the one it is set to use before then. function modelFor(ev, st, agent, step, cap) { @@ -832,10 +820,75 @@Share
+ '' + (priced ? 'Costs on this page are estimates from the prices above, set by this deployment. They are not a bill.' : 'No prices are set, so this page shows tokens but not cost.') + '
'); return out.join(''); } - function inputsHtml() { - return '| Call | What you send | What it does |
|---|---|---|
' + i.method + ' ' + esc(API + i.path) + ' | ' + (i.field ? '' + esc(i.field) + ' (' + esc(i.where) + ')' : 'nothing') + ' | ' + esc(i.what) + ' |
An upload used to accept its own review-round setting. It no longer does: a config field is ignored, and every document gets the deployment\'s settings.
$1');
+ const AUTH_WORDS = { open: 'Open to anyone.', key: 'Needs the API key where this deployment sets one.', quality: 'Needs the quality token.' };
+ function apiCardHtml(o, i) {
+ const k = 'api' + i;
+ const tryable = o.method === 'GET' && o.path !== '/v1/openapi.json';
+ const action = o.method === 'POST' ? (o.path === '/v1/sessions' ? 'Use Start to send one.' : o.path.endsWith('/feedback') ? 'Use the feedback box in step 5 of a finished run.' : o.path.endsWith('/pdf') ? 'Use “Make the tagged PDF” in step 6.' : o.path.endsWith('/close') ? ' Accepting adds its pages to the examples Iris checks future page-agent changes against. It cannot be undone.' : '') : '';
+ return '' + o.method + ' ' + esc(o.path) + ' ' + esc(o.summary) + '
' + + (o.description ? '' + md(o.description) + '
' : '') + + '' + AUTH_WORDS[o.auth] + '
' + + (o.params.length ? 'You can send
- ' + o.params.map((x) => '
' + esc(x.name) + '(' + esc(x.in) + ')' + (x.description ? ': ' + md(x.description) : '') + ' ').join('') + '
Body
- ' + o.body.map((x) => '
' + esc(x.name) + '' + (x.required ? ' (required)' : '') + (x.description ? ': ' + md(x.description) : '') + ' ').join('') + '
Answers
- ' + o.responses.filter((r) => r.code !== '429' && !(r.code === '401' && o.auth === 'key')).map((r) => '
' + esc(r.code) + '' + md(r.description) + ' ').join('') + '
' + (o.auth === 'key' ? 'It answers 401 without the key, where one is needed. ' : '') + (o.responses.some((r) => r.code === '429') ? 'It answers 429 when too many requests come from one address.' : '') + '
' + esc(curl(o.method, o.path.replace(/^\/v1/, ''), o.auth === 'quality' ? "-H 'Authorization: Bearer YOUR_QUALITY_TOKEN'" : o.method === 'POST' && o.body.length ? "-H 'Content-Type: application/json' -d '{…}'" : '')) + ''
+ + (tryable ? '' : '') + (action ? '' + action + '
' : '') + + '' + esc(a.bytes) + '
' + : a.rows.length ? '| Field | Value | What it means |
|---|---|---|
' + esc(x.path) + ' | ' + esc(x.value) + ' | ' + md(x.meaning) + ' |
' + esc(a.summary) + '
'; + return '' + a.status + ' ' + md(a.description) + '
' + body + (a.raw ? det('raw' + i, 'The answer itself', '' + esc(a.raw) + '') : ''); + } + function apiHtml(spec) { + if (!spec) return '
This deployment did not serve its API description.
'; + let i = 0; + return apiGroups(spec).map((g) => '' + esc(g.tag) + '
' + md(g.description) + '
' + + (g.tag === 'Operators' ? 'Only for this page and only for these calls. It is never stored, logged or shown.
' : '') + + g.ops.map((o) => apiCardHtml(o, i++)).join('')).join(''); } // ----- State and API calls ----- @@ -853,9 +906,16 @@Share
if (type && type.includes('html')) return text.length.toLocaleString() + ' characters of HTML.'; try { return JSON.stringify(JSON.parse(text), null, 2).slice(0, 4000); } catch { return text.slice(0, 4000); } } - async function call(key, method, path, { body, extra, plain, json = true } = {}) { - const res = await fetch(API + path, { method, body, headers: body && !(body instanceof FormData) ? { 'Content-Type': 'application/json' } : undefined }); + // `headers` carries a token for one call. It is sent and never recorded: the card shows only the answer. + async function call(key, method, path, { body, extra, plain, json = true, headers } = {}) { + const res = await fetch(API + path, { method, body, headers: { ...(body && !(body instanceof FormData) ? { 'Content-Type': 'application/json' } : {}), ...(headers || {}) } }); const type = res.headers.get('content-type') || ''; + // An image or a PDF is kept as bytes: decoding it as text would fill the card with noise. + if (/^image\/|pdf/.test(type)) { + const blob = await res.blob(); + record(key, { method, path, extra, status: res.status, body: blob.size.toLocaleString() + ' bytes of ' + type.split(';')[0] + '.', plain }); + return { res, text: '', blob, data: null }; + } const text = await res.text(); record(key, { method, path, extra, status: res.status, body: summarise(text, type), plain }); return { res, text, data: json && type.includes('json') ? JSON.parse(text) : null }; @@ -865,12 +925,14 @@Share
try { state.limits = (await call('limits', 'GET', '/limits', { plain: 'What this deployment accepts, and whether it makes tagged PDFs.' })).data; } catch { /* optional */ } } - // Before a new upload or a newly opened session: the last one's polling stops, and its cards go. - // The calls about the deployment itself (/limits, /me, /settings) stay. + // Before a new upload or a newly opened session: the last one's polling stops, and its cards go, + // with any Try-it answers (they may name the old session). The calls about the deployment itself + // (/limits, /me, /settings, /stats, /openapi.json) stay. function resetSession() { clearTimeout(state.timer); Object.assign(state, { id: null, uploaded: false, run: null, events: [], session: null, manifest: null, output: null, diagnostics: null, fields: null, pdf: null, done: false, sourceIsPdf: false }); - for (const k of [...state.calls.keys()]) if (!['limits', 'me', 'settings', 'stats'].includes(k)) state.calls.delete(k); + for (const k of [...state.calls.keys()]) if (!['limits', 'me', 'settings', 'stats', 'openapi'].includes(k)) state.calls.delete(k); + document.querySelectorAll('.api-answer').forEach((d) => { d.innerHTML = ''; }); lastSteps = null; snaps.clear(); } @@ -1198,7 +1260,56 @@Share
} } catch { /* unreachable: the first real call will say so */ } } - $('inputs-body').innerHTML = inputsHtml(); + let apiOps = []; + call('openapi', 'GET', '/openapi.json', { plain: 'The API\'s exact contract, which the section on every endpoint is built from.' }).then((r) => { + state.spec = r.res.ok ? r.data : null; + apiOps = state.spec ? apiGroups(state.spec).flatMap((g) => g.ops) : []; + $('api-body').innerHTML = apiHtml(state.spec); + }).catch(() => { $('api-body').innerHTML = apiHtml(null); }); + // Fill a path from what is open: the session, and for audit items the first one it has. + function tryPath(o) { + if (o.path.includes('{id}') && !state.id) return null; + const m = state.manifest || { pages: [], files: [], runs: [] }; + const prompt = state.events.find((e) => e.type === 'model_call_start' && e.prompt); + const snap = (m.runs || []).flatMap((r) => r.snapshots.map((x) => [r.run, x.name]))[0]; + const fill = { id: state.id, order: m.pages[0] && m.pages[0].order, name: o.path.includes('/runs/') ? snap && snap[1] : m.files[0] && m.files[0].name, hash: prompt && prompt.prompt.messages[0].sha256, run: snap && snap[0] }; + let missing = false; + const path = o.path.replace(/\{(\w+)\}/g, (_, k) => { if (fill[k] == null) missing = true; return encodeURIComponent(fill[k]); }); + return missing ? null : path.replace(/^\/v1/, '') + (o.path === '/v1/sessions' ? '?limit=5' : ''); + } + document.addEventListener('click', async (ev) => { + const t = ev.target.closest('button[data-try], button[data-close]'); + if (!t) return; + if (t.dataset.close) { + if (!state.id) { setError('Open or convert a document first.'); return; } + const r = await call('close', 'POST', '/sessions/' + state.id + '/close', { plain: 'Accepting the document. Its pages become examples for checking future page-agent changes.' }); + live(r.res.ok ? 'The document was accepted.' : 'It could not be accepted: ' + ((r.data && r.data.error && r.data.error.message) || r.res.status) + '.'); + return; + } + const i = Number(t.dataset.try), o = apiOps[i], out = $('api-answer-' + i); + const path = tryPath(o); + if (!path) { out.innerHTML = 'Open or convert a document first: this needs a session' + (o.path.includes('audit/') ? ' with audit items' : '') + '.
'; return; } + const token = o.auth === 'quality' ? $('quality-token').value.trim() : ''; + t.disabled = true; out.setAttribute('aria-busy', 'true'); $('calls').hidden = false; + try { + const r = await call('try-' + i, 'GET', path, { json: true, headers: token ? { Authorization: 'Bearer ' + token } : undefined, plain: o.summary + '.' }); + const type = r.res.headers.get('content-type') || ''; + const resp = deref(state.spec, (o.op.responses || {})[String(r.res.status)]) || {}; + const schema = resp.content && resp.content['application/json'] && resp.content['application/json'].schema; + const rows = r.data ? fieldRows(state.spec, schema, r.data) : []; + if (out.dataset.url) URL.revokeObjectURL(out.dataset.url); + const imageUrl = r.blob && type.startsWith('image/') ? URL.createObjectURL(r.blob) : ''; + if (imageUrl) out.dataset.url = imageUrl; + out.innerHTML = answerHtml(i, { status: r.res.status, description: resp.description || '', rows, imageUrl, + bytes: r.blob ? r.blob.size.toLocaleString() + ' bytes of ' + type.split(';')[0] + '.' : '', + summary: type.includes('ndjson') ? r.text.split('\n').filter(Boolean).length + ' lines of the run log.' : type.includes('html') || type.includes('text') ? r.text.length.toLocaleString() + ' characters of text.' : '', + raw: r.blob ? '' : r.text.slice(0, 6000) }); + live('Answer ' + r.res.status + ' from ' + o.method + ' ' + o.path + '.'); + } catch (e) { + out.innerHTML = 'The call failed: ' + esc(e.message) + '
'; + } + t.disabled = false; out.removeAttribute('aria-busy'); + }); Promise.all([loadLimits(), call('stats', 'GET', '/stats', { plain: 'How much this deployment has converted, and how often a document came back with nothing left open.' }).then((r) => r.res.ok ? r.data : null).catch(() => null), call('settings', 'GET', '/settings', { plain: 'How this deployment is set up: its settings and which model does what. Secrets are never included.' }).then((r) => r.res.ok ? r.data : null).catch(() => null)]) .then(([, stats, st]) => { state.settings = st; $('settings-body').innerHTML = settingsHtml(st, state.limits, stats); safeRender(); }); probe().then(() => { diff --git a/test/how-it-works.test.ts b/test/how-it-works.test.ts index fede3b6a..0e81e809 100644 --- a/test/how-it-works.test.ts +++ b/test/how-it-works.test.ts @@ -46,22 +46,25 @@ const lib = new Function( const esc = (s) => String(s ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' })[c]); const AI = ''; const CODE = ''; const plural = (n, one, many) => n + ' ' + (n === 1 ? one : (many || one + 's')); ${pure} - return { feedbackFormHtml, firstSummary, changeSummary, stageSettings, modelFor, usageByStage, usageLine, settingsHtml, inputsHtml, processSteps, pdfReportHtml, PDF_WARN, INPUTS, parseLog, parseReply, explain, SAY, runsOf, pagesFrom, roundsFrom, problems, unresolvedFrom, stagesFrom, curl };`, + return { answerHtml, md, apiGroups, fieldRows, apiHtml, feedbackFormHtml, firstSummary, changeSummary, stageSettings, modelFor, usageByStage, usageLine, settingsHtml, processSteps, pdfReportHtml, PDF_WARN, parseLog, parseReply, explain, SAY, runsOf, pagesFrom, roundsFrom, problems, unresolvedFrom, stagesFrom, curl };`, )(index) as { parseLog(t: string): Record[^<]+<\/label>', '
[^<]*never stored, logged or shown/); + assert.ok(!/Bearer (?!YOUR_QUALITY_TOKEN)/.test(h), "a curl never holds a real token"); +}); + +test("an answer is explained field by field from the document's descriptions", () => { + const schema = spec.paths["/v1/stats"].get.responses["200"].content["application/json"].schema; + const rows = lib.fieldRows(spec, schema, { pages_processed: 40125, documents_processed: 6723, since: "2026-08-12T00:00:00Z", quality: { window_days: 30, clean_rate: 0.37 } }); + const by = Object.fromEntries(rows.map((r) => [r.path, r])); + assert.equal(by.pages_processed.value, "40125"); + assert.match(by.pages_processed.meaning, /Pages delivered/); + assert.match(by["quality.clean_rate"].meaning, /nothing left open/); + assert.equal(lib.apiHtml(null), "
This deployment did not serve its API description.
"); +}); + +test("backticked code in the document's descriptions shows as code, and nothing else becomes markup", () => { + assert.equal(lib.md("`null` on the last page"), "null on the <b>last</b> page");
+});
+
+test("an answer inside an array is explained from the item schema", () => {
+ const schema = spec.paths["/v1/sessions"].get.responses["200"].content["application/json"].schema;
+ const rows = lib.fieldRows(spec, schema, { sessions: [{ session_id: "ses_1", status: "queued" }], next_cursor: null });
+ assert.match(rows.find((r) => r.path === "sessions[0].status")!.meaning, /waits for a free slot/);
+});
+
+test("the API section, rendered, passes the same axe check", async () => {
+ const html = howItWorksPage(page, apiMd).replace('Loading…
' + lib.apiHtml(spec) + "
");
+ assert.ok(html.includes('data-k="api0"'), "the section was put in the page");
+ // And a Try-it answer in each of its shapes, in the first card's answer area.
+ const rows = [{ path: "status", value: "ok", meaning: "`ok` when up" }];
+ const answers = [
+ lib.answerHtml(0, { status: 200, description: "Up.", rows, raw: '{"status":"ok"}' }),
+ lib.answerHtml(1, { status: 200, description: "The image.", rows: [], imageUrl: "blob:x", bytes: "9 bytes of image/png." }),
+ lib.answerHtml(2, { status: 200, description: "The log.", rows: [], summary: "3 lines of the run log.", raw: "{}" }),
+ ].join("");
+ const withAnswers = html.replace('', '' + answers + "
");
+ assert.ok(withAnswers.includes("blob:x"), "the answers were put in the page");
+ assert.deepEqual((await runAxe(withAnswers)).violations, []);
+ const r = await runAxe(html);
+ assert.deepEqual(r.violations, []);
+});