Deploy rebuilt Aphaea with cited retrieval

.env.example

@@ -0,0 +1,6 @@
+# Create a Hugging Face read token at https://huggingface.co/settings/tokens.
+# Add it as a Hugging Face Space secret named HF_TOKEN in production.
+HF_TOKEN=
+
+# Optional model override.
+HF_MODEL=google/gemma-2-2b-it

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Teah Reichenbaum
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,12 +1,81 @@
 ---
-title: Chatbot
-emoji: 💻
-colorFrom: purple
-colorTo: blue
+title: Aphaea
+emoji: 🌙
+colorFrom: pink
+colorTo: purple
 sdk: gradio
 sdk_version: 5.38.2
 app_file: app.py
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 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. Gemma 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.
+
+## Roadmap
+
+- Build a versioned evaluation set for retrieval and citation accuracy.
+- Add automated tests for source coverage and safety behavior.
+- Conduct accessibility and mobile-layout audits.
+- Publish measured results before making accuracy claims.

app.py

@@ -1,221 +1,413 @@
+"""Aphaea: a cited, cycle-aware wellness education assistant."""
+
+import json
+import os
+from collections.abc import Iterable
+from dataclasses import dataclass
+from datetime import date, datetime
+from functools import lru_cache
+from pathlib import Path
+
 import gradio as gr
+import numpy as np
+from dotenv import load_dotenv
 from huggingface_hub import InferenceClient
-import os
 from sentence_transformers import SentenceTransformer
-import torch
-import numpy as np
-from datetime import datetime, timedelta
-
-# Load knowledge base
-with open("knowledge.txt", "r", encoding="utf-8") as f:
-    knowledge_text = f.read()
-chunks = [chunk.strip() for chunk in knowledge_text.split("\n\n") if chunk.strip()]
-embedder = SentenceTransformer('all-MiniLM-L6-v2')
-chunk_embeddings = embedder.encode(chunks, convert_to_tensor=True)
-
-def get_relevant_context(query, top_k=3):
-    query_embedding = embedder.encode(query, convert_to_tensor=True)
-    query_embedding = query_embedding / query_embedding.norm()
-    norm_chunk_embeddings = chunk_embeddings / chunk_embeddings.norm(dim=1, keepdim=True)
-    similarities = torch.matmul(norm_chunk_embeddings, query_embedding)
-    top_k_indices = torch.topk(similarities, k=top_k).indices.cpu().numpy()
-    context = "\n\n".join([chunks[i]] for i in top_k_indices)
-    return context
-
-client = InferenceClient("google/gemma-2-2b-it")
-
-cycle_ai_prompt = """
-Cycle-Aware Wellness AI Coach (Strict Enforcement Version)
-==========================================================
-Mission:
---------
-You are a compassionate and knowledgeable wellness coach who specializes in fitness aligned with the menstrual cycle and evidence-based contraceptive education. Your mission is to empower women to understand their bodies, support their fitness and reproductive health, and make informed, cycle-aware choices.
-You may *only* respond to questions related to:
-- Menstrual cycles and hormonal phases
-- Cycle-based fitness and wellness programming
-- Contraceptive methods and reproductive health education
-- Hormonal syndromes or life stages (PCOS, PMDD, menopause, irregular cycles, etc.)
-If the user asks something unrelated (e.g., fixing a car, meal prep, unrelated illnesses, tech support), immediately respond with:
-"I'm here to help with cycle-based fitness and contraceptive wellness. That question’s outside my scope, but I’d love to support you with anything related to your body, cycle, or health goals!"
-You must *never* attempt to answer off-topic requests, even if the user insists or rephrases. Always redirect the conversation back to wellness, hormones, fitness, or reproductive health.
-Style and Voice Guidelines:
----------------------------
-- Speak like a friendly, knowledgeable older sister who’s also a certified personal trainer and women’s health educator.
-- Be warm, inclusive, and body-positive. Avoid judgment, shame, or clinical coldness.
-- Validate the user’s experience before offering guidance (e.g., “That makes total sense—your energy might be shifting in this phase”).
-- Encourage autonomy by offering options, not orders.
-- Connect advice to real-life impact: how the cycle affects energy, mood, and performance.
-When the user asks about workouts, always ask a follow-up:
-"What kind of equipment or space do you have access to—like a gym, home weights, or just bodyweight? I’ll tailor a workout for you based on that!"
-Final Boundary Rule:
---------------------
- Strictly decline all unrelated questions. Your only purpose is cycle-aware fitness and reproductive wellness coaching. Do not give general medical, tech, cooking, legal, or life advice. IF THE USER ASKS ABOUT A WORKOUT YOU MUST ASK WHAT EQUIPTMENT OR THINGS THEY HAVE ACSESS TO
-"""
 
