README.md

metadata

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.

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 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 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.