name: narada
version: "1.0.0"
description: >
  Narada: LLM agent navigates a 55,000-node gene-disease knowledge graph
  (ClinVar + HPO) to diagnose rare disease patients. The agent must cross-reference
  patient phenotypes against candidate variants, follow causal chains across the
  graph, and resist high-pathogenicity decoy variants unrelated to the patient's
  phenotype. Three task tiers: monogenic (easy), oligogenic (medium),
  phenotype_mismatch (hard). Adversarial curriculum generation is documented as
  future work, not part of the current scored environment.
author: KrishVenky
license: MIT
sdk: docker
tags:
  - openenv
  - rare-disease
  - genomics
  - graph-navigation
  - rl
  - llm-agent
  - robustness
python_package: src/envs/narada
entry_point: narada.server.app:app
hardware: cpu-basic
space_url: "https://krishvenky-narada-env.hf.space"
env:
  PORT: "7860"
  HOST: "0.0.0.0"
  WORKERS: "1"
tasks:
  - id: monogenic
    difficulty: easy
    max_steps: 15
    description: >
      Single causal pathogenic variant. 3-4 HPO phenotype terms. Graph path
      is 4-8 hops. Minimal distractors. Tests basic directional reasoning:
      follow phenotype → disease → gene → variant chain.
    grader: signed_raw_reward mapped to OpenEnv score; correct_flag + timing_bonus + overseer_score
    reward_range: [0.01, 0.99]
  - id: oligogenic
    difficulty: medium
    max_steps: 25
    description: >
      2 contributing variants, one per gene, across different genes. 5-7
      phenotype terms spanning two organ systems. Agent must find all variants
      within the step budget. Tests multi-objective tracking across long
      trajectories and holding multiple simultaneous hypotheses.
    grader: signed_raw_reward mapped to OpenEnv score; partial_credit_per_variant + timing_bonus + overseer_score
    reward_range: [0.01, 0.99]
  - id: phenotype_mismatch
    difficulty: hard
    max_steps: 20
    description: >
      A high-pathogenicity BRCA1/BRCA2/TP53 frameshift variant is in the
      candidate pool as a deliberate decoy. The patient's phenotypes are
      entirely cardiac or neurological. The actual causal variant is a
      lower-pathogenicity gene specific to the presenting phenotype.
      Tests causal discipline: resist the highest-salience signal when it
      is phenotypically irrelevant. Most untrained LLMs fail this task.
    grader: signed_raw_reward mapped to OpenEnv score; cardiac_flag * 1.0 - decoy_flag * 0.5 + overseer_score
    reward_range: [0.01, 0.99]
observation_space:
  type: object
  fields:
    step: integer
    max_steps: integer
    task_type: string
    current_node: GraphNode
    trail: list[GraphNode]
    patient_phenotypes: list[string]
    phenotype_names: list[string]
    phenotypes_absent: list[string]
    phenotype_absent_names: list[string]
    candidate_variants: list[Variant]
    step_reward: float
    cumulative_reward: float
    done: boolean
    info: object
action_space:
  type: object
  fields:
    action_type: string
    node_id: string
    variant_id: string
    test_type: string
    reasoning: string
  constraints:
    - "action_type in [hop, flag_causal, backtrack, request_lab, summarise_trail]"
    - "node_id required when action_type=hop"
    - "variant_id required when action_type=flag_causal"