# kanak0708/women-s-health-ai-agent architecture

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

- Interactive diagram: https://gitdiagram.com/kanak0708/women-s-health-ai-agent
- Repository: https://github.com/kanak0708/women-s-health-ai-agent

## Overview

The product is a CLI-based, evidence-grounded women’s-health education assistant for adult menstrual health and PCOS. A user query enters the application service, which coordinates session context, bounded cycle-task handling, safety and retrieval; the tools orchestrator selects evidence or supported tools, and the service gates the resulting answer through claim verification. Separate branches support cycle calculations and explicitly authorized PubMed research. Edges reflect the README and shown source/index references; several domain modules were not excerpted, so their internal behavior is not expanded.

Main entry points: [`health_tools/workflow.py`](https://github.com/kanak0708/women-s-health-ai-agent/blob/main/health_tools/workflow.py) (Tools Orchestrator), [`app/workflow/service.py`](https://github.com/kanak0708/women-s-health-ai-agent/blob/main/app/workflow/service.py) (Application Service), [`app/retrieval/engine.py`](https://github.com/kanak0708/women-s-health-ai-agent/blob/main/app/retrieval/engine.py) (Hybrid Retrieval), [`main.py`](https://github.com/kanak0708/women-s-health-ai-agent/blob/main/main.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Entry"]
  node_cli["CLI<br/>[main.py]"]
  node_service["Application Service<br/>[service.py]"]
  node_orchestrator["Tools Orchestrator<br/>[workflow.py]"]
end

subgraph group_memory["Session and Tasks"]
  node_context["Context Tracking<br/>[context_tracker.py]"]
  node_session[("Session Store")]
  node_memory_schema["Memory Schema<br/>[memory.py]"]
  node_pending["Pending Tasks<br/>[pending_tasks.py]"]
end

subgraph group_evidence["Evidence and Answers"]
  node_evidence_schema["Evidence Contracts<br/>[evidence.py]"]
  node_retrieval["Hybrid Retrieval<br/>[engine.py]"]
  node_pg[("Postgres Retrieval")]
  node_filters["Retrieval Guardrails<br/>[filters.py]"]
  node_reranker["Passage Reranking<br/>[reranker.py]"]
  node_selection["Answer Selection"]
  node_verifier["Claim Verification<br/>[verifier.py]"]
  node_handoff["Evidence Handoff<br/>[handoff.py]"]
end

subgraph group_health["Health Tools"]
  node_cycle["Cycle Analysis<br/>[cycle_history.py]"]
  node_pubmed["PubMed Research<br/>[pubmed.py]"]
end

node_user(("User"))
node_ncbi(("NCBI"))

node_user -->|"submits query"| node_cli
node_cli -->|"processes turn"| node_service
node_cli -->|"configures tools"| node_orchestrator
node_service -->|"runs workflow"| node_orchestrator
node_service -->|"updates context"| node_context
node_service -->|"loads and saves"| node_session
node_session -->|"stores state"| node_memory_schema
node_service -->|"manages tasks"| node_pending
node_orchestrator -->|"requests evidence"| node_retrieval
node_orchestrator -->|"selects passages"| node_selection
node_orchestrator -->|"adapts evidence"| node_handoff
node_orchestrator -->|"analyzes cycles"| node_cycle
node_orchestrator -->|"dispatches research"| node_pubmed
node_pubmed -->|"queries research"| node_ncbi
node_retrieval -->|"uses backend"| node_pg
node_retrieval -->|"applies guardrails"| node_filters
node_retrieval -->|"ranks passages"| node_reranker
node_pg -->|"applies guardrails"| node_filters
node_pg -->|"ranks passages"| node_reranker
node_retrieval -->|"returns evidence"| node_evidence_schema
node_service -->|"checks answer"| node_verifier
node_verifier -->|"checks citations"| node_evidence_schema

click node_cli "https://github.com/kanak0708/women-s-health-ai-agent/blob/main/main.py"
click node_service "https://github.com/kanak0708/women-s-health-ai-agent/blob/main/app/workflow/service.py"
click node_orchestrator "https://github.com/kanak0708/women-s-health-ai-agent/blob/main/health_tools/workflow.py"
click node_context "https://github.com/kanak0708/women-s-health-ai-agent/blob/main/app/storage/context_tracker.py"
click node_session "https://github.com/kanak0708/women-s-health-ai-agent/blob/main/app/storage/redis_session_store.py"
click node_memory_schema "https://github.com/kanak0708/women-s-health-ai-agent/blob/main/app/schemas/memory.py"
click node_pending "https://github.com/kanak0708/women-s-health-ai-agent/blob/main/health_tools/pending_tasks.py"
click node_evidence_schema "https://github.com/kanak0708/women-s-health-ai-agent/blob/main/app/schemas/evidence.py"
click node_retrieval "https://github.com/kanak0708/women-s-health-ai-agent/blob/main/app/retrieval/engine.py"
click node_pg "https://github.com/kanak0708/women-s-health-ai-agent/blob/main/app/retrieval/pg_vector_engine.py"
click node_filters "https://github.com/kanak0708/women-s-health-ai-agent/blob/main/app/retrieval/filters.py"
click node_reranker "https://github.com/kanak0708/women-s-health-ai-agent/blob/main/app/retrieval/reranker.py"
click node_selection "https://github.com/kanak0708/women-s-health-ai-agent/blob/main/health_tools/answer_selection.py"
click node_verifier "https://github.com/kanak0708/women-s-health-ai-agent/blob/main/app/verification/verifier.py"
click node_handoff "https://github.com/kanak0708/women-s-health-ai-agent/blob/main/health_tools/handoff.py"
click node_cycle "https://github.com/kanak0708/women-s-health-ai-agent/blob/main/health_tools/cycle_history.py"
click node_pubmed "https://github.com/kanak0708/women-s-health-ai-agent/blob/main/health_tools/pubmed.py"

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_cli,node_service,node_orchestrator,node_user toneBlue
class node_context,node_session,node_memory_schema,node_pending toneAmber
class node_evidence_schema,node_retrieval,node_pg,node_filters,node_reranker,node_selection,node_verifier,node_handoff toneMint
class node_cycle,node_pubmed toneRose
class node_ncbi toneIndigo
```

## Components

### User Entry

- [CLI](https://github.com/kanak0708/women-s-health-ai-agent/blob/main/main.py): `main.py`
- [Application Service](https://github.com/kanak0708/women-s-health-ai-agent/blob/main/app/workflow/service.py): `app/workflow/service.py`
- [Tools Orchestrator](https://github.com/kanak0708/women-s-health-ai-agent/blob/main/health_tools/workflow.py): `health_tools/workflow.py`

### Session and Tasks

- [Context Tracking](https://github.com/kanak0708/women-s-health-ai-agent/blob/main/app/storage/context_tracker.py): `app/storage/context_tracker.py`
- [Session Store](https://github.com/kanak0708/women-s-health-ai-agent/blob/main/app/storage/redis_session_store.py): `app/storage/redis_session_store.py`
- [Memory Schema](https://github.com/kanak0708/women-s-health-ai-agent/blob/main/app/schemas/memory.py): `app/schemas/memory.py`
- [Pending Tasks](https://github.com/kanak0708/women-s-health-ai-agent/blob/main/health_tools/pending_tasks.py): `health_tools/pending_tasks.py`

### Evidence and Answers

- [Evidence Contracts](https://github.com/kanak0708/women-s-health-ai-agent/blob/main/app/schemas/evidence.py): `app/schemas/evidence.py`
- [Hybrid Retrieval](https://github.com/kanak0708/women-s-health-ai-agent/blob/main/app/retrieval/engine.py): `app/retrieval/engine.py`
- [Postgres Retrieval](https://github.com/kanak0708/women-s-health-ai-agent/blob/main/app/retrieval/pg_vector_engine.py): `app/retrieval/pg_vector_engine.py`
- [Retrieval Guardrails](https://github.com/kanak0708/women-s-health-ai-agent/blob/main/app/retrieval/filters.py): `app/retrieval/filters.py`
- [Passage Reranking](https://github.com/kanak0708/women-s-health-ai-agent/blob/main/app/retrieval/reranker.py): `app/retrieval/reranker.py`
- [Answer Selection](https://github.com/kanak0708/women-s-health-ai-agent/blob/main/health_tools/answer_selection.py): `health_tools/answer_selection.py`
- [Claim Verification](https://github.com/kanak0708/women-s-health-ai-agent/blob/main/app/verification/verifier.py): `app/verification/verifier.py`
- [Evidence Handoff](https://github.com/kanak0708/women-s-health-ai-agent/blob/main/health_tools/handoff.py): `health_tools/handoff.py`

### Health Tools

- [Cycle Analysis](https://github.com/kanak0708/women-s-health-ai-agent/blob/main/health_tools/cycle_history.py): `health_tools/cycle_history.py`
- [PubMed Research](https://github.com/kanak0708/women-s-health-ai-agent/blob/main/health_tools/pubmed.py): `health_tools/pubmed.py`

### Other components

- **User**
- **NCBI**

## Connections

- User → CLI: submits query
- CLI → Application Service: processes turn (evidence: `main.py`)
- CLI → Tools Orchestrator: configures tools (evidence: `main.py`)
- Application Service → Tools Orchestrator: runs workflow (evidence: `app/workflow/service.py`)
- Application Service → Context Tracking: updates context (evidence: `app/workflow/service.py`)
- Application Service → Session Store: loads and saves (evidence: `app/workflow/service.py`)
- Session Store → Memory Schema: stores state (evidence: `app/storage/redis_session_store.py`)
- Application Service → Pending Tasks: manages tasks (evidence: `app/workflow/service.py`)
- Tools Orchestrator → Hybrid Retrieval: requests evidence (evidence: `health_tools/workflow.py`)
- Tools Orchestrator → Answer Selection: selects passages (evidence: `health_tools/workflow.py`)
- Tools Orchestrator → Evidence Handoff: adapts evidence (evidence: `health_tools/workflow.py`)
- Tools Orchestrator → Cycle Analysis: analyzes cycles (evidence: `health_tools/workflow.py`)
- Tools Orchestrator → PubMed Research: dispatches research (evidence: `health_tools/workflow.py`)
- PubMed Research → NCBI: queries research
- Hybrid Retrieval → Postgres Retrieval: uses backend (evidence: `app/retrieval/pg_vector_engine.py`)
- Hybrid Retrieval → Retrieval Guardrails: applies guardrails (evidence: `app/retrieval/engine.py`)
- Hybrid Retrieval → Passage Reranking: ranks passages (evidence: `app/retrieval/engine.py`)
- Postgres Retrieval → Retrieval Guardrails: applies guardrails (evidence: `app/retrieval/pg_vector_engine.py`)
- Postgres Retrieval → Passage Reranking: ranks passages (evidence: `app/retrieval/pg_vector_engine.py`)
- Hybrid Retrieval → Evidence Contracts: returns evidence (evidence: `app/retrieval/engine.py`)
- Application Service → Claim Verification: checks answer (evidence: `app/workflow/service.py`)
- Claim Verification → Evidence Contracts: checks citations (evidence: `app/verification/verifier.py`)