# yahskapar/personal-health-insights-agent architecture

> Architecture diagram of the GitHub repository yahskapar/personal-health-insights-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yahskapar/personal-health-insights-agent
- Repository: https://github.com/yahskapar/personal-health-insights-agent

## Overview

PHIA is a research prototype that answers questions about wearable activity, sleep, and wellness using a ReAct LLM agent. The main workflow is to load a user’s summary and activity data, ask a question in the demo, and let the agent analyze the data with Python and optionally search the web before returning an answer. Few-shot notebooks guide the agent; evaluation artifacts and figure notebooks support the paper’s research results. The runtime links are grounded in sampled source; evaluation and figure wiring is only documented at a high level.

Main entry points: [`phia_agent.py`](https://github.com/yahskapar/personal-health-insights-agent/blob/main/phia_agent.py) (ReAct agent), [`phia_demo.ipynb`](https://github.com/yahskapar/personal-health-insights-agent/blob/main/phia_demo.ipynb) (PHIA demo), [`data/auto_eval`](https://github.com/yahskapar/personal-health-insights-agent/tree/main/data/auto_eval) (Evaluation results), [`data_utils.py`](https://github.com/yahskapar/personal-health-insights-agent/blob/main/data_utils.py) (Wearable data loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User Interaction"]
  node_demo["PHIA demo<br/>[phia_demo.ipynb]"]
end

subgraph group_runtime["Agent Runtime"]
  node_agent["ReAct agent<br/>[phia_agent.py]"]
  node_prompt["Prompts and exemplars"]
  node_executor["Python data tool<br/>[phia_agent.py]"]
  node_search["Web search tool<br/>[phia_agent.py]"]
  node_loader["Wearable data loader<br/>[data_utils.py]"]
end

subgraph group_research["Research Artifacts"]
  node_fewshots["Few-shot examples"]
  node_synthetic[("Synthetic users")]
  node_real[("Deidentified users")]
  node_queries["Query sets"]
  node_openqueries["Open-ended queries"]
  node_eval["Evaluation results"]
  node_human["Human annotations"]
  node_figures["Paper figures"]
end

node_user(("Wearable-data user"))
node_tavily{{"Tavily search"}}

node_user -->|"asks question"| node_demo
node_demo -->|"loads data"| node_loader
node_loader -->|"reads files"| node_synthetic
node_loader -->|"reads files"| node_real
node_demo -->|"invokes"| node_agent
node_agent -->|"sets prompt"| node_prompt
node_prompt -->|"loads examples"| node_fewshots
node_agent -->|"dispatches code"| node_executor
node_executor -->|"analyzes data"| node_demo
node_agent -.->|"dispatches search"| node_search
node_search -.->|"queries"| node_tavily
node_agent -->|"returns answer"| node_demo
node_queries -->|"evaluated in"| node_eval
node_openqueries -->|"evaluated in"| node_eval
node_human -->|"labels outputs"| node_eval
node_eval -->|"informs figures"| node_figures

click node_demo "https://github.com/yahskapar/personal-health-insights-agent/blob/main/phia_demo.ipynb"
click node_agent "https://github.com/yahskapar/personal-health-insights-agent/blob/main/phia_agent.py"
click node_prompt "https://github.com/yahskapar/personal-health-insights-agent/blob/main/prompt_templates.py"
click node_executor "https://github.com/yahskapar/personal-health-insights-agent/blob/main/phia_agent.py"
click node_search "https://github.com/yahskapar/personal-health-insights-agent/blob/main/phia_agent.py"
click node_loader "https://github.com/yahskapar/personal-health-insights-agent/blob/main/data_utils.py"
click node_fewshots "https://github.com/yahskapar/personal-health-insights-agent/tree/main/few_shots"
click node_synthetic "https://github.com/yahskapar/personal-health-insights-agent/tree/main/synthetic_wearable_users"
click node_real "https://github.com/yahskapar/personal-health-insights-agent/tree/main/real_wearable_users"
click node_queries "https://github.com/yahskapar/personal-health-insights-agent/blob/main/Objective%20Query%20-%20PHIA.xlsx"
click node_openqueries "https://github.com/yahskapar/personal-health-insights-agent/blob/main/Open-Ended%20Query%20-%20PHIA.xlsx"
click node_eval "https://github.com/yahskapar/personal-health-insights-agent/tree/main/data/auto_eval"
click node_human "https://github.com/yahskapar/personal-health-insights-agent/tree/main/data/human_label_experiments"
click node_figures "https://github.com/yahskapar/personal-health-insights-agent/tree/main/figs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_demo,node_user toneBlue
class node_agent,node_prompt,node_executor,node_search,node_loader toneAmber
class node_fewshots,node_synthetic,node_real,node_queries,node_openqueries,node_eval,node_human,node_figures toneMint
class node_tavily toneIndigo
```

## Components

### User Interaction

- [PHIA demo](https://github.com/yahskapar/personal-health-insights-agent/blob/main/phia_demo.ipynb): `phia_demo.ipynb`

### Agent Runtime

- [ReAct agent](https://github.com/yahskapar/personal-health-insights-agent/blob/main/phia_agent.py): `phia_agent.py`
- [Prompts and exemplars](https://github.com/yahskapar/personal-health-insights-agent/blob/main/prompt_templates.py): `prompt_templates.py`
- [Python data tool](https://github.com/yahskapar/personal-health-insights-agent/blob/main/phia_agent.py): `phia_agent.py`
- [Web search tool](https://github.com/yahskapar/personal-health-insights-agent/blob/main/phia_agent.py): `phia_agent.py`
- [Wearable data loader](https://github.com/yahskapar/personal-health-insights-agent/blob/main/data_utils.py): `data_utils.py`

### Research Artifacts

- [Few-shot examples](https://github.com/yahskapar/personal-health-insights-agent/tree/main/few_shots): `few_shots`
- [Synthetic users](https://github.com/yahskapar/personal-health-insights-agent/tree/main/synthetic_wearable_users): `synthetic_wearable_users`
- [Deidentified users](https://github.com/yahskapar/personal-health-insights-agent/tree/main/real_wearable_users): `real_wearable_users`
- [Query sets](https://github.com/yahskapar/personal-health-insights-agent/blob/main/Objective%20Query%20-%20PHIA.xlsx): `Objective Query - PHIA.xlsx`
- [Open-ended queries](https://github.com/yahskapar/personal-health-insights-agent/blob/main/Open-Ended%20Query%20-%20PHIA.xlsx): `Open-Ended Query - PHIA.xlsx`
- [Evaluation results](https://github.com/yahskapar/personal-health-insights-agent/tree/main/data/auto_eval): `data/auto_eval`
- [Human annotations](https://github.com/yahskapar/personal-health-insights-agent/tree/main/data/human_label_experiments): `data/human_label_experiments`
- [Paper figures](https://github.com/yahskapar/personal-health-insights-agent/tree/main/figs): `figs`

### Other components

- **Wearable-data user**
- **Tavily search**

## Connections

- Wearable-data user → PHIA demo: asks question
- PHIA demo → Wearable data loader: loads data
- Wearable data loader → Synthetic users: reads files
- Wearable data loader → Deidentified users: reads files
- PHIA demo → ReAct agent: invokes
- ReAct agent → Prompts and exemplars: sets prompt
- Prompts and exemplars → Few-shot examples: loads examples
- ReAct agent → Python data tool: dispatches code
- Python data tool → PHIA demo: analyzes data
- ReAct agent → Web search tool: dispatches search
- Web search tool → Tavily search: queries
- ReAct agent → PHIA demo: returns answer
- Query sets → Evaluation results: evaluated in
- Open-ended queries → Evaluation results: evaluated in
- Human annotations → Evaluation results: labels outputs
- Evaluation results → Paper figures: informs figures