Skip to content

Commit 3d4d7bc

Browse files
ilarsfilarsf
committed
Publish the standalone Python and R learner exercise
0 parents  commit 3d4d7bc

71 files changed

Lines changed: 6181 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/pipeline-review/SKILL.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
name: pipeline-review
3+
description: Review changes to this synthetic BMI pipeline against its documented data contract and independent test cases. Use for a requested pipeline review, not general prose edits or unrelated repositories.
4+
---
5+
6+
Resolve all repository-relative paths below from the project root containing `AGENTS.md`.
7+
8+
Read the applicable repository instructions, `docs/reference/io_contract.md`, the requested diff, and the relevant tests. The method is a teaching specification; do not invent a clinical interpretation or replace the agreed thresholds.
9+
10+
Trace changed behavior from inputs to selected encounters, flags, run status, and recorded artifacts. Useful failure cases include repeated demographics keys, tied measurements, missing values, equality at thresholds, and a run that fails after initialization. Use only the cases relevant to the requested change.
11+
12+
For the workshop exclusion report, read `docs/lessons/02-specify.md` and compare the report with the six-row example. There are three excluded measurements, with missing height on two and missing weight on two. Check that the report explains the overlap and summarizes all actual reasons. Usable measurements not chosen as a person's representative are not exclusions. Preserve existing cleaning and CLI behavior.
13+
14+
Identify the selected language from the task and changed files: Python uses `src/pgacg/`, and R uses `R/` with `scripts/r/demo.R`. When execution is available and within scope, run relevant tests (`python -m pytest` or `Rscript tests/r/run_tests.R`) and inspect the small-example reports. Review the meaning and counts rather than prescribing function names or report wording. If tools are restricted to reading, inspect supplied evidence and identify checks as unrun. Never claim agreement with another agent or the other language's implementation establishes scientific validity.
15+
16+
Return concrete findings with a file location, a small synthetic reproducing case, expected behavior, actual behavior, and impact. Separate observed defects from uncertainties and optional improvements. Do not edit files as part of a review unless the user requests fixes.

‎.codex/agents/pipeline-reviewer.toml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
name = "pipeline-reviewer"
2+
description = "Review the synthetic BMI pipeline against its documented contract."
3+
sandbox_mode = "read-only"
4+
developer_instructions = """
5+
Resolve repository paths from the project root containing AGENTS.md.
6+
Read AGENTS.md and docs/reference/io_contract.md.
7+
Use the pipeline-review skill when reviewing a pipeline change.
8+
Inspect the requested code and tests without editing files.
9+
Report behavior discrepancies with file locations, a minimal synthetic example,
10+
and the expected result. Distinguish verified findings from open questions.
11+
Run checks only if the effective tools and permissions permit them;
12+
otherwise state which supplied results you inspected and which checks are unrun.
13+
"""

‎.codex/config.toml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Shared settings for the local teaching exercise.
2+
# See https://ilarsf.github.io/practical-genai-agentic-coding-guide/docs/platforms/codex.html for trust, overrides, and permission profiles.
3+
approval_policy = "on-request"
4+
sandbox_mode = "workspace-write"
5+
6+
[sandbox_workspace_write]
7+
network_access = false

‎.gitattributes‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Keep teaching inputs and their recorded checksums consistent across platforms.
2+
* text=auto eol=lf
3+
*.png binary
4+
*.jpg binary
5+
*.woff binary
6+
*.woff2 binary

‎.github/copilot-instructions.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# GitHub Copilot custom instructions (repo-wide)
2+
3+
Read `AGENTS.md` for the shared repository instructions and `REPO_MAP.md` for
4+
entrypoints. Follow those files when implementing, testing, or documenting a change.
5+
6+
Use only synthetic examples. Keep generated runs ignored by Git, whether they use
7+
the default `runs/` directory or another explicitly requested `--runs_dir`.
8+
After behavioral changes, run the checks in `AGENTS.md` and report the actual results.

‎.github/instructions/python_pgacg.instructions.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
applyTo: "src/pgacg/**"
3+
---
4+
5+
When editing Python code under src/pgacg:
6+
- prefer small pure functions
7+
- update or add pytest tests
8+
- keep output schemas stable unless explicitly changing contracts (update docs/reference/io_contract.md)

