Spaces:
Sleeping
Sleeping
| 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. | |