-def determine_cycle_phase(start_date_str):
+APP_DIR = Path(__file__).parent
+load_dotenv(APP_DIR / ".env")
+MODEL_ID = os.getenv("HF_MODEL", "google/gemma-2-2b-it")
+HF_TOKEN = os.getenv("HF_TOKEN")
+EMBEDDING_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
+
+MEDICAL_NOTICE = (
+    "Aphaea provides general education, not diagnosis or medical care. "
+    "Seek urgent help for severe pain, fainting, very heavy bleeding, trouble breathing, "
+    "or another emergency."
+)
+
+SYSTEM_PROMPT = f"""
+You are Aphaea, a careful educational assistant for menstrual-cycle wellness,
+exercise, contraception, and reproductive health.
+
+Rules:
+- Use only the supplied source passages for factual health claims.
+- Cite supporting passages inline as [S1], [S2], and so on.
+- If the passages do not support an answer, say that clearly and recommend a
+  qualified clinician or pharmacist instead of guessing.
+- Never diagnose, prescribe, or tell someone to start or stop medication.
+- Do not claim that a calendar estimate can confirm ovulation or cycle phase.
+- For urgent warning signs, encourage immediate local medical care.
+- Keep responses concise, inclusive, respectful, and easy to understand.
+- Decline unrelated requests and redirect to Aphaea's health-education scope.
+
+Medical notice: {MEDICAL_NOTICE}
+""".strip()
+
+
+@dataclass(frozen=True)
+class SourceChunk:
+    text: str
+    title: str
+    source_id: str
+    url: str = ""
+
+
+def split_legacy_knowledge(text: str) -> list[SourceChunk]:
+    """Split the original corpus while retaining stable source identifiers."""
+    paragraphs = [p.strip() for p in text.split("\n\n") if len(p.strip()) >= 40]
+    return [
+        SourceChunk(
+            text=paragraph,
+            title="Aphaea legacy knowledge base (source review pending)",
+            source_id=f"legacy-{index:03d}",
+        )
+        for index, paragraph in enumerate(paragraphs, start=1)
+    ]
+
+
+class KnowledgeBase:
+    def __init__(self, chunks: Iterable[SourceChunk]):
+        self.chunks = list(chunks)
+        if not self.chunks:
+            raise ValueError("The knowledge base contains no usable passages.")
+        self.encoder = SentenceTransformer(EMBEDDING_MODEL)
+        embeddings = self.encoder.encode(
+            [chunk.text for chunk in self.chunks],
+            convert_to_numpy=True,
+            normalize_embeddings=True,
+        )
+        self.embeddings = np.asarray(embeddings, dtype=np.float32)
+
+    def search(self, query: str, top_k: int = 4) -> list[tuple[SourceChunk, float]]:
+        query_embedding = self.encoder.encode(
+            [query], convert_to_numpy=True, normalize_embeddings=True
+        )[0]
+        scores = self.embeddings @ query_embedding
+        count = min(top_k, len(self.chunks))
+        indices = np.argsort(scores)[-count:][::-1]
+        return [(self.chunks[index], float(scores[index])) for index in indices]
+
+
+@lru_cache(maxsize=1)
+def get_knowledge_base() -> KnowledgeBase:
+    records = json.loads(
+        (APP_DIR / "knowledge" / "sources.json").read_text(encoding="utf-8")
+    )
+    chunks = [
+        SourceChunk(
+            text=record["text"],
+            title=record["title"],
+            source_id=record["source_id"],
+            url=record["url"],
+        )
+        for record in records
+    ]
+    return KnowledgeBase(chunks)
+
+
+def parse_iso_date(value: str) -> date:
+    if not value or not value.strip():
+        raise ValueError("Enter the first day of your most recent period.")
+    try:
+        parsed = date.fromisoformat(value.strip())
+    except ValueError as exc:
+        raise ValueError("Use the date format YYYY-MM-DD.") from exc
+    if parsed > datetime.now().astimezone().date():
+        raise ValueError("The start date cannot be in the future.")
+    return parsed
+
+
+def cycle_day_estimate(start_date: str, typical_length: int) -> tuple[int, str]:
+    """Return a transparent calendar estimate, not an ovulation prediction."""
+    start = parse_iso_date(start_date)
+    length = int(typical_length)
+    if not 21 <= length <= 40:
+        raise ValueError("Typical cycle length must be between 21 and 40 days.")
+    elapsed = (datetime.now().astimezone().date() - start).days
+    day = elapsed % length + 1
+    return day, (
+        f"Calendar estimate: cycle day {day} of a typical {length}-day cycle. "
+        "This cannot confirm hormonal phase or ovulation, especially when cycles vary."
+    )
+
+
+def build_profile(start_date: str, typical_length: int, training_level: str):
     try:
