AGENTS.md

1# Project AI Instructions
2 
3## Project Overview
4 
5OpenLeukemia is a patient-centered platform for organizing leukemia-related medical data, tracking changes over time, extracting structured information from documents, and explaining validated model outputs in plain language.
6 
7The product must help patients understand their information without replacing a physician. Treat privacy, explicit consent, and non-diagnostic language as core requirements, not optional polish.
8 
9## Tech Stack
10 
11- Frontend: React 19, TypeScript, Vite, Vitest, ESLint
12- Platform layer: Supabase Auth, Postgres, Storage, Row Level Security, Edge Functions
13- AI service: Python 3.12, FastAPI, Pydantic, Uvicorn
14- AI/ML: PyTorch, XGBoost, scikit-learn, Gemma or another LLM for extraction and explanation tasks
15- Package manager: npm workspaces for the frontend; Python virtual environment for `ai-service`
16 
17## Repository Layout
18 
19- `frontend/`: React + TypeScript application
20- `ai-service/`: Python FastAPI service for ML, extraction, parsing, and model-facing workloads
21- `supabase/`: migrations, policies, storage-related platform logic, and Edge Functions
22- `ml/`: machine learning workspace
23- `docs/`: project documentation
24- `PROJECT_CHARTER.md`: product principles and guardrails
25- `ARCHITECTURE.md`: system design and data-flow guidance
26 
27## Setup
28 
29Install frontend dependencies from the repository root:
30 
31```sh
32npm install
33```
34 
35Create the AI-service virtual environment:
36 
37```sh
38cd ai-service
39python -m venv .venv
40python -m pip install -e ".[dev]"
41```
42 
43On Windows PowerShell, activate the environment with:
44 
45```powershell
46.\.venv\Scripts\Activate.ps1
47```
48 
49## Development
50 
51Run the frontend from the repository root:
52 
53```sh
54npm --workspace frontend run dev
55```
56 
57Default frontend URL:
58 
59```text
60http://127.0.0.1:5173
61```
62 
63Run the AI service from `ai-service/`:
64 
65```sh
66python -m uvicorn app.main:app --reload
67```
68 
69Default AI-service URL:
70 
71```text
72http://127.0.0.1:8000
73```
74 
75Health check:
76 
77```text
78http://127.0.0.1:8000/health
79```
80 
81## Tests And Checks
82 
83Frontend checks:
84 
85```sh
86npm run lint:frontend
87npm run typecheck:frontend
88npm test --workspace frontend
89npm --workspace frontend run build
90```
91 
92AI-service checks:
93 
94```sh
95cd ai-service
96python -m ruff check .
97python -m pytest
98python -m mypy app
99```
100 
101Makefile shortcuts:
102 
103```sh
104make frontend-lint
105make frontend-typecheck
106make ai-service-lint
107make ai-service-test
108```
109 
110Run the checks most relevant to the files you changed. If a check cannot be run, say why and name the command that should be run next.
111 
112## Code Style
113 
114- Follow the existing style in neighboring files before adding a new pattern.
115- Prefer clear names over clever names.
116- Keep functions small and responsibility-focused.
117- Add comments only when they genuinely reduce reading effort.
118- Use typed models and structured parsing instead of ad hoc string manipulation.
119- Do not add dependencies unless the local implementation would be materially worse without them.
120- Do not change public APIs, data contracts, routes, schemas, or consent behavior without an explicit reason.
121- Keep patient-facing copy calm, careful, and non-diagnostic.
122 
123## Architecture Rules
124 
125- Use Supabase for routine product workflows: auth, CRUD, storage, consent records, and access-control paths.
126- Keep Row Level Security and explicit consent central to data access.
127- Use the Python AI service only when the task genuinely needs Python, ML, parsing, OCR, extraction, or heavier compute.
128- Keep FastAPI route handlers thin. Put reusable Python logic in services and domain modules.
129- Keep frontend code feature-oriented and reuse existing UI, layout, and testing patterns.
130- Treat LLM output as explanation or candidate extraction, not as a medical decision.
131- High-risk extracted medical values should be reviewable before becoming canonical records.
132- Keep identity data and medical data conceptually separate.
133 
134## Product And Safety Rules
135 
136- Registration does not mean blanket consent.
137- Patient data belongs to the patient.
138- Every consent should be separate, explicit, auditable, and revocable.
139- AI may summarize and explain, but must not diagnose, recommend treatment, or make urgent clinical judgments.
140- Structured ML may support prediction and trend detection; LLMs may support extraction and explanation.
141- Prefer minimal collection for privacy-sensitive workflows.
142 
143## Frontend Rules
144 
145- Build mobile-first responsive layouts.
146- Maintain light and dark theme support.
147- Preserve accessible interaction patterns for menus, forms, dialogs, and controls.
148- Keep the public site lightweight; avoid unnecessary heavy animation, video, or large assets.
149- Keep brand color usage centered on red without making every surface the same hue.
150 
151## AI-Service Rules
152 
153- Use explicit Pydantic schemas for request and response bodies.
154- Keep domain behavior in `app/domains/`.
155- Keep route modules focused on HTTP concerns.
156- Maintain strict typing and pass `mypy` for `app`.
157- Keep model outputs explainable and non-diagnostic.
158 
159## AI Agent Behavior
160 
161- Read nearby code, tests, and documentation before editing.
162- Make minimal, focused changes that preserve existing architecture.
163- Do not rewrite unrelated files or clean up unrelated churn.
164- Respect uncommitted user changes.
165- Add or update tests when behavior changes.
166- After edits, run the most relevant checks when practical.
167- When touching medical, consent, auth, or privacy-sensitive behavior, be extra conservative and call out any residual risk.
168