[ask-a-sailor] ABA-informed dialogue layer: Coach + Reflect modes, Social Stories schema

packages/ask-a-sailor/src/prompts/__init__.py

@@ -0,0 +1,11 @@
+from prompts.system import (  # noqa: F401
+    SYSTEM_PROMPT,
+    COACH_SYSTEM_PROMPT,
+    REFLECT_SYSTEM_PROMPT,
+    PARENT_QUESTION_CATEGORIES,
+)
+from prompts.social_stories import (  # noqa: F401
+    SocialStory,
+    TonePreset,
+    DisclosureIntent,
+)

packages/ask-a-sailor/src/prompts/social_stories.py

@@ -0,0 +1,107 @@
+"""
+Social Stories — Corpus Schema
+==============================
+Pydantic model for ABA-informed Social Stories used by the Coach and
+Reflect prompt modes.
+
+A Social Story is a short narrative that describes a situation, skill,
+or concept using a specific format.  These are used with youth sailors
+— especially neurodivergent youth — to preview upcoming activities,
+process past experiences, and reduce anxiety around transitions.
+
+Schema fields follow the issue specification:
+  setting, roles, objective, sensory_profile, tone_preset,
+  disclosure_intent
+
+References:
+  - Carol Gray's Social Stories™ criteria (2015)
+  - ASD-iLLM (Lai et al., EMNLP 2025)
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class TonePreset(str, Enum):
+    """Pre-defined tone options for Social Story narration."""
+
+    calm = "calm"
+    encouraging = "encouraging"
+    matter_of_fact = "matter-of-fact"
+    playful = "playful"
+
+
+class DisclosureIntent(str, Enum):
+    """How openly the story addresses neurodivergence or disability."""
+
+    none = "none"                # No mention of diagnosis/neurodivergence
+    normalising = "normalising"  # Frames differences as normal variation
+    explicit = "explicit"        # Directly names the condition (only if family consents)
+
+
+class SocialStory(BaseModel):
+    """Schema for a single Social Story in the Ask a Sailor corpus.
+
+    Example
+    -------
+    >>> story = SocialStory(
+    ...     setting="Lakewood Yacht Club boat ramp, Saturday morning",
+    ...     roles=["sailor (child)", "instructor", "dock volunteer"],
+    ...     objective="Preview the steps for launching an Opti from the dock",
+    ...     sensory_profile="Loud halyards, wind, cold spray, life-jacket pressure",
+    ...     tone_preset=TonePreset.calm,
+    ...     disclosure_intent=DisclosureIntent.normalising,
+    ... )
+    """
+
+    setting: str = Field(
+        ...,
+        min_length=1,
+        description=(
+            "Where and when the story takes place "
+            "(e.g., 'Houston Yacht Club dock, first day of camp')."
+        ),
+    )
+
+    roles: list[str] = Field(
+        ...,
+        min_length=1,
+        description=(
+            "People involved in the story "
+            "(e.g., ['sailor (child)', 'instructor', 'parent'])."
+        ),
+    )
+
+    objective: str = Field(
+        ...,
+        min_length=1,
+        description=(
+            "What the story aims to help the reader understand or do "
+            "(e.g., 'Know what to expect during capsize drill')."
+        ),
+    )
+
+    sensory_profile: Optional[str] = Field(
+        default=None,
+        description=(
+            "Sensory elements the reader may encounter "
+            "(e.g., 'Loud horn, cold water splash, rocking motion')."
+        ),
+    )
+
+    tone_preset: TonePreset = Field(
+        default=TonePreset.calm,
+        description="Narrative tone for the generated story.",
+    )
+
+    disclosure_intent: DisclosureIntent = Field(
+        default=DisclosureIntent.none,
+        description=(
+            "Level of neurodivergence disclosure. "
+            "Use 'explicit' ONLY with prior family consent."
+        ),
+    )

packages/ask-a-sailor/src/prompts/system.py

@@ -3,10 +3,43 @@
 =====================================================
 Centralized prompt definitions for the Ask a Sailor RAG agent.
 Import these from agent.py and api/main.py rather than duplicating.
+
+Prompt modes:
+  - SYSTEM_PROMPT  : default RAG assistant for parent questions
+  - COACH_SYSTEM_PROMPT  : ABA-informed, in-the-moment coaching for youth sailors
+  - REFLECT_SYSTEM_PROMPT: ABA-informed, post-session metacognitive reflection
+
+References:
+  - ASD-iLLM (Lai et al., EMNLP 2025): github.com/Shuzhong-Lai/ASD-iLLM
+  - ABA with GPT blueprint: huggingface.co/blog/Clock070303/aba-for-gpt
+  - Noora RCT: doi:10.1007/s10803-025-06734-x
 """
 
 from __future__ import annotations
 
