Add jokes, spelling sub-flows and fix composite question blocking

- Add Huey Jokes sub-flow with randomized precursor/bridge messages
  using new random_choice() CEL function
- Add Huey Spelling sub-flow with 3-round pick-the-correct-spelling
  game, difficulty matched to reading ability
- Add CMS content loaders for jokes (from CSV) and spelling questions
- Fix composite sub-flows not blocking on questions when entered via
  condition auto-chain (questions were dumped as messages instead of
  pausing for user input)
- Add days_since() CEL function for date comparisons
- Update Huey Bookbot flow to v3.0.0 with jokes, spelling composites
  and stale collection warning
- Make /school/{id}/bot endpoint public (no auth required)
- Fix KeyError on missing experiments key in school info

Author: hardbyte

app/api/schools.py

@@ -215,9 +215,9 @@ async def school_exists():
     return True
 
 
-@router.get("/school/{wriveted_identifier}/bot")
+@public_router.get("/school/{wriveted_identifier}/bot")
 async def get_school_bookbot_type(
-    school: School = Permission("read", get_school_from_wriveted_id),
+    school: School = Depends(get_school_from_wriveted_id),
 ):
     """
     Returns the Huey-relevant information for a school, i.e. whether they've opted for Huey's Collection,

app/services/cel_evaluator.py

@@ -1,5 +1,7 @@
 """CEL (Common Expression Language) evaluator service for safe expression evaluation."""
 
+import random
+from datetime import datetime, timezone
 from typing import Any, Callable, Dict, List, Union
 
 from cel import Context, evaluate
@@ -108,6 +110,29 @@ def _cel_top_keys(d: Dict[str, Any], n: int = 5) -> List[str]:
     return [k for k, _ in numeric_items[:n]]
 
 
+def _cel_days_since(iso_date_str: str) -> int:
+    """Return number of days between an ISO datetime string and now.
+
+    Returns -1 if the input is empty/None or unparseable.
+    """
+    if not iso_date_str or not isinstance(iso_date_str, str):
+        return -1
+    try:
+        dt = datetime.fromisoformat(iso_date_str.replace("Z", "+00:00"))
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return (datetime.now(timezone.utc) - dt).days
+    except (ValueError, TypeError):
+        return -1
+
+
+def _cel_random_choice(items: List[Any]) -> Any:
+    """Pick a random item from a list."""
+    if not items:
+        return None
+    return random.choice(items)
+
+
 # Registry of custom functions available in CEL expressions
 CUSTOM_CEL_FUNCTIONS: Dict[str, Callable] = {
     "sum": _cel_sum,
@@ -122,6 +147,8 @@ def _cel_top_keys(d: Dict[str, Any], n: int = 5) -> List[str]:
     "flatten": _cel_flatten,
     "collect": _cel_collect,
     "top_keys": _cel_top_keys,
+    "days_since": _cel_days_since,
+    "random_choice": _cel_random_choice,
 }
 
 

app/services/chat_runtime.py

@@ -1651,6 +1651,26 @@ async def _try_return_to_parent_flow(
         session = await self._refresh_session(db, session)
 
         if return_result:
+            # Check if the return node (or its auto-chained successor)
+            # produced a question — e.g. condition → composite → question.
+            if return_result.get("type") == "question":
+                node_id = return_result.get("node_id")
+                flow_id = _to_uuid(return_result.get("sub_flow_id"))
+                if node_id:
+                    result["current_node_id"] = node_id
+                    options = return_result.get("options", [])
+                    session = await chat_repo.update_session_state(
+                        db,
+                        session_id=session.id,
+                        state_updates={"system": {"_current_options": options}},
+                        current_node_id=node_id,
+                        current_flow_id=flow_id,
+                        expected_revision=session.revision,
+                    )
+                result["input_request"] = self._build_input_request(return_result)
+                result["awaiting_input"] = True
+                return result
+
             # Extract actual messages from the result
             if return_result.get("type") == "messages":
                 result["messages"].extend(return_result.get("messages", []))
@@ -1709,8 +1729,40 @@ async def _try_return_to_parent_flow(
                     ):
                         node_result = await self.process_node(db, next_node, session)
                         session = await self._refresh_session(db, session)
+                        self.logger.debug(
+                            "Return-chain processed node",
+                            node_id=next_node.node_id,
+                            node_type=str(next_node.node_type),
+                            result_type=node_result.get("type")
+                            if node_result
+                            else None,
+                            result_keys=list(node_result.keys()) if node_result else [],
+                        )
                         if node_result:
-                            if node_result.get("type") == "messages":
+                            if node_result.get("type") == "question":
+                                # Composite (or other node) returned a question
+                                # — treat it like the dict-question branch below
+                                node_id = node_result.get("node_id")
+                                flow_id = _to_uuid(node_result.get("sub_flow_id"))
+                                if node_id:
+                                    result["current_node_id"] = node_id
+                                    options = node_result.get("options", [])
+                                    session = await chat_repo.update_session_state(
+                                        db,
+                                        session_id=session.id,
+                                        state_updates={
+                                            "system": {"_current_options": options}
+                                        },
+                                        current_node_id=node_id,
+                                        current_flow_id=flow_id,
+                                        expected_revision=session.revision,
+                                    )
+                                result["input_request"] = self._build_input_request(
+                                    node_result
+                                )
+                                result["awaiting_input"] = True
+                                break
+                            elif node_result.get("type") == "messages":
                                 result["messages"].extend(
                                     node_result.get("messages", [])
                                 )

app/tests/unit/test_cel_aggregation.py

@@ -421,6 +421,8 @@ def test_context_includes_all_custom_functions(self):
             "flatten",
             "collect",
             "top_keys",
+            "days_since",
+            "random_choice",
         }
         assert set(CUSTOM_CEL_FUNCTIONS.keys()) == expected_functions
 

scripts/deploy_huey_flow.py

@@ -42,6 +42,8 @@
     {"file": "huey-profile-flow.json", "seed_key": "huey-profile", "name": "Huey Profile"},
     {"file": "huey-preferences-flow.json", "seed_key": "huey-preferences", "name": "Huey Preferences"},
     {"file": "huey-recommendation-flow.json", "seed_key": "huey-recommendation", "name": "Huey Recommendation"},
+    {"file": "huey-jokes-flow.json", "seed_key": "huey-jokes", "name": "Huey Jokes"},
+    {"file": "huey-spelling-flow.json", "seed_key": "huey-spelling", "name": "Huey Spelling"},
 ]
 
 

scripts/fixtures/admin-ui-seed.json

@@ -544,6 +544,8 @@
     {"flow_file": "huey-profile-flow.json"},
     {"flow_file": "huey-preferences-flow.json"},
     {"flow_file": "huey-recommendation-flow.json"},
+    {"flow_file": "huey-jokes-flow.json"},
+    {"flow_file": "huey-spelling-flow.json"},
     {
       "flow_file": "huey-bookbot-flow.json",
       "theme_seed_key": "huey-bookbot-theme"

scripts/fixtures/huey-bookbot-flow.json

@@ -1,8 +1,8 @@
 {
   "seed_key": "huey-bookbot",
   "name": "Huey Bookbot",
-  "description": "Kid-friendly book recommendation chatbot. Asks age, reading ability, and preference questions, then recommends books.",
-  "version": "2.0.0",
+  "description": "Kid-friendly book recommendation chatbot. Asks age, reading ability, and preference questions, then recommends books. Optionally offers jokes and a spelling game.",
+  "version": "3.0.0",
   "entry_node_id": "welcome",
   "visibility": "wriveted",
   "trace_enabled": true,
@@ -56,31 +56,80 @@
           ],
           "variable": "temp.school_confirm"
         },
-        "position": {"x": 700, "y": 150}
+        "position": {"x": 700, "y": 100}
+      },
+      {
+        "id": "check_stale_collection",
+        "type": "condition",
+        "content": {
+          "conditions": [
+            {"if": "has(context.collection_updated_at) && days_since(context.collection_updated_at) > 1095", "then": "$0"}
+          ],
+          "default_path": "default"
+        },
+        "position": {"x": 900, "y": 100}
+      },
+      {
+        "id": "stale_collection_msg",
+        "type": "message",
+        "content": {
+          "messages": [
+            {"type": "text", "text": "Just a heads up \u2014 it looks like your school's book list hasn't been updated in a while, so my recommendations might not match what's on the shelves right now."},
+            {"type": "text", "text": "Your librarian can upload a new CSV at hueybooks.com to help me find the latest books! \ud83d\udcda"}
+          ]
+        },
+        "position": {"x": 1100, "y": 0}
       },
       {
         "id": "profile_composite",
         "type": "composite",
         "content": {
           "composite_flow_seed_key": "huey-profile"
         },
-        "position": {"x": 900, "y": 300}
+        "position": {"x": 1100, "y": 300}
       },
       {
         "id": "preferences_composite",
         "type": "composite",
         "content": {
           "composite_flow_seed_key": "huey-preferences"
         },
-        "position": {"x": 1100, "y": 300}
+        "position": {"x": 1300, "y": 300}
       },
       {
         "id": "recommendation_composite",
         "type": "composite",
         "content": {
           "composite_flow_seed_key": "huey-recommendation"
         },
-        "position": {"x": 1300, "y": 300}
+        "position": {"x": 1500, "y": 300}
+      },
+      {
+        "id": "check_jokes_enabled",
+        "type": "condition",
+        "content": {
+          "conditions": [
+            {"if": "!(has(context.experiments) && has(context.experiments.no_jokes) && context.experiments.no_jokes == true)", "then": "$0"}
+          ],
+          "default_path": "default"
+        },
+        "position": {"x": 1700, "y": 300}
+      },
+      {
+        "id": "jokes_composite",
+        "type": "composite",
+        "content": {
+          "composite_flow_seed_key": "huey-jokes"
+        },
+        "position": {"x": 1900, "y": 200}
+      },
+      {
+        "id": "spelling_composite",
+        "type": "composite",
+        "content": {
+          "composite_flow_seed_key": "huey-spelling"
+        },
+        "position": {"x": 2100, "y": 300}
       },
       {
         "id": "end_msg",
@@ -90,7 +139,7 @@
             {"type": "text", "text": "Happy reading! Remember, the best book is the one YOU enjoy. \ud83d\ude0a"}
           ]
         },
-        "position": {"x": 1500, "y": 300}
+        "position": {"x": 2300, "y": 300}
       },
       {
         "id": "restart_choice",
@@ -104,7 +153,7 @@
           ],
           "variable": "temp.restart_choice"
         },
-        "position": {"x": 1700, "y": 300}
+        "position": {"x": 2500, "y": 300}
       },
       {
         "id": "goodbye",
@@ -114,18 +163,25 @@
             {"type": "text", "text": "Thanks for chatting with me! See you next time! \ud83d\udc4b"}
           ]
         },
-        "position": {"x": 1900, "y": 450}
+        "position": {"x": 2700, "y": 450}
       }
     ],
     "connections": [
       {"source": "welcome", "target": "greeting_response", "type": "default"},
       {"source": "greeting_response", "target": "check_school", "type": "default"},
       {"source": "check_school", "target": "school_confirm", "type": "$0"},
       {"source": "check_school", "target": "profile_composite", "type": "default"},
-      {"source": "school_confirm", "target": "profile_composite", "type": "default"},
+      {"source": "school_confirm", "target": "check_stale_collection", "type": "default"},
+      {"source": "check_stale_collection", "target": "stale_collection_msg", "type": "$0"},
+      {"source": "check_stale_collection", "target": "profile_composite", "type": "default"},
+      {"source": "stale_collection_msg", "target": "profile_composite", "type": "default"},
       {"source": "profile_composite", "target": "preferences_composite", "type": "default"},
       {"source": "preferences_composite", "target": "recommendation_composite", "type": "default"},
-      {"source": "recommendation_composite", "target": "end_msg", "type": "default"},
+      {"source": "recommendation_composite", "target": "check_jokes_enabled", "type": "default"},
+      {"source": "check_jokes_enabled", "target": "jokes_composite", "type": "$0"},
+      {"source": "check_jokes_enabled", "target": "spelling_composite", "type": "default"},
+      {"source": "jokes_composite", "target": "spelling_composite", "type": "default"},
+      {"source": "spelling_composite", "target": "end_msg", "type": "default"},
       {"source": "end_msg", "target": "restart_choice", "type": "default"},
       {"source": "restart_choice", "target": "welcome", "type": "$0", "conditions": {"if": {"var": "temp.restart_choice", "eq": "restart"}}},
       {"source": "restart_choice", "target": "goodbye", "type": "default"}