---
title: Aphaea
emoji: 🌙
colorFrom: pink
colorTo: purple
sdk: gradio
sdk_version: 5.38.2
app_file: app.py
pinned: false
license: mit
---

# Aphaea

Aphaea is a cycle-aware reproductive-health education assistant. It combines
semantic retrieval with an instruction-tuned language model to answer questions
using a small, traceable source library.

> Aphaea provides general education, not diagnosis or medical care. It does not
> replace a clinician, pharmacist, or emergency service.

## What changed in the rebuild

- Connected semantic retrieval to the generation pipeline.
- Added inline source labels and clickable source details.
- Replaced fixed phase claims with a transparent calendar-day estimate.
- Added input validation, configuration errors, and model-service fallbacks.
- Removed collection of names and exact ages.
- Rebuilt the interface for a clearer desktop and mobile experience.
- Added authoritative summaries from CDC, ACOG, the Office on Women's Health,
  and a peer-reviewed exercise meta-analysis.

## Architecture

1. Source summaries are loaded from `knowledge/sources.json`.
2. `all-MiniLM-L6-v2` embeds each passage and the user's question.
3. Cosine similarity selects the four most relevant passages.
4. Qwen 2.5 Instruct receives the question, optional session profile, and retrieved context.
5. The response must cite the supplied passages as `[S1]`, `[S2]`, and so on.

## Run locally

Python 3.10 or newer is recommended.

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python app.py
```

Add a Hugging Face read token to `.env` as `HF_TOKEN`. Never commit `.env`.
The interface and retrieval can be inspected without a token; generation will
show a configuration message until the secret is present.

## Hugging Face deployment

Create a Space secret named `HF_TOKEN`. The application reads it at runtime.
Do not place the token in `README.md`, `app.py`, or the Git history.

## Knowledge-source policy

Every active passage must include a stable identifier, title, public URL, review
date, and concise paraphrase. Prefer government health agencies, professional
medical bodies, and peer-reviewed systematic reviews. Re-review health passages
before major releases.

## Limitations

- Retrieval quality is not yet clinically evaluated.
- The current corpus is intentionally small.
- Calendar estimates cannot confirm ovulation or hormonal phase.
- Generated answers can still be incomplete or wrong and require evaluation.

## Evaluation and release history

The [`evaluation`](evaluation/) folder contains a 30-prompt fixed test library,
scoring rubric, run log, and formula-driven dashboard. Use the same prompts for
every release so measured changes are comparable. See [`CHANGELOG.md`](CHANGELOG.md)
for the product history and verification record.

## Roadmap

- Run and score the first versioned baseline evaluation.
- Add automated tests for source coverage and safety behavior.
- Conduct accessibility and mobile-layout audits.
- Publish measured results before making accuracy claims.