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.