‎.github/workflows/ci.yml‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
name: Exercise checks
2+
3+
on:
4+
push:
5+
pull_request:
6+
7+
jobs:
8+
test:
9+
runs-on: ubuntu-latest
10+
strategy:
11+
matrix:
12+
python-version: ["3.10", "3.12"]
13+
steps:
14+
- uses: actions/checkout@v6
15+
- uses: actions/setup-python@v6
16+
with:
17+
python-version: ${{ matrix.python-version }}
18+
cache: pip
19+
- name: Install dependencies
20+
run: python -m pip install -r requirements-dev.txt
21+
- name: Check baseline and style
22+
run: |
23+
python -m pytest
24+
python -m ruff check .
25+
python scripts/py/check_example_data.py
26+
- name: Run documented baseline
27+
run: python -m pgacg demo --ehr data/example/ehr_bmi_simulated_data.tsv --demo data/example/demographics_simulated_data.tsv --run_id ci-baseline
28+
29+
r-and-parity:
30+
runs-on: ubuntu-latest
31+
steps:
32+
- uses: actions/checkout@v6
33+
- uses: actions/setup-python@v6
34+
with:
35+
python-version: "3.12"
36+
cache: pip
37+
- uses: r-lib/actions/setup-r@v2
38+
with:
39+
r-version: "4.6.1"
40+
- name: Install both demo environments
41+
run: |
42+
python -m pip install -r requirements-dev.txt
43+
Rscript scripts/r/install_dependencies.R
44+
- name: Check the R baseline
45+
run: Rscript tests/r/run_tests.R
46+
- name: Run the documented R demo
47+
run: Rscript scripts/r/demo.R --ehr data/example/ehr_bmi_simulated_data.tsv --demo data/example/demographics_simulated_data.tsv --run_id ci-r-baseline
48+
- name: Compare Python and R outputs
49+
run: python scripts/py/check_language_parity.py
50+
51+
synthetic-fixtures:
52+
runs-on: ubuntu-latest
53+
steps:
54+
- uses: actions/checkout@v6
55+
- uses: actions/setup-python@v6
56+
with:
57+
python-version: "3.12"
58+
- uses: r-lib/actions/setup-r@v2
59+
with:
60+
r-version: "4.6.1"
61+
- name: Install the simulator dependency
62+
run: Rscript -e 'install.packages("optparse", repos = "https://cloud.r-project.org")'
63+
- name: Regenerate synthetic teaching inputs
64+
run: |
65+
Rscript scripts/r/simulate_ehr_data.R --output_ehr tmp/regenerated/ehr_bmi_simulated_data.tsv --output_ehr_dict tmp/regenerated/data_dictionary.txt --output_demo tmp/regenerated/demographics_simulated_data.tsv --output_demo_dict tmp/regenerated/demographics_data_dictionary.txt --seed 123 --n_individuals 12
66+
python scripts/py/check_example_data.py --directory tmp/regenerated

