Initial commit: Spelling Bee Tutor (NeMo Guardrails demo)

.gitignore

@@ -0,0 +1,9 @@
+# Python
+__pycache__/
+*.pyc
+.venv/
+# macOS
+.DS_Store
+
+# screenshots
+screenshots/*.orig

app.py

@@ -0,0 +1,243 @@
+import csv
+from types import SimpleNamespace
+from nemoguardrails import LLMRails, RailsConfig
+
+# -----------------------------
+# Load CSV (ground-truth data)
+# -----------------------------
+words = []
+with open("words.csv", newline="", encoding="utf-8") as f:
+    for row in csv.DictReader(f):
+        try:
+            row["difficulty"] = int(row.get("difficulty", 5))
+        except Exception:
+            row["difficulty"] = 5
+        words.append(row)
+
+# sort hardest -> easiest
+words.sort(key=lambda r: r["difficulty"], reverse=True)
+
+ROUND_SIZE = 5
+state = {"index": 0, "in_round": 0, "current": None, "correct": 0}
+
+
+def _get_row(word: str):
+    if not word:
+        return None
+    wl = word.strip().lower()
+    for r in words:
+        if r["word"].strip().lower() == wl:
+            return r
+    return None
+
+
+# -----------------------------
+# Actions (called from Colang v1)
+# -----------------------------
+def get_next_word():
+    """Return next word for the round, or empty string if round finished."""
+    if state["in_round"] >= ROUND_SIZE or state["index"] >= len(words):
+        return ""
+    w = words[state["index"]]["word"]
+    state["current"] = w
+    state["index"] += 1
+    state["in_round"] += 1
+    return w
+
+
+def get_current():
+    """Return the current word (or empty string)."""
+    return state.get("current") or ""
+
+
+def check_spelling(word, attempt):
+    """Exact (case-insensitive) match check. Returns 'true' or 'false'."""
+    ok = (attempt or "").strip().lower() == (word or "").strip().lower()
+    if ok:
+        state["correct"] += 1
+    return "true" if ok else "false"
+
+
+def get_definition(word):
+    r = _get_row(word)
+    return r["definition"] if r and r.get("definition") else "No definition found."
+
+
+def get_origin(word):
+    r = _get_row(word)
+    return r["origin"] if r and r.get("origin") else "No origin found."
+
+
+def get_sentence(word):
+    r = _get_row(word)
+    return r["sentence"] if r and r.get("sentence") else "No example available."
+
+
+def get_progress():
+    return f"Score this round: {state['correct']}/{state['in_round']}."
+
+
+# -----------------------------
+# Fully compatible Dummy LLM for NeMo Guardrails 0.15
+# -----------------------------
+class DummyLLM:
+    """Return a LangChain-like LLMResult with generations + llm_output."""
+    def __init__(self, text: str = ""):
+        self._text = text
+
+    def _result(self):
+        gen = SimpleNamespace(text=self._text)
+        # Guardrails expects these fields to exist
+        return SimpleNamespace(generations=[[gen]], llm_output={})
+
+    # async APIs Guardrails may use
+    async def agenerate_prompt(self, *args, **kwargs):
+        return self._result()
+
+    async def agenerate(self, *args, **kwargs):
+        return self._result()
+
+    # sync fallbacks
+    def generate_prompt(self, *args, **kwargs):
+        return self._result()
+
+    def generate(self, *args, **kwargs):
+        return self._result()
+
+
+# -----------------------------
+# Wire up NeMo Guardrails (v1)
+# -----------------------------
+config = RailsConfig.from_path("rails")
+rails = LLMRails(config, llm=DummyLLM())  # keep everything offline
+
+for fn in [
+    get_next_word,
+    get_current,
+    check_spelling,
+    get_definition,
+    get_origin,
+    get_sentence,
+    get_progress,
+]:
+    rails.register_action(fn)
+
+
+# -----------------------------
+# Response helpers
+# -----------------------------
+def extract_assistant_text(resp) -> str:
+    """Try to pull assistant/bot text from various Guardrails return shapes."""
+    if isinstance(resp, dict):
+        # Common path
+        if resp.get("content"):
+            return resp["content"]
+
+        # Messages list
+        msgs = resp.get("messages") or resp.get("output", {}).get("messages", [])
+        if isinstance(msgs, list) and msgs:
+            parts = []
+            for m in msgs:
+                if isinstance(m, dict) and m.get("role") in ("assistant", "bot"):
+                    txt = m.get("content") or m.get("text") or ""
+                    if txt:
+                        parts.append(txt)
+            if parts:
+                return "\n".join(parts)
+
+        # Some builds emit a single message-like dict
+        if resp.get("role") in ("assistant", "bot") and resp.get("content"):
+            return resp["content"]
+
+    # Fallback
+    return ""
+
+
+def run_local_engine(user: str) -> str:
+    """Deterministic, no-LLM fallback that mirrors our flows."""
+    u = (user or "").strip().lower()
+
+    if u in ("start", "start quiz", "begin", "quiz me"):
+        w = get_next_word()
+        if not w:
+            p = get_progress()
+            return f"Round complete. {p}"
+        return f"Okay! We'll do 5 words this round, hardest to easiest. Ready?\nSpell this word: {w}"
+
+    if u == "definition":
+        c = get_current()
+        d = get_definition(c)
+        return f"Definition: {d}"
+
+    if u == "origin":
+        c = get_current()
+        o = get_origin(c)
+        return f"Origin: {o}"
+
+    if u == "sentence":
+        c = get_current()
+        s = get_sentence(c)
+        return f"Example: {s}"
+
+    if u == "next":
+        n = get_next_word()
+        if not n:
+            p = get_progress()
+            return f"Round complete. {p}"
+        return f"Next word: {n}"
+
+    if u in ("stop", "end", "finish"):
+        p = get_progress()
+        return f"Stopping the quiz. {p}"
+
+    # Otherwise treat as spelling attempt
+    c = get_current()
+    if not c:
+        # If user types a word before starting
+        w = get_next_word()
+        if not w:
+            p = get_progress()
+            return f"Round complete. {p}"
+        # Re-run attempt logic on new word
+        c = w
+
+    ok = check_spelling(c, user)
+    if ok == "true":
+        n = get_next_word()
+        if not n:
+            p = get_progress()
+            return f"✅ Correct!\nRound complete. {p}"
+        return f"✅ Correct!\nNext word: {n}"
+    else:
+        return "❌ Not quite. Try again or ask for definition/origin/sentence."
+
+
+# -----------------------------
+# Tiny CLI loop
+# -----------------------------
+print(
+    "Type: 'start' (or 'start quiz'), then 'definition'/'origin'/'sentence', "
+    "type your spelling attempt, 'next', or 'stop'."
+)
+
+while True:
+    user_in = input("You: ").strip()
+    if not user_in:
+        continue
+
+    # Try Guardrails first
+    try:
+        resp = rails.generate(messages=[{"role": "user", "content": user_in}])
+        tutor_text = extract_assistant_text(resp)
+    except Exception:
+        tutor_text = ""
+
+    # Fallback to our local engine if Guardrails produced nothing visible
+    if not tutor_text:
+        tutor_text = run_local_engine(user_in)
+
+    print("Tutor:", tutor_text or "[no response]")
+
+    if ("Round complete" in tutor_text) or ("Stopping the quiz" in tutor_text):
+        break
+

rails/colang/v2/flows.co

@@ -0,0 +1,79 @@
+# ===== Minimal Colang v1 (no intents, no loop, no parentheses) =====
+
+# Bot actions available from Python:
+# - get_next_word
+# - get_current
+# - check_spelling
+# - get_definition
+# - get_origin
+# - get_sentence
+# - get_progress
+
+# Start quiz (supports "start" and "start quiz")
+define flow start_flow_a
+  user says "start"
+  bot says "Okay! We'll do 5 words this round, hardest to easiest. Ready?"
+  do get_next_word as $w
+  bot says "Spell this word: {{$w}}"
+
+define flow start_flow_b
+  user says "start quiz"
+  bot says "Okay! We'll do 5 words this round, hardest to easiest. Ready?"
+  do get_next_word as $w
+  bot says "Spell this word: {{$w}}"
+
+# Definition / origin / sentence for current word
+define flow definition_flow
+  user says "definition"
+  do get_current as $c
+  do get_definition $c as $d
+  bot says "Definition: {{$d}}"
+
+define flow origin_flow
+  user says "origin"
+  do get_current as $c
+  do get_origin $c as $o
+  bot says "Origin: {{$o}}"
+
+define flow sentence_flow
+  user says "sentence"
+  do get_current as $c
+  do get_sentence $c as $s
+  bot says "Example: {{$s}}"
+
+# Spelling attempt: capture ANY free text that isn't one of our commands
+define flow answer_flow
+  user says $attempt
+  do get_current as $c
+  do check_spelling $c $attempt as $ok
+  if $ok == "true"
+    bot says "✅ Correct!"
+    do get_next_word as $n
+    if $n == ""
+      do get_progress as $p
+      bot says "Round complete. {{$p}}"
+    else
+      bot says "Next word: {{$n}}"
+  else
+    bot says "❌ Not quite. Try again or ask for definition/origin/sentence."
+
+# Skip to next word
+define flow next_flow
+  user says "next"
+  do get_next_word as $n2
+  if $n2 == ""
+    do get_progress as $p2
+    bot says "Round complete. {{$p2}}"
+  else
+    bot says "Next word: {{$n2}}"
+
+# End quiz
+define flow end_flow_a
+  user says "stop"
+  do get_progress as $p3
+  bot says "Stopping the quiz. {{$p3}}"
+
+define flow end_flow_b
+  user says "end"
+  do get_progress as $p4
+  bot says "Stopping the quiz. {{$p4}}"

rails/rails.yaml

@@ -0,0 +1,8 @@
+rails:
+  config:
+    allow_smalltalk: false
+    input_character_limit: 256
+
+constraints:
+  - "Stay on the spelling-bee quiz task only."
+  - "If the user asks for unrelated content, gently steer back to the quiz."

requirements.txt

@@ -0,0 +1 @@
+nemoguardrails==0.9.0

words.csv

@@ -0,0 +1,7 @@
+word,difficulty,definition,origin,sentence
+acrimonious,9,angry and bitter,Latin "acer" (sharp),The debate turned acrimonious quickly.
+bibliophile,8,a person who loves books,Greek "biblion"+"philos",As a bibliophile, she spends hours in libraries.
+capricious,7,impulsive and unpredictable,Italian "capriccio",The stock’s capricious rise surprised investors.
+dilettante,6,an amateur who dabbles,Italian "dilettare",He’s a dilettante in classical music.
+ephemeral,5,lasting a very short time,Greek "ephemeros",Beauty is ephemeral.
+facsimile,4,an exact copy,Latin "facere"+"similis",They sent a facsimile of the contract.