# AGENTS.md

## Project Overview

**covid data analysis** is a healthcare-focused data science project designed to build machine-learning models that support clinical decision-making for patients presenting with COVID-like symptoms. The project’s business context is hospital and care operations: helping clinicians and care teams evaluate when a patient should be admitted and, later, when they may be appropriate for discharge. The goal is to improve consistency, transparency, and reproducibility in decision support while ensuring that all modeling work remains traceable, testable, and aligned with healthcare data governance expectations.

## Architecture

### Project Directory Structure

This project uses a spec-driven layout:

```text
covid-data-analysis/
├── AGENTS.md
├── .gitignore
├── progress.md
├── requirements.txt
├── venv/
├── specs/
│   ├── 01-problem.md
│   ├── 02-data.md
│   ├── 03-data-cleaning.md
│   ├── 04-feature-engineering.md
│   ├── 05-model-development.md
│   ├── 06-evaluation.md
│   └── 07-reporting.md
├── data/
│   ├── raw/
│   ├── cleaned/
│   ├── features/
│   └── output/
├── notebooks/
│   ├── 01_eda.ipynb
│   ├── 02_feature_engineering.ipynb
│   └── 03_modeling.ipynb
├── src/
│   ├── __init__.py
│   ├── config.py
│   ├── logging_config.py
│   ├── pipeline.py
│   ├── data/
│   │   ├── __init__.py
│   │   ├── ingest.py
│   │   ├── clean.py
│   │   └── validate.py
│   ├── features/
│   │   ├── __init__.py
│   │   └── build_features.py
│   ├── models/
│   │   ├── __init__.py
│   │   ├── train.py
│   │   ├── predict.py
│   │   └── evaluate.py
│   └── utils/
│       ├── __init__.py
│       └── io.py
└── tests/
    ├── __init__.py
    └── test_data.py
```

### Data Flow

All data processing must follow this flow:

```text
source → raw → cleaned → features → model → output
```

* **source**: Original source systems, extracts, or manually provided datasets
* **raw**: Immutable copies of ingested source data
* **cleaned**: Standardized and quality-checked datasets
* **features**: Modeling-ready tables with explicit feature definitions
* **model**: Trained machine-learning artifacts and evaluation outputs
* **output**: Reports, predictions, summaries, and other downstream deliverables

## Coding Standards

* **Language**: Python 3.12+
* **Core libraries**:

  * `pandas==3.0.2`
  * `scikit-learn==1.8.0`
  * `numpy==2.4.4`
  * `pytest==9.0.3`
  * `jupyter==1.1.1`
* **Environment**:

  * Create and use a local virtual environment at `venv/`
  * Install dependencies from `requirements.txt`
  * The current local environment is expected to run on `python3.14`
  * If the active interpreter is not Python 3.12+, record that mismatch in `progress.md`
* **Style requirements**:

  * Follow PEP 8
  * Use type hints for public functions and methods
  * Use Google-style docstrings for modules, classes, and functions
* **Notebook conventions**:

  * Prefix notebooks with numeric ordering (for example, `01_eda.ipynb`)
  * Use clear markdown headers to separate sections
  * Remove dead code and unused cells before committing
  * Keep notebooks exploratory, but move reusable logic into `src/`
* **Logging**:

  * Use the Python `logging` module
  * Do not use `print()` for operational or pipeline output

## Data Conventions

* **Dates and times**:

  * Use ISO 8601 format
  * All timestamps must be timezone-aware
  * Default timezone is UTC unless explicitly specified otherwise
* **Missing values**:

  * Use `pd.NA`
  * Never fill missing values silently; every imputation or exclusion must be explicit and documented
* **Column naming**:

  * Use `snake_case`
  * Prefer descriptive names over abbreviations
  * Include units in column names where relevant
* **Transformation tracking**:

  * Every transformation must be documented in `progress.md`

## Spec Workflow

* Before executing any phase, read the relevant spec in `specs/`
* After completing a phase, update `progress.md` with findings, assumptions, and decisions
* Do not proceed to the next phase until the current spec's acceptance criteria are met
* When EDA reveals something that changes the problem spec, update `specs/01-problem.md`

## Testing

* Add data validation tests in `tests/test_data.py`
* Ensure pipeline reproducibility through fixed random seeds and pinned dependencies
* Never evaluate model performance on training data
* Keep train, validation, and test boundaries explicit and documented

## Common Commands

* `source venv/bin/activate` — activate the project virtual environment
* `pip install -r requirements.txt` — install project dependencies
* `python -m pytest tests/ -x -q` — run all tests
* `jupyter nbconvert --execute notebooks/*.ipynb` — execute notebooks
* `python -m src.pipeline` — run the full pipeline

## Additional Guidance for Agents

* Treat all healthcare-related data as sensitive and handle it with care
* Prefer transparent, interpretable baseline models before introducing more complex approaches
* Document admission and discharge target definitions explicitly before modeling
* Flag label leakage risks early, especially when using downstream clinical events or post-decision variables
* Record all modeling assumptions, feature eligibility rules, and exclusion criteria in `progress.md`
