feat: Adding a clinical trial agent notebook including test data

[Hipnozata]

feat: Adding a sample for HCLS specifically clinical trials matching agent. The agent works with randomly generated patient profiles and matches them to publicly available clinical trials. Included in the folder you can find an necessary requirements, the generated data and a notebook with the code itself.

[scouturier]

Thanks for this contribution, @Hipnozata — the clinical-trial matching agent is a great addition! 🙌

One small suggestion before merge: the notebook and README pin anthropic.claude-sonnet-4-20250514-v1:0 (Claude Sonnet 4). Since then the lineup has moved on, so it'd be worth updating to the current Claude Sonnet 5 (claude-sonnet-5) so the sample stays current for readers.

(No rush — happy to help if useful.)

[Hipnozata]

@scouturier just updated with the newest model, nice catch! Looking forward to seeing it go public :)

[scouturier]

Thanks @Hipnozata. I did a thorough pass and also ran the notebook end-to-end against Bedrock in us-east-1. The overall design is sound, but there's a set of items to address before merge — mostly correctness/safety details in the eligibility logic, plus one that stops the notebook running on a clean install. Summarizing here so you have the full picture, with specifics inline. Where I note "confirmed by running it," that's observed behavior from the live run, not just a code read.

Should fix before merge (correctness / safety):

1. Notebook fails on a clean install — BedrockModel is created with no max_tokens, and requirements.txt pins strands-agents>=0.1.0 (unbounded). A fresh install pulls current strands, and the flagship agent("Match trials for patient P-001") cell raises MaxTokensReachedException before producing output. Setting an explicit max_tokens (8192 worked for me) and bounding the strands pin fixes it — confirmed by running it.
2. Inverted exclusion logic — aggregate_verdict returns not_eligible when a patient passes an exclusion (i.e. is not excluded), the opposite of the prompt's convention. Confirmed by running it: every result came back not_eligible even when all criteria passed.
3. Fabricated eligibility criteria in Quick Start — _transform_study drops the API's eligibilityModule, and the KB is off by default, so the agent infers criteria from the trial title rather than real ones. Confirmed by running it: all retrieve_trial_kb calls returned KB_NOT_CONFIGURED and the reasoning cited only title-derived criteria.
4. Parse failure defaults to eligible — an empty criteria parse yields a confident eligible match with zero criteria; safer as needs_review.
5. overall_match_score is never computed — it's the ranking key (and the README's "Score: 92%"), but it's pure LLM free-text.
6. Biomarker borderline check is dead — shipped values are unit-bearing ("30%", "850 pg/mL"), which fail _is_numeric, so the "within 10% of cutoff" rule never fires.
7. Quick Start clone URL 404s — points at a repo that doesn't exist.

With all seven addressed, the notebook runs clean end-to-end (I verified the runtime path once max_tokens was set), so this should be the last correctness pass.

Nice to tidy up (non-blocking):

• A few unrelated changes rode along (LICENSE year bumps in other folders, a package.json/yarn.lock dep removal, a next-env.d.ts edit) — worth splitting into a separate housekeeping PR.

Happy to help with any of these.

[scouturier]

Inverted exclusion logic (should fix). The prompt defines an exclusion "pass" as the patient does NOT meet the exclusion — i.e. a good outcome — and "fail" as the patient MEETS the exclusion (should be excluded). This branch returns not_eligible on exclusion "pass", and nothing acts on exclusion "fail", so the result is exactly backwards: patients who clear an exclusion are marked ineligible, while patients who actually hit an exclusion pass through.

Confirmed by running it: every match for P-001 came back not_eligible even though all criteria were pass/unknown with no fail — the exclusion "pass" entries flipped the verdict.

Suggest flipping to outcome == "fail" for the exclusion branch, and updating the docstring rules + the cell's assert aggregate_verdict([{"type": "exclusion", "outcome": "pass"}]) == "not_eligible" (it currently encodes the inverted convention).

[scouturier]

Fabricated eligibility criteria in the default path (should fix). _transform_study returns only nct_id/title/phase/status/conditions/locations and never reads protocolSection.eligibilityModule.eligibilityCriteria, which the ClinicalTrials.gov v2 response already includes (the request sets no fields filter). Since retrieve_trial_kb is disabled in Quick Start (KNOWLEDGE_BASE_ID=""), the agent has no factual source of criteria and infers them from the trial title.

Suggest carrying eligibilityCriteria through here and parsing it with split_eligibility_criteria (used in setup_knowledge_base.ipynb; it'll need to be copied into this notebook since notebooks don't share a namespace), then surfacing the parsed inclusion/exclusion lists in the tool output so the agent evaluates real criteria.

[scouturier]

Empty criteria defaults to eligible (should fix). When _parse_criteria_response can't extract JSON it returns [], and an empty list reaches this line with has_unknown still False — so a malformed model response becomes a confident eligible verdict with zero criteria evaluated. For a clinical-eligibility tool the fail-safe should be needs_review.

Suggest an early guard (if not criteria: return "needs_review") or detecting the empty parse in evaluate_eligibility. Worth also wrapping the json.loads calls in the regex branches of _parse_criteria_response, which can raise JSONDecodeError uncaught.

[scouturier]

overall_match_score is never computed (should fix). It's the ranking key here (and appears as "Score: 92%" in the README), and the output contract declares it a float in [0, 1] — but no code produces it. EligibilityAssessment.to_dict() returns only overall_verdict/criteria/borderline_flag, and display_results just reads result.get("overall_match_score", 0) straight from the model's free-text output. So the value that orders the top-5 results is an ungrounded LLM number in an otherwise deterministic pipeline.

Suggest computing it deterministically from the criterion outcomes and writing it into the assessment dict so the ranking is grounded.

[scouturier]

Biomarker borderline check is effectively dead (should fix). The shipped patient profiles store unit-bearing biomarker values ("lvef": "30%", "bnp": "850 pg/mL", "hba1c": "8.2%"). _is_numeric("30%") is False, so this guard continues for every unit-bearing value and the "within 10% of a numeric cutoff" logic never runs — only the age rule can trigger a borderline flag, despite the README advertising the biomarker case.

Suggest stripping units before the numeric compare, or storing numeric values with a separate units field (more robust against unit mismatch between patient value and threshold).

[scouturier]

Unbounded strands-agents pin (should fix — pairs with the max_tokens fix). >=0.1.0 has no upper bound, so a fresh install resolves to whatever strands is current (1.45.x today), whose max_tokens handling differs from whatever this notebook was authored against — which is how the primary demo cell ends up raising MaxTokensReachedException. Suggest pinning to a tested range you've verified, e.g. strands-agents>=1.0,<2.0 (adjust to whatever you confirm works), so the sample is reproducible over time.