README.md

Clarity Ops — Two-Phase Medical Analytics Engine

This repo implements a universal, scenario-agnostic medical analytics workflow:

1. Phase 1: Clarification Questions (<=5, grouped by category)
2. Phase 2: Structured Analysis (schema-validated, unit-checked, math-verified, policy-aligned)

The engine never invents data. If inputs are missing/ambiguous, it asks for clarifications first.

Quick start

1. Populate a scenario in /packs/<scenario>/ (see /packs/mdsi as an example).
2. (Optional) Put known answers to clarifications in clarifications.json.
3. Run the pipeline (pseudo-call in your orchestration):
   • run_two_phase.run_clarityops("packs/mdsi")
4. Review the final JSON. It passes:
   • JSON Schema validation
   • Unit/range checks
   • Math consistency
   • Policy/constraints adherence
5. (Optional) Compare against /packs/<scenario>/expected.json with the rule-based grader.

Folder overview

• /core: Global medical rules (units, ranges, privacy)
• /prompts: System + two-phase user template
• /schemas: Output schema for Phase 2
• /validators: Hard guardrails (schema/units/math/policy)
• /graders: Rule-based grader for gold answers
• /pipeline: Two-phase orchestration
• /packs/<scenario>: Scenario Pack (inputs, constraints, schema selection, rubric, expected)

Notes

• This repo shows reference Python code for validators and pipeline. Hook the prompts into your LLM runner of choice.
• All numbers are examples unless your scenario pack provides them.