Arc Assist · Protearc Docs

Arc Assist

Arc Assist answers questions about one member's released results: what changed, by how much against their own baseline, and the laboratory's quality checks. It does not diagnose and does not advise on treatment.

Ask a question

POST /v1/members/{member_ref}/ask takes a question (1 to 2000 characters) and optionally history, up to 20 earlier turns, each {"role": "user" | "assistant", "content": "..."}. No other fields are accepted.

The fields:

answer: the text, or null when it is withheld (below).
citations: the lookups the answer was built from. numbers_checked counts the numbers in the answer that were matched to those lookups.
refused and reason: set when the question was declined (below). answer then holds the refusal text.
cards: ids of the proteins the answer used.
audit_event_id: the audit record of this question. Questions are audited by member and outcome, not by their text.

curl -X POST http://localhost:8000/v1/members/PA-0001/ask \
  -H "Authorization: Bearer ptk_sandbox_meridian_demo" \
  -H "Content-Type: application/json" \
  -d '{"question": "What changed since the first draw?", "history": []}'

import requests

r = requests.post(
    "http://localhost:8000/v1/members/PA-0001/ask",
    headers={"Authorization": "Bearer ptk_sandbox_meridian_demo"},
    json={"question": "What changed since the first draw?", "history": []},
)
answer = r.json()
print(answer["refused"], answer["answer"])

const r = await fetch("http://localhost:8000/v1/members/PA-0001/ask", {
  method: "POST",
  headers: {
    Authorization: "Bearer ptk_sandbox_meridian_demo",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ question: "What changed since the first draw?", history: [] }),
});
const answer = await r.json();
console.log(answer.refused, answer.answer);

json Response 200 (synthetic example)

{
  "answer": "The latest released draw is number 4. p-tau217 is higher than this member's baseline.",
  "citations": [{ "tool": "get_latest_report", "args": {} }],
  "numbers_checked": 1,
  "unverified_numbers": [],
  "refused": false,
  "reason": null,
  "model": "example-model",
  "cards": ["plasma_ptau217"],
  "audit_event_id": 1042,
  "withheld": false
}

What it answers

Only the released results of the member in the URL: what changed, by how much, and the laboratory's checks. It does not use draft or held results, and it never returns raw measurement series. Before an answer is returned, every number in it is checked against the lookups it cited. If one cannot be verified, the answer is withheld: answer is null, withheld is true, and unverified_numbers lists them.

What it declines

A declined question is a 200 with refused: true and one of these reasons.

`reason`	Declined because
`treatment_advice`	The question asks for a diagnosis or for treatment, medication or dosing.
`other_member`	The question names a different member than the one in the URL.
`off_topic`	It is not about this member's released results.
`no_released_data`	The member has no released results yet, or the latest result is on a quality-control hold.

An answer that itself reads as a diagnosis is replaced by the same treatment_advice refusal.

json Response 200, declined (synthetic example)

{
  "answer": "I can't diagnose or advise on treatment. I can show what changed for PA-0001, how large the change is against their own variation, and the lab's quality checks.",
  "citations": [],
  "numbers_checked": 0,
  "unverified_numbers": [],
  "refused": true,
  "reason": "treatment_advice",
  "model": null,
  "cards": [],
  "audit_event_id": 1043,
  "withheld": false
}

When it is not available

Status	`detail`	Meaning
`403`	`arc_assist_off`	Arc Assist is not turned on for your organization.
`403`	`assistant_off`	It is not live for your organization: it is switched off in Arc Watch under Settings, or Protearc has not made it available yet.
`503`	`unavailable`	The assistant could not answer right now, for example no model is configured or its budget is spent.
`404`	`not found`	The member does not exist or is not yours.

These are audited too. See Errors for the shape of every error.