+# ---------------------------------------------------------------------------
+# Shared boundary-hygiene block (injected into every ABA-informed prompt)
+# ---------------------------------------------------------------------------
+
+_BOUNDARY_BLOCK = """
+BOUNDARY RULES — FOLLOW STRICTLY:
+- You are NOT a licensed therapist, psychologist, or medical professional.
+- NEVER diagnose or suggest a diagnosis of autism, ADHD, anxiety, or any condition.
+- NEVER recommend medication or specific therapeutic interventions.
+- If a user asks for a diagnosis or clinical advice, respond with:
+  "That's an important question — and one best answered by a qualified professional.
+   I'd recommend reaching out to your pediatrician or a board-certified behavior
+   analyst (BCBA) who can give you personalised guidance."
+- Redirect clinical questions to: pediatrician, BCBA, licensed counselor, or
+  school psychologist as appropriate.
+- You MAY share general ABA-informed communication strategies (e.g., positive
+  reinforcement, visual supports, Social Stories) without framing them as treatment.
+""".strip()
+
+# ---------------------------------------------------------------------------
+# Default RAG assistant prompt (unchanged from original)
+# ---------------------------------------------------------------------------
+
 SYSTEM_PROMPT = """You are Ask a Sailor, a friendly and knowledgeable AI assistant
 that helps parents, families, and newcomers learn about youth sailing programs,
 summer camps, and sailing clubs.
@@ -36,6 +69,64 @@
 4. An encouraging note for first-timers (when appropriate)
 """
 
+# ---------------------------------------------------------------------------
+# Coach mode — ABA-informed, in-the-moment support
+# ---------------------------------------------------------------------------
+
+COACH_SYSTEM_PROMPT = f"""You are Ask a Sailor Coach, an ABA-informed support
+assistant that helps parents and instructors navigate real-time situations with
+youth sailors — especially those who may be neurodivergent, anxious, or new to
+group activities on the water.
+
+{_BOUNDARY_BLOCK}
+
+PERSONA — COACH (in-the-moment):
+- You provide calm, concrete, actionable guidance for situations happening RIGHT NOW.
+- Use simple, direct language a stressed parent or volunteer coach can act on immediately.
+- Suggest positive-reinforcement strategies: praise specific behaviours, not traits.
+- Offer sensory-aware tips (e.g., noise-reducing ear protection, shaded rest areas,
+  predictable routines) when the situation involves sensory overload.
+- Frame challenges with strengths-based language ("your child is building resilience"
+  rather than "your child is struggling").
+- When appropriate, suggest brief Social Stories to preview what comes next
+  (e.g., "First we rig the boat, then we push off from the dock").
+- Keep responses short and structured: What to do → Why it helps → What to say.
+
+TONE: Warm, steady, encouraging — like a seasoned sailing coach who also
+understands child development.
+"""
+
+# ---------------------------------------------------------------------------
+# Reflect mode — ABA-informed, post-session metacognitive reflection
+# ---------------------------------------------------------------------------
+
+REFLECT_SYSTEM_PROMPT = f"""You are Ask a Sailor Reflect, an ABA-informed
+reflection assistant that helps parents, instructors, and young sailors
+process experiences AFTER a sailing session, camp day, or regatta.
+
+{_BOUNDARY_BLOCK}
+
+PERSONA — REFLECT (post-session metacognitive):
+- You help the user look back on what happened, identify wins, and plan for next time.
+- Use open-ended, metacognitive questions: "What felt easiest today?",
+  "What would you do differently next time?"
+- Reinforce effort and process over outcome ("You stayed on the boat even when it
+  was windy — that takes real courage").
+- Help build self-awareness by naming emotions without judgement.
+- Suggest concrete adjustments for the next session (e.g., arriving early to
+  reduce transition stress, bringing a familiar comfort object).
+- When relevant, help the parent or instructor create a brief Social Story
+  for the next session based on what happened today.
+- Use longer, more reflective responses than Coach mode; paragraphs are fine.
+
+TONE: Thoughtful, validating, and gently curious — like a mentor reviewing
+game film with a young athlete.
+"""
+
+# ---------------------------------------------------------------------------
+# Question categories
+# ---------------------------------------------------------------------------
+
 PARENT_QUESTION_CATEGORIES = [
     "cost/pricing",
     "age requirements",