‎.gitignore‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# ---- Generated outputs / artifacts ----
2+
runs/
3+
tmp/
4+
*.log
5+
6+
# ---- Data (keep small synthetic examples only) ----
7+
data/raw/
8+
data/derived/
9+
# NOTE: data/example/ is tracked
10+
11+
# ---- OS files ----
12+
.DS_Store
13+
Thumbs.db
14+
15+
# ---- Editor / IDE ----
16+
.vscode/
17+
.idea/
18+
*.swp
19+
*.swo
20+
*~
21+
22+
# ---- Python caches / tooling ----
23+
__pycache__/
24+
*.py[cod]
25+
.pytest_cache/
26+
.mypy_cache/
27+
.ruff_cache/
28+
.coverage
29+
.coverage.*
30+
dist/
31+
build/
32+
*.egg-info/
33+
34+
# ---- Virtual environments ----
35+
.venv/
36+
venv/
37+
38+
# ---- R session and local library state ----
39+
.Rhistory
40+
.RData
41+
.Ruserdata
42+
.Rproj.user/
43+
.Rlib/
44+
45+
# ---- Local secrets / env overrides ----
46+
.env
47+
.env.*
48+
49+
# ---- Shared agent setup; keep runtime state and personal additions local ----
50+
.codex/*
51+
!.codex/config.toml
52+
!.codex/agents/
53+
.codex/agents/*
54+
!.codex/agents/pipeline-reviewer.toml
55+
.agents/*
56+
!.agents/skills/
57+
.agents/skills/*
58+
!.agents/skills/pipeline-review/
59+
.claude/settings.local.json

‎AGENTS.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# AGENTS.md
2+
3+
Help the learner make and verify one reporting change in the synthetic BMI pipeline.
4+
5+
## Start with the learner's path
6+
7+
Read `README.md` and `REPO_MAP.md`, then follow `docs/paths/python/` or `docs/paths/r/` for the language the learner selected. Read relevant files before editing and use `rg` to locate code. When asked for an explanation without edits, inspect and explain before proceeding.
8+
9+
## Keep the exercise focused
10+
11+
- Work in the selected language: `src/pgacg/` for Python, or `R/` and `scripts/r/` for R.
12+
- Use the existing flagged rows to build the exclusion report. Preserve cleaning rules, selected records, data tables, CLI behavior, and dependencies.
13+
- Treat each input row as one measurement. A flagged measurement can have several reasons; count it once in the excluded total and once under each applicable reason.
14+
- Keep functions small and testable, with I/O in CLI/reporting layers. Use type hints and `pathlib.Path` in Python; keep R functions sourceable and use `file.path()`.
15+
- Preserve unrelated work. If another agent is working in parallel, agree on separate file ownership.
16+
- Ask when the request leaves a scientific method, public schema, CLI behavior, or access decision unresolved. Explain a plan when the approach is unclear or the work is substantial.
17+
18+
## Use synthetic data
19+
20+
Use only the included synthetic fixtures or small synthetic cases. Never add real patient or participant records, PHI, PII, or credentials to files or agent context. These simplified pipeline rules are teaching specifications, not clinical recommendations.
21+
22+
Outputs, logs, paths, and screenshots can disclose information. This pipeline does not de-identify data or redact saved paths and errors. See `docs/reference/lab-data-policy.md` before adapting the workflow to study data.
23+
24+
`runs/`, `tmp/`, `data/raw/`, `data/derived/`, `.venv/`, and caches are generated. Keep them out of commits. Ignore rules and instruction files do not grant access; follow the client's effective permissions. Keep credentials and personal client settings out of the repository.
25+
26+
## Verify the change
27+
28+
Run the selected language's checks. Python:
29+
30+
```bash
31+
python -m pytest
32+
python -m ruff check .
33+
```
34+
35+
R:
36+
37+
```bash
38+
Rscript tests/r/run_tests.R
39+
```
40+
41+
Use Lesson 4's commands for both six-row fixtures. Compare the summaries with `docs/lessons/02-specify.md`: 3 of 6 excluded with missing height on 2 and missing weight on 2, an overlap explanation, and 0 of 6 excluded for complete data. Compare the cleaned and flagged outputs with the saved baseline. The larger demo, extra report tests, and documentation updates are optional follow-ups.
42+
43+
Review the actual diff and open new files too. For a requested pipeline review, use `.agents/skills/pipeline-review/SKILL.md`; it is optional for the learner's own review. The data contract is `docs/reference/io_contract.md`.
44+
45+
Finish with a short handoff: what changed, commands actually run and their results, and anything unfinished or untested. Passing tests or agreement between agents does not establish scientific validity. Do not publish, deploy, or modify external services without authorization.

‎CITATION.cff‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
cff-version: 1.2.0
2+
message: "If you use this teaching exercise, please cite this repository."
3+
title: "Practical GenAI Agentic Coding Example: Synthetic BMI reporting exercise"
4+
abstract: "Runnable Python and R exercise for Part 2 of the Fritsche Lab Practical GenAI series: make a bounded reporting change, verify it with synthetic data, review the diff, and leave a handoff."
5+
authors:
6+
- family-names: "Fritsche"
7+
given-names: "Lars G."
8+
affiliation: "University of Michigan"
9+
website: "https://fritschelab.org/"
10+
repository-code: "https://github.com/ilarsf/practical-genai-agentic-coding-example"
11+
url: "https://ilarsf.github.io/practical-genai-agentic-coding-guide/"
12+
license: "GPL-3.0-only"
13+
keywords:
14+
- "agentic coding"
15+
- "generative AI"
16+
- "reproducible research"
17+
- "research software"
18+
- "teaching"

0 commit comments

Comments
 (0)