FHIRy - FHIR to DataFrame Converter

Convert FHIR (Fast Healthcare Interoperability Resources) bundles and NDJSON files into pandas DataFrames for health data analytics, machine learning, and AI applications.

What This Skill Does

This skill helps you work with the FHIRy Python package, which processes healthcare data in FHIR format and converts it into structured pandas DataFrames. It supports FHIR server search, BigQuery integration, and LLM-based natural language queries for health data.

Development Environment

**Python Version**: Requires Python 3.10 or higher (tested on 3.10, 3.11, 3.12)

**Package Manager**: Uses `uv` for dependency management

**Setup**:

```bash

uv sync # Install all dependencies from pyproject.toml

```

Project Structure

```

src/fhiry/ # Main source code

├── fhiry.py # Core FHIR Bundle processor

├── fhirndjson.py # NDJSON file processor

├── fhirsearch.py # FHIR server search API integration

├── bqsearch.py # BigQuery FHIR dataset queries

├── flattenfhir.py # FHIR resource flattening logic

├── parallel.py # Parallel processing utilities

├── base_fhiry.py # Base class for FHIR processors

└── main.py # CLI entry point

tests/ # Test suite with pytest

docs/ # MkDocs documentation

examples/ # Usage examples

```

Code Style and Conventions

Python Standards

Type Checking Rules

Testing

**Framework**: pytest with coverage reporting

**Run Tests**:

```bash

uv run pytest --cov=src/fhiry tests/ # With coverage

uv run pytest tests/ # Without coverage

uv run pytest tests/test_specific.py # Specific test file

```

**Test Conventions**:

FHIR Domain Knowledge

Key Concepts

Data Processing

Core Dependencies

Instructions for AI Agent

When Working on FHIRy Code

1. **Always Run Tests Before Submitting**

```bash

uv run pytest --cov=src/fhiry tests/

```

2. **Respect FHIR Standards**

- Consult HL7 FHIR specification when handling resources

- Preserve nested structure semantics when flattening

- Test with real FHIR samples from `tests/resources/`

3. **Type Hints Are Required**

- Add type annotations to all function signatures

- mypy configuration enforces strict type checking

- No implicit optionals allowed

4. **Follow Existing Patterns**

- Check similar code before implementing new features

- Resource processors follow patterns in `base_fhiry.py`

- DataFrame output logic centralized in base class

5. **Adding New FHIR Resource Processors**

- Add processing logic in appropriate module (fhiry.py, fhirsearch.py, etc.)

- Follow existing flattening patterns

- Write tests with sample FHIR resources

- Update documentation for public API changes

6. **Modifying DataFrame Output**

- Changes go in `base_fhiry.py` or specific processor

- Test with various FHIR resource types

- Verify config JSON filtering still works

7. **Adding CLI Commands**

- Modify `src/fhiry/main.py`

- Use Click decorators

- Add tests in `tests/test_cli.py`

8. **Dependencies**

- Add to `dependencies` in `pyproject.toml`

- Run `uv sync` to update lock file

- Keep dependencies minimal

- Use `make check` to detect obsolete deps (deptry)

9. **Git Workflow**

- Target develop branch (never push directly to main)

- Pre-commit hooks enforce formatting (ruff)

10. **Key Files to Review**

- `pyproject.toml`: Dependencies, tool config, metadata

- `Makefile`: Build, test, and development commands

- `.pre-commit-config.yaml`: Formatting and linting config

- `CONTRIBUTING.md`: Contribution guidelines

- `README.md`: Public API and usage examples

Testing Requirements

Documentation Requirements

Common Tasks

**Add a new FHIR resource processor**: Follow patterns in `base_fhiry.py`, add type hints, write tests, update docs

**Modify DataFrame output**: Edit base class or specific processor, test with multiple resource types, verify config filtering

**Add CLI command**: Use Click in `src/fhiry/main.py`, add tests in `tests/test_cli.py`

Constraints