docs/map/models.md

# Models Map — `replicalab/models.py`

> All Pydantic data contracts. Frozen with `extra="forbid"` unless noted.
>
> **Tasks implemented:** MOD 01, 02, 03, 04, 09, 11, 12

## Enums

### `ScientistActionType(str, Enum)`
| Value | Meaning |
|-------|---------|
| `propose_protocol` | First protocol submission |
| `revise_protocol` | Modify existing protocol |
| `request_info` | Ask lab manager a question |
| `accept` | Agree to current protocol |

### `LabManagerActionType(str, Enum)`
| Value | Meaning |
|-------|---------|
| `report_feasibility` | Report on feasibility without suggestions |
| `suggest_alternative` | Propose revised protocol |
| `reject` | Reject protocol outright |
| `accept` | Approve protocol |

## Action Models

### `ScientistAction(BaseModel)` — `extra="forbid"`
MOD 01 + MOD 09. Strict contract for scientist output.

| Field | Type | Constraint | Notes |
|-------|------|-----------|-------|
| `action_type` | `ScientistActionType` | required | |
| `sample_size` | `int` | `ge=0` | Must be `>=1` for propose/revise |
| `controls` | `list[str]` | normalized | |
| `technique` | `str` | stripped | Required for propose/revise |
| `duration_days` | `int` | `ge=0` | |
| `required_equipment` | `list[str]` | normalized | |
| `required_reagents` | `list[str]` | normalized | |
| `questions` | `list[str]` | normalized | Required non-empty for request_info |
| `rationale` | `str` | stripped | Required for propose/revise |

**Validation rules:**
- `propose_protocol` / `revise_protocol`: sample_size >= 1, technique required, rationale required, questions must be empty
- `request_info`: questions non-empty, no protocol payload fields
- `accept`: no questions, no protocol payload fields

### `LabManagerAction(BaseModel)` — `extra="forbid"`
MOD 02. Strict contract with feasible-flag consistency.

| Field | Type | Constraint | Notes |
|-------|------|-----------|-------|
| `action_type` | `LabManagerActionType` | required | |
| `feasible` | `bool` | required | Must equal AND of all constraint flags |
| `budget_ok` | `bool` | required | |
| `equipment_ok` | `bool` | required | |
| `reagents_ok` | `bool` | required | |
| `schedule_ok` | `bool` | required | |
| `staff_ok` | `bool` | required | |
| `suggested_technique` | `str` | stripped | Only for suggest_alternative |
| `suggested_sample_size` | `int` | `ge=0` | Only for suggest_alternative |
| `suggested_controls` | `list[str]` | normalized | Only for suggest_alternative |
| `explanation` | `str` | required non-empty | |

**Validation rules:**
- `feasible` must equal `all(budget_ok, equipment_ok, reagents_ok, schedule_ok, staff_ok)`
- `accept` requires `feasible=True`
- `reject` requires `feasible=False`
- `suggest_alternative` requires `feasible=False` + at least one suggestion field
- Suggestion fields forbidden for non-suggest_alternative actions

## Observation Models

### `ConversationEntry(BaseModel)` — `extra="forbid"`
| Field | Type | Notes |
|-------|------|-------|
| `role` | `Literal["scientist", "lab_manager", "system"]` | |
| `message` | `str` | Required non-empty |
| `round_number` | `int` | `ge=0` |
| `action_type` | `Optional[str]` | Null or non-empty |

### `Protocol(BaseModel)` — `extra="forbid"`
Shared protocol payload used in observations and actions.

| Field | Type | Notes |
|-------|------|-------|
| `sample_size` | `int` | `ge=0` |
| `controls` | `list[str]` | normalized |
| `technique` | `str` | required non-empty |
| `duration_days` | `int` | `ge=0` |
| `required_equipment` | `list[str]` | normalized |
| `required_reagents` | `list[str]` | normalized |
| `rationale` | `str` | required non-empty |

### `ScientistObservation(BaseModel)` — `extra="forbid"`
| Field | Type |
|-------|------|
| `paper_title` | `str` |
| `paper_hypothesis` | `str` |
| `paper_method` | `str` |
| `paper_key_finding` | `str` |
| `experiment_goal` | `str` |
| `conversation_history` | `list[ConversationEntry]` |
| `current_protocol` | `Optional[Protocol]` |
| `round_number` | `int` (ge=0) |
| `max_rounds` | `int` (ge=0) |

