ismailridwans/clarus

<div align="center">

🏥 Clarus

Healthcare Billing Dispute & Patient Advocacy Arena

   

An RL environment where an AI agent fights for wrongly-billed patients — graded by SQL checks against real CMS regulatory data.

</div>

Overview

Medical billing errors cost Americans $300 billion annually. One in five claims is denied on first submission. Clarus puts an AI agent in the role of a patient advocacy specialist tasked with:

• —Reconciling conflicting records across three independent parties (insurer, provider, payment processor)
• —Detecting regulatory violations against real CMS CPT, NCCI, and NSA data
• —Holding position under adversarial counter-pressure from the provider in Phase 2

Graded by deterministic SQL checks — no LLM-as-judge, no subjectivity.

Three Tasks

Task 1 — Deductive Liability

The agent fetches EOB, payment ledger, and plan document, then computes the correct patient balance and files a refund. The billing error is a copay that was never credited.

Task 2 — Abductive Conflict

Two insurer sources say the denial is legitimate. Two other sources override it. The agent must read all four before diagnosing. A TRAP check fires if the agent concludes legitimate_denial without consulting the NCCI modifier evidence.

Task 3 — Adversarial Fabrication (2-Phase)

• —Phase 1: Detect a backdated Good Faith Estimate by comparing provider_record.gfe_date to an independent processor_log.timestamp
• —Phase 2: Reject three authoritative counter-arguments injected after filing — EHR notes, a false NSA emergency exception claim, and a legal threat — and hold the dispute

Quick Start

# Clone and install
git clone https://huggingface.co/spaces/ismailridwans/clarus
cd clarus
pip install -r requirements.txt

# Start the server
uvicorn server.main:app --host 0.0.0.0 --port 7860

# Run all tests
pytest tests/ -v

# Run inference (requires HF token)
export HF_TOKEN=hf_...
python inference.py

Or use the live environment directly:

from client import ClarusClient

with ClarusClient("https://ismailridwans-clarus.hf.space") as env:
    obs = env.reset(task_name="deductive_liability", seed=1001)
    print(obs["patient_complaint"])

    result = env.step({
        "action_type": "authenticate_patient",
        "parameters": {"patient_id": obs["case_id"]}
    })
    print(result["reward"])  # +0.05

API Reference

Endpoints

Action Space

Observation Space

class ClarusObservation(BaseModel):
    step_number:             int
    api_calls_used:          int
    api_call_budget:         int                          # varies by task
    rate_limited_tools:      List[str]
    cooldown_steps:          Dict[str, int]
    case_id:                 str
    patient_complaint:       str
    patient_name:            str
    patient_emotional_state: Literal["calm", "frustrated", "distressed"]
    last_action_type:        Optional[str]
    last_action_result:      Optional[Dict]
    last_action_error:       Optional[str]
    action_log_summary:      List[str]
    step_reward:             float
    done:                    bool

Reward Structure

Per-Step (Structural)

Terminal (Episode Score)

episode_score = (passing_checks + 0.5) / (total_checks + 1.0)   ∈ (0, 1)

Standard Laplace smoothing. The score is determined only by how many SQL grader checks the agent passes — no artificial weights or caps. The formula is always strictly in (0, 1):

Data Sources

All grading uses real regulatory data — no synthetic rules.

Committed bundles in data/bundles/ cover all 15 training seeds. Builds work fully offline.

Baseline Performance

export HF_TOKEN=hf_...
export API_BASE_URL=https://router.huggingface.co/v1
export MODEL_NAME=Qwen/Qwen2.5-72B-Instruct
python inference.py

Heuristic fallback agent (no LLM, 5 dev seeds per task):

Scores use Laplace smoothing (passing + 0.5) / (total + 1), always strictly in (0, 1). Harder tasks require more domain-specific reasoning (NCCI modifiers, NSA Phase 2 rejections with correct artifact citations) that a generic heuristic misses — producing genuine score differentiation by difficulty.

Why Clarus is Unique

Architecture

┌─────────────────────────────────────────────┐
│                FastAPI Server                │
│  POST /reset  ·  POST /step  ·  GET /state  │
└──────────────────┬──────────────────────────┘
                   │
         ┌─────────▼─────────┐
         │    ClarusEnv       │
         │  Episode manager   │
         │  SQLite runtime DB │
         └─────────┬─────────┘
                   │
    ┌──────────────┼──────────────┐
    │              │              │
┌───▼───┐   ┌─────▼─────┐  ┌────▼────┐
│ Tools │   │ Scenario   │  │ Grader  │
│ reads │   │ generator  │  │ SQL     │
│ writes│   │ (seeded)   │  │ checks  │
└───────┘   └───────────┘  └─────────┘
                   │
         ┌─────────▼─────────┐
         │  Reference DB      │
         │  CPT · NCCI · NSA  │
         └───────────────────┘

<div align="center">

Clarus — making billing clear.

OpenEnv Hackathon · Customer Service Agents Track · April 2026

</div>