-        start_date = datetime.strptime(start_date_str, "%Y-%m-%d")
-        days_since = (datetime.now() - start_date).days % 28
-        if days_since < 5:
-            return "Menstrual Phase", "💗 Time to rest and recover. Gentle movement like stretching or walking is great."
-        elif days_since < 13:
-            return "Follicular Phase", "💪 Your energy’s building—go for strength training or cardio!"
-        elif days_since < 16:
-            return "Ovulation Phase", "🔥 Peak power! Try high-intensity workouts or social activities."
-        else:
-            return "Luteal Phase", "🌙 Wind down. Opt for lighter training, yoga, or bodyweight exercises."
-    except:
-        return "Unknown Phase", "Couldn't parse the date. Please use YYYY-MM-DD."
-
-def respond(message, history):
-    if not isinstance(history, list):
-        history = []
-
-    messages = [{"role": "system", "content": cycle_ai_prompt}]
-    for entry in history:
-        if isinstance(entry, dict):
-            messages.append(entry)
-    messages.append({"role": "user", "content": message})
-
-    response = client.chat_completion(
-        messages,
-        max_tokens=500,
-        temperature=0.1
+        day, estimate = cycle_day_estimate(start_date, typical_length)
+    except ValueError as exc:
+        return gr.update(value=f"**Check your information:** {exc}"), {}
+
+    profile = {
+        "cycle_day": day,
+        "cycle_length": int(typical_length),
+        "training_level": training_level or "Not specified",
+    }
+    message = (
+        f"### Your private session profile\n\n{estimate}\n\n"
+        f"**Training level:** {profile['training_level']}\n\n"
+        "Your entries stay in this browser session and are not written to a database."
     )
+    return gr.update(value=message), profile
+
+
+def format_sources(results: list[tuple[SourceChunk, float]]) -> tuple[str, str]:
+    context_parts = []
+    source_lines = []
+    for position, (chunk, score) in enumerate(results, start=1):
+        context_parts.append(f"[S{position}] {chunk.text}")
+        title = f"[{chunk.title}]({chunk.url})" if chunk.url else chunk.title
+        source_lines.append(f"**S{position}.** {title} - `{chunk.source_id}`")
+    return "\n\n".join(context_parts), "\n\n".join(source_lines)
+
+
+def normalize_history(history) -> list[dict[str, str]]:
+    normalized = []
+    for entry in history or []:
+        if isinstance(entry, dict) and entry.get("role") in {"user", "assistant"}:
+            content = entry.get("content")
+            if isinstance(content, str):
+                normalized.append({"role": entry["role"], "content": content})
+    return normalized[-8:]
 
-    print("DEBUG RESPONSE:", response)  # <-- Add this to inspect
 
-    # Now adapt based on actual response
+def answer(message: str, history, profile: dict):
+    message = (message or "").strip()
+    clean_history = normalize_history(history)
+    if not message:
+        return clean_history, clean_history, "", ""
+
     try:
-        assistant_reply = response['choices'][0]['message']['content'].strip()
-    except Exception as e:
-        assistant_reply = f"⚠️ There was an error processing the response: {e}"
+        results = get_knowledge_base().search(message)
+        context, sources = format_sources(results)
+    except Exception as exc:  # noqa: BLE001 - user-facing retrieval boundary
+        reply = (
+            "I couldn't search the knowledge library right now. "
+            f"Please try again after the app is restarted. ({type(exc).__name__})"
+        )
+        updated = clean_history + [
+            {"role": "user", "content": message},
+            {"role": "assistant", "content": reply},
+        ]
+        return updated, updated, "", ""
+
+    if not HF_TOKEN:
+        reply = (
+            "The interface and knowledge retrieval are working, but model generation "
+            "is not configured locally yet. Add `HF_TOKEN` to a local `.env` workflow "
+            "or as a Hugging Face Space secret. Never paste the token into source code."
+        )
+    else:
+        profile_note = (
+            f"Session profile: {profile}. Treat the cycle day as a calendar estimate only."
+            if profile
+            else "No optional session profile was provided."
+        )
+        messages = [
+            {"role": "system", "content": SYSTEM_PROMPT},
+            *clean_history,
+            {
+                "role": "user",
+                "content": (
+                    f"{profile_note}\n\nQuestion: {message}\n\n"
+                    f"Retrieved passages:\n{context}"
+                ),
+            },
+        ]
+        try:
+            client = InferenceClient(model=MODEL_ID, token=HF_TOKEN)
+            completion = client.chat_completion(
+                messages=messages,
+                max_tokens=550,
+                temperature=0.2,
+            )
+            reply = completion.choices[0].message.content or "No response was returned."
+        except Exception as exc:  # noqa: BLE001 - remote model boundary
+            reply = (
+                "The model service is unavailable right now, but your question was not lost. "
+                f"Please try again shortly. ({type(exc).__name__})"
+            )
 
-    new_history = history + [
+    updated = clean_history + [
         {"role": "user", "content": message},
-        {"role": "assistant", "content": assistant_reply}
+        {"role": "assistant", "content": reply},
     ]
-    return new_history, new_history, ""
+    return updated, updated, "", sources
 
-def update_chatbot(user_message, history):
-    return respond(user_message, history)
 
-def set_user_info(name, age, level, period_start_date, period_end_date):
-    phase, tip = determine_cycle_phase(period_start_date)
-    greeting = f"Hi {name}! I'm here to help you with cycle-aware fitness and wellness.\n\nYou’re {age} years old, training at a {level.lower()} level, and your last period started on {period_start_date} and ended on {period_end_date}.\n\nRight now, you’re likely in your **{phase}**. {tip} 💞\n\nAsk me anything about your body, cycle, or contraceptive health!"
-    return name, [{"role": "assistant", "content": greeting}]
+def suggested_prompt(prompt: str, history, profile):
+    return answer(prompt, history, profile)
 
-def button_click(question, history):
-    new_history, updated_history, _ = respond(question, history)
-    return new_history, updated_history
 
-with gr.Blocks(
-    css="""
-    .gradio-container {
-        background: linear-gradient(135deg, #F6D365 0%, #FDA085 50%, #FF8FA0 100%);
-        font-family: 'Quicksand', sans-serif;
-    }
-    .message.user {
-        background-color: lightpink;
-        border-radius: 20px;
-        padding: 10px;
-        margin: 5px;
-        max-width: 75%;
-        align-self: flex-end;
-    }
-    .message.bot {
-        background-color: #FFE4D1;
-        border-radius: 20px;
-        padding: 10px;
-        margin: 5px;
-        max-width: 75%;
-        align-self: flex-start;
-    }
-    .chat-interface {
-        background-color: peachpuff;
-        border-radius: 12px;
-        padding: 15px;
-        box-shadow: 0 4px 10px rgba(0, 0, 0, 0.1);
-    }
-    #about-you-title {
-    font-size: 24px;
-    font-weight: 700;
-    color: #A80055;
-    text-align: left;
-    padding-left: 10px;
-    margin-top: 10px;
-    margin-bottom: -10px;
-}
-
-    #banner-image {
-        background-color: transparent;
-        margin-bottom: -150px;
-        margin-top: -150px;
-        padding-top: 20px;
-    }
-    """,
-    theme=gr.themes.Soft(
-        primary_hue="pink",
-        secondary_hue="orange",
-        neutral_hue="yellow",
-        spacing_size="lg",
-        radius_size="lg",
-        font=[gr.themes.GoogleFont("Quicksand"), "sans-serif"],
-        font_mono=[gr.themes.GoogleFont("IBM Plex Mono"), "monospace"]
-    )
-) as demo:
-    gr.Image(
-        value="Untitled design.png",
-        show_label=False,
-        show_share_button = False,
-        show_download_button = False,
-        elem_id="banner-image")
-
-    name_state = gr.State("")
-    chat_history = gr.State([])
-    gr.Markdown("## Tell me about yourself", elem_id="about-you-title")
-    
-    with gr.Row():
-        with gr.Column(scale=1):
-            name_input = gr.Textbox(label="Name", placeholder="Your name…")
-            age_input = gr.Textbox(label="Age", placeholder="Your age…")
-            level_input = gr.Dropdown(choices=["Beginner", "Intermediate", "Expert"], label="Training Level")
-            period_start_input = gr.Textbox(label="Last Period Start Date", placeholder="YYYY-MM-DD")
-            period_end_input = gr.Textbox(label="Last Period End Date", placeholder="YYYY-MM-DD")
-            set_btn = gr.Button("Set Info")
-            gr.Markdown("_After the greeting appears, start chatting →_")
-
-        with gr.Column(scale=2):
-            chatbot = gr.Chatbot(label="Chat", type="messages")
-            user_text = gr.Textbox(placeholder="Ask me something…", label="")
-            with gr.Row():
-                workout_btn = gr.Button("Prompt: Workouts")
-                contraceptive_btn = gr.Button("Prompt: Contraceptives")
-
-    set_btn.click(
-        fn=set_user_info,
-        inputs=[name_input, age_input, level_input, period_start_input, period_end_input],
-        outputs=[name_state, chatbot],
-        show_progress=False,
-    )
+CSS = """
+:root { --ink: #24212b; --muted: #6f6878; --plum: #69405f; --rose: #b75b73; }
+.gradio-container { background: #fbf8f6 !important; color: var(--ink); color-scheme: light !important;
+  --body-background-fill: #fbf8f6; --block-background-fill: #ffffff;
+  --input-background-fill: #ffffff; --body-text-color: #24212b;
+  --block-label-text-color: #69405f; }
+.app-shell { max-width: 1180px; margin: 0 auto; }
+.hero { padding: 26px 30px; border: 1px solid #eadfe2; border-radius: 24px;
+  background: linear-gradient(135deg, #fff 0%, #f9ecef 100%); margin-bottom: 18px; }
+.eyebrow { color: #8e5067; font-weight: 700; letter-spacing: .12em; text-transform: uppercase; font-size: 12px; }
+.hero h1 { font-size: 36px; line-height: 1.08; margin: 8px 0; color: #3f283b; }
+.hero p { color: var(--muted); max-width: 720px; font-size: 16px; margin: 0; }
+.status { display: inline-block; margin-top: 15px; padding: 6px 10px; border-radius: 999px;
+  background: #f0e3e7; color: #69405f; font-size: 12px; font-weight: 700; }
+.panel { border: 1px solid #eadfe2 !important; border-radius: 20px !important;
+  background: #fff !important; padding: 18px !important; box-shadow: 0 10px 30px rgba(69,43,62,.06); }
+h1, h2, h3, p { color: var(--ink) !important; }
+.panel .block, .panel .wrap, .panel .form { background: #fff !important; color: var(--ink) !important; }
+.panel input, .panel textarea { background: #fff !important; color: var(--ink) !important; }
+#aphaea-chat { background: #fff !important; color: var(--ink) !important; }
+#aphaea-chat .wrap { background: #1f2937 !important; }
+#aphaea-chat .wrap, #aphaea-chat .wrap * { color: #f8fafc !important; }
+.panel label, .panel label span, .panel .label-wrap { color: var(--ink) !important; }
+button.primary { color: #fff !important; }
+.profile-copy { color: var(--muted); font-size: 13px; }
+.notice { border-left: 4px solid #b75b73; padding: 10px 12px; background: #fff3f5;
+  color: #5d3546; border-radius: 8px; font-size: 13px; }
+.sources { font-size: 12px; color: var(--muted); }
+footer { display: none !important; }
+"""
 
-    user_text.submit(
-        fn=update_chatbot,
-        inputs=[user_text, chat_history],
-        outputs=[chatbot, chat_history, user_text]
-    )
+THEME = gr.themes.Base(primary_hue="rose", neutral_hue="slate").set(
+    body_background_fill="#fbf8f6",
+    body_text_color="#24212b",
+    block_background_fill="#ffffff",
+    block_border_color="#eadfe2",
+    block_label_background_fill="#ffffff",
+    block_label_text_color="#69405f",
+    input_background_fill="#ffffff",
+    input_border_color="#ded6dc",
+    input_placeholder_color="#8a838d",
+    button_primary_background_fill="#7d4667",
+    button_primary_background_fill_hover="#673653",
+    button_primary_text_color="#ffffff",
+    button_secondary_background_fill="#f4eff1",
+    button_secondary_background_fill_hover="#eadfe3",
+    button_secondary_text_color="#3f283b",
+)
+
+
+with gr.Blocks(css=CSS, theme=THEME) as demo:
+    profile_state = gr.State({})
+    history_state = gr.State([])
+
+    with gr.Column(elem_classes="app-shell"):
+        gr.HTML(
+            """
+            <section class="hero">
+              <div class="eyebrow">Cycle-aware health education</div>
+              <h1>Aphaea</h1>
+              <p>Explore menstrual wellness, movement, and contraception with
+              answers grounded in a cited source library under active review.</p>
+              <span class="status">Educational tool - not medical care</span>
+            </section>
+            """
+        )
 
-    workout_btn.click(
-        fn=lambda history: button_click("What workout routine would you recommend based on my cycle phase?", history),
-        inputs=[chat_history],
-        outputs=[chatbot, chat_history]
+        with gr.Row(equal_height=False):
+            with gr.Column(scale=1, elem_classes="panel"):
+                gr.Markdown("### Optional session profile")
+                gr.Markdown(
+                    "A calendar estimate can personalize wording, but it cannot confirm "
+                    "ovulation or hormonal phase.",
+                    elem_classes="profile-copy",
+                )
+                start_input = gr.Textbox(
+                    label="Most recent period start",
+                    placeholder="YYYY-MM-DD",
+                )
+                length_input = gr.Slider(
+                    minimum=21,
+                    maximum=40,
+                    value=28,
+                    step=1,
+                    label="Typical cycle length",
+                )
+                training_input = gr.Dropdown(
+                    ["Beginner", "Intermediate", "Advanced"],
+                    value="Beginner",
+                    label="Training experience",
+                )
+                save_profile = gr.Button("Create session profile", variant="primary")
+                profile_output = gr.Markdown(
+                    "No profile created. You can still use the assistant."
+                )
+                gr.HTML(f'<div class="notice">{MEDICAL_NOTICE}</div>')
+
+            with gr.Column(scale=2, elem_classes="panel"):
+                gr.Markdown("### Ask Aphaea")
+                chatbot = gr.Chatbot(
+                    elem_id="aphaea-chat",
+                    type="messages",
+                    height=430,
+                    placeholder="Ask a question or choose a starting prompt below.",
+                    show_copy_button=True,
+                )
+                user_input = gr.Textbox(
+                    label="Your question",
+                    placeholder="For example: What are common reasons a cycle changes?",
+                    lines=2,
+                )
+                with gr.Row():
+                    send_button = gr.Button("Send", variant="primary")
+                    clear_button = gr.Button("Clear conversation")
+                with gr.Row():
+                    workout_button = gr.Button("Adapt a workout")
+                    contraception_button = gr.Button("Compare contraception")
+                    symptoms_button = gr.Button("Understand cycle changes")
+                with gr.Accordion("Sources used for the latest answer", open=False):
+                    source_output = gr.Markdown(
+                        "Sources will appear after you ask a question.",
+                        elem_classes="sources",
+                    )
+
+    save_profile.click(
+        build_profile,
+        [start_input, length_input, training_input],
+        [profile_output, profile_state],
     )
 
-    contraceptive_btn.click(
-        fn=lambda history: button_click("Can you explain the different contraceptive options and their benefits?", history),
-        inputs=[chat_history],
-        outputs=[chatbot, chat_history]
+    for trigger in (send_button.click, user_input.submit):
+        trigger(
+            answer,
+            [user_input, history_state, profile_state],
+            [chatbot, history_state, user_input, source_output],
+        )
+
+    workout_button.click(
+        lambda history, profile: suggested_prompt(
+            "How can I adjust exercise when my energy or symptoms change?",
+            history,
+            profile,
+        ),
+        [history_state, profile_state],
+        [chatbot, history_state, user_input, source_output],
+    )
+    contraception_button.click(
+        lambda history, profile: suggested_prompt(
+            "What factors should someone discuss with a clinician when comparing contraception?",
+            history,
+            profile,
+        ),
+        [history_state, profile_state],
+        [chatbot, history_state, user_input, source_output],
     )
+    symptoms_button.click(
+        lambda history, profile: suggested_prompt(
+            "What are common reasons menstrual-cycle timing can change?",
+            history,
+            profile,
+        ),
+        [history_state, profile_state],
+        [chatbot, history_state, user_input, source_output],
+    )
+    clear_button.click(
+        lambda: ([], [], "Sources will appear after you ask a question."),
+        outputs=[chatbot, history_state, source_output],
+    )
+
 
-if __name__ == '__main__':
-    demo.launch()
+if __name__ == "__main__":
+    demo.queue().launch()

knowledge/sources.json

@@ -0,0 +1,44 @@
+[
+  {
+    "source_id": "owh-cycle-basics-2024",
+    "title": "Office on Women's Health - Your menstrual cycle",
+    "url": "https://womenshealth.gov/menstrual-cycle/your-menstrual-cycle",
+    "reviewed_at": "2026-08-05",
+    "text": "A menstrual cycle starts on the first day of menstrual bleeding and ends when the next period begins. Estrogen and progesterone levels usually change during the cycle and may contribute to symptoms. Calendar dates alone cannot prove when ovulation occurred, and cycles may become irregular for many reasons. A clinician can evaluate pregnancy or health conditions when periods stop or become irregular."
+  },
+  {
+    "source_id": "acog-aub-patterns",
+    "title": "ACOG - Abnormal Uterine Bleeding",
+    "url": "https://www.acog.org/womens-health/faqs/abnormal-uterine-bleeding",
+    "reviewed_at": "2026-08-05",
+    "text": "ACOG describes cycles shorter than 21 days or longer than 35 days, bleeding longer than 7 days, bleeding between periods or after sex, and substantial cycle-length variation as patterns that can warrant medical discussion. Potential causes include ovulation changes, fibroids, polyps, bleeding disorders, medications, pregnancy-related conditions, and other health conditions; symptoms alone cannot identify the cause."
+  },
+  {
+    "source_id": "acog-aub-emergency",
+    "title": "ACOG - Abnormal Uterine Bleeding",
+    "url": "https://www.acog.org/womens-health/faqs/abnormal-uterine-bleeding",
+    "reviewed_at": "2026-08-05",
+    "text": "ACOG advises emergency medical care when someone is changing pads or tampons every hour for more than 2 hours in a row and also has chest pain, shortness of breath, lightheadedness, or dizziness. Acute or unusually heavy bleeding should not be diagnosed by a chatbot."
+  },
+  {
+    "source_id": "cdc-contraception-choice-2024",
+    "title": "CDC - Contraception and Birth Control Methods",
+    "url": "https://www.cdc.gov/contraception/about/index.html",
+    "reviewed_at": "2026-08-05",
+    "text": "The CDC recommends voluntary, informed contraceptive choice. Relevant comparison factors include safety for the individual's medical history, effectiveness with typical use, availability and cost, possible side effects, user control, reversibility, and how easily a method can be stopped or removed. A clinician or pharmacist can help assess contraindications and medication interactions."
+  },
+  {
+    "source_id": "cdc-contraception-sti-2024",
+    "title": "CDC - Contraception and Birth Control Methods",
+    "url": "https://www.cdc.gov/contraception/about/index.html",
+    "reviewed_at": "2026-08-05",
+    "text": "Most contraceptive methods do not protect against sexually transmitted infections. Condoms can help reduce the risk of HIV and other sexually transmitted infections and may be used alone or together with another contraceptive method. Emergency contraception is intended for use after unprotected sex or method failure, not as a regular contraceptive method."
+  },
+  {
+    "source_id": "mcnulty-exercise-review-2020",
+    "title": "McNulty et al. - Menstrual cycle phase and exercise performance",
+    "url": "https://pubmed.ncbi.nlm.nih.gov/32661839/",
+    "reviewed_at": "2026-08-05",
+    "text": "A systematic review and meta-analysis found only trivial average differences in exercise performance across menstrual-cycle phases, with large differences between studies and low-quality evidence. The authors concluded that general phase-based exercise rules cannot be formed from the evidence and recommended personalizing training according to each individual's own responses and symptoms."
+  }
+]

requirements.txt

@@ -1,5 +1,7 @@
-gradio
-huggingface_hub
-sentence_transformers
-torch
-numpy
+gradio==5.38.2
+huggingface_hub>=0.33,<1.0
+sentence-transformers>=4.1,<6.0
+numpy>=1.26,<3.0
+requests>=2.32,<3.0
+python-dotenv>=1.0,<2.0
+pytest>=8.0,<9.0

tests/test_core.py

@@ -0,0 +1,46 @@
+import json
+from datetime import datetime, timedelta
+from pathlib import Path
+
+import pytest
+
+from app import cycle_day_estimate, parse_iso_date, split_legacy_knowledge
+
+
+def test_parse_iso_date_accepts_today():
+    today = datetime.now().astimezone().date()
+    assert parse_iso_date(today.isoformat()) == today
+
+
+def test_parse_iso_date_rejects_future_date():
+    today = datetime.now().astimezone().date()
+    future = (today + timedelta(days=1)).isoformat()
+    with pytest.raises(ValueError, match="future"):
+        parse_iso_date(future)
+
+
+def test_cycle_estimate_is_transparent():
+    today = datetime.now().astimezone().date()
+    day, explanation = cycle_day_estimate(today.isoformat(), 28)
+    assert day == 1
+    assert "cannot confirm hormonal phase or ovulation" in explanation
+
+
+def test_legacy_splitter_retains_stable_ids():
+    text = (
+        "A sufficiently long first paragraph that should become a source chunk.\n\n"
+        "A sufficiently long second paragraph that should become another chunk."
+    )
+    chunks = split_legacy_knowledge(text)
+    assert [chunk.source_id for chunk in chunks] == ["legacy-001", "legacy-002"]
+
+
+def test_active_sources_are_traceable():
+    source_path = Path(__file__).parents[1] / "knowledge" / "sources.json"
+    records = json.loads(source_path.read_text(encoding="utf-8"))
+    assert len(records) >= 5
+    assert len({record["source_id"] for record in records}) == len(records)
+    for record in records:
+        assert record["url"].startswith("https://")
+        assert record["reviewed_at"]
+        assert len(record["text"]) >= 100