### `LabManagerObservation(BaseModel)` — `extra="forbid"`
| Field | Type |
|-------|------|
| `budget_total` | `float` (ge=0) |
| `budget_remaining` | `float` (ge=0) |
| `equipment_available` | `list[str]` |
| `equipment_booked` | `list[str]` |
| `reagents_in_stock` | `list[str]` |
| `reagents_out_of_stock` | `list[str]` |
| `staff_count` | `int` (ge=0) |
| `time_limit_days` | `int` (ge=0) |
| `safety_restrictions` | `list[str]` |
| `conversation_history` | `list[ConversationEntry]` |
| `current_protocol` | `Optional[Protocol]` |
| `round_number` | `int` (ge=0) |
| `max_rounds` | `int` (ge=0) |

### `Observation(BaseModel)` — `extra="forbid"`
Combined wrapper. Each role receives its own view.

| Field | Type |
|-------|------|
| `scientist` | `Optional[ScientistObservation]` |
| `lab_manager` | `Optional[LabManagerObservation]` |

## Reward & Step Models

### `RewardBreakdown(BaseModel)` — default `extra="forbid"`
MOD 11. Component scores from judge rubric engine.

| Field | Type | Default | Range |
|-------|------|---------|-------|
| `rigor` | `float` | 0.0 | [0, 1] |
| `feasibility` | `float` | 0.0 | [0, 1] |
| `fidelity` | `float` | 0.0 | [0, 1] |
| `efficiency_bonus` | `float` | 0.0 | unbounded |
| `communication_bonus` | `float` | 0.0 | unbounded |
| `penalties` | `dict[str, float]` | {} | unbounded |

### `StepInfo(BaseModel)` — `extra="allow"`
MOD 11. Extensible metadata returned with each step.

| Field | Type | Default |
|-------|------|---------|
| `agreement_reached` | `bool` | False |
| `error` | `Optional[str]` | None |
| `reward_breakdown` | `Optional[RewardBreakdown]` | None |
| `judge_notes` | `Optional[str]` | None |
| `verdict` | `Optional[str]` | None |

### `StepResult(BaseModel)`
| Field | Type | Default |
|-------|------|---------|
| `observation` | `Optional[Observation]` | None |
| `reward` | `float` | 0.0 |
| `done` | `bool` | False |
| `info` | `StepInfo` | StepInfo() |

## Episode Models

### `EpisodeState(BaseModel)` — MOD 04
Full internal state for debugging and replay.

| Field | Type | Default |
|-------|------|---------|
| `seed` | `int` | 0 |
| `scenario_template` | `str` | "" |
| `difficulty` | `str` | "easy" |
| `paper_title` | `str` | "" |
| `paper_hypothesis` | `str` | "" |
| `paper_method` | `str` | "" |
| `paper_key_finding` | `str` | "" |
| `experiment_goal` | `str` | "" |
| `lab_budget_total` | `float` | 0.0 |
| `lab_budget_remaining` | `float` | 0.0 |
| `lab_equipment` | `list[str]` | [] |
| `lab_reagents` | `list[str]` | [] |
| `lab_staff_count` | `int` | 0 |
| `lab_time_limit_days` | `int` | 0 |
| `current_protocol` | `Optional[Protocol]` | None |
| `conversation_history` | `list[ConversationEntry]` | [] |
| `round_number` | `int` | 0 |
| `max_rounds` | `int` | 0 |
| `done` | `bool` | False |
| `agreement_reached` | `bool` | False |
| `reward` | `float` | 0.0 |
| `rigor_score` | `float` | 0.0 |
| `feasibility_score` | `float` | 0.0 |
| `fidelity_score` | `float` | 0.0 |

### `EpisodeLog(BaseModel)` — MOD 04
Completed episode record for logging, replay, evaluation.

| Field | Type | Default |
|-------|------|---------|
| `episode_id` | `str` | "" |
| `seed` | `int` | 0 |
| `scenario_template` | `str` | "" |
| `difficulty` | `str` | "easy" |
| `final_state` | `Optional[EpisodeState]` | None |
| `transcript` | `list[ConversationEntry]` | [] |
| `reward_breakdown` | `Optional[RewardBreakdown]` | None |
| `total_reward` | `float` | 0.0 |
| `rounds_used` | `int` | 0 |
| `agreement_reached` | `bool` | False |
| `judge_notes` | `str` | "" |
| `verdict` | `str` | "" |

## Helper Functions

| Function | Purpose |
|----------|---------|
| `_normalize_string_list(value)` | Strip whitespace, reject empty strings |