Initial Towards AI helper chatbot

.env.example

@@ -0,0 +1,25 @@
+# Public domains where the helper widget is allowed to run.
+HELPER_ALLOWED_ORIGINS=https://academy.towardsai.net,https://towardsai.net,https://www.towardsai.net
+HELPER_ALLOWED_HOSTS=academy.towardsai.net,towardsai.net,www.towardsai.net
+
+# Gemini.
+GEMINI_API_KEY=
+HELPER_MODEL=gemini-2.5-flash
+HELPER_MAX_OUTPUT_TOKENS=420
+
+# Hard public rate limits.
+HELPER_RATE_LIMIT_PER_MINUTE=3
+HELPER_RATE_LIMIT_PER_DAY=20
+HELPER_GLOBAL_RATE_LIMIT_PER_MINUTE=120
+
+# Request caps.
+HELPER_MAX_BODY_BYTES=65536
+HELPER_MAX_QUERY_CHARS=600
+HELPER_MAX_HISTORY_TURNS=8
+
+# Optional Opik monitoring.
+OPIK_ENABLED=false
+OPIK_PROJECT_NAME=towards-ai-helper
+OPIK_WORKSPACE=
+OPIK_API_KEY=
+OPIK_MAX_TEXT_CHARS=4000

.github/workflows/ci.yml

@@ -0,0 +1,76 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      run_live_chat:
+        description: "Run the live /chat smoke test against the deployed Space"
+        required: false
+        default: "false"
+        type: choice
+        options:
+          - "false"
+          - "true"
+  schedule:
+    - cron: "41 */6 * * *"
+
+jobs:
+  fast-tests:
+    name: Fast Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Ruff
+        run: uv run ruff check .
+
+      - name: Widget syntax
+        run: node --check static/widget.js
+
+      - name: Pytest
+        run: uv run pytest -m "not live" -p no:cacheprovider tests
+
+  live-smoke:
+    name: Live HF Smoke
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    if: github.event_name == 'workflow_dispatch' || github.event_name == 'schedule'
+
+    env:
+      LIVE_SPACE_BASE_URL: ${{ vars.LIVE_SPACE_BASE_URL || 'https://towardsai-tutors-tai-helper.hf.space' }}
+      RUN_LIVE_CHAT_SMOKE: ${{ github.event.inputs.run_live_chat || 'false' }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Live smoke tests
+        run: uv run pytest -m live -p no:cacheprovider tests/test_live_smoke.py

.github/workflows/keepalive.yml

@@ -0,0 +1,24 @@
+name: HF Space Keepalive
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "29 */12 * * *"
+
+env:
+  SPACE_BASE_URL: https://towardsai-tutors-tai-helper.hf.space
+
+jobs:
+  ping:
+    name: Ping HF Space
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: Health check
+        run: |
+          curl --fail --show-error --silent --max-time 180 "$SPACE_BASE_URL/healthz"
+
+      - name: Widget check
+        run: |
+          curl --fail --show-error --silent --max-time 60 "$SPACE_BASE_URL/widget.js" | grep -q "Towards AI Helper"

.gitignore

@@ -0,0 +1,7 @@
+.env
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.DS_Store

Dockerfile

@@ -0,0 +1,19 @@
+FROM python:3.13-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PORT=7860
+
+WORKDIR /opt/tai-helper
+
+COPY pyproject.toml README.md ./
+COPY tai_helper ./tai_helper
+COPY static ./static
+COPY data ./data
+
+RUN pip install --no-cache-dir uv \
+    && uv pip install --system -e .
+
+EXPOSE 7860
+
+CMD ["uvicorn", "tai_helper.api:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,58 @@
 ---
-title: Tai Helper
-emoji: 🐢
-colorFrom: indigo
-colorTo: gray
+title: Towards AI Helper
 sdk: docker
+app_port: 7860
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Towards AI Helper
+
+Public sales helper for anonymous visitors on Towards AI Academy and
+TowardsAI.net. It helps prospective students choose courses, bundles,
+mentorship, free resources, the book, or B2B training/consulting.
+
+It is deliberately separate from the Thinkific lesson tutor:
+
+- This helper appears only on public, sitemap-discoverable pages.
+- It hides when a visitor appears signed in.
+- The first message must be one of the fixed prompt buttons.
+- It uses Gemini 2.5 Flash with strict rate limits and concise answers.
+- It does not answer general AI questions or give away course lesson content.
+
+## Local Setup
+
+```bash
+cd /Users/louis/Documents/GitHub/tai-helper
+uv sync
+cp .env.example .env
+uv run uvicorn tai_helper.api:app --host 0.0.0.0 --port 8001
+```
+
+## Public Widget Snippet
+
+Add this to public site footer code on `academy.towardsai.net` and
+`towardsai.net`:
+
+```html
+<script
+  src="https://YOUR-HF-SPACE/widget.js"
+  data-api-base="https://YOUR-HF-SPACE"
+  defer
+></script>
+```
+
+The widget fetches `/api/helper/config`, checks the current public URL, hides on
+signed-in sessions, and starts as a bottom-right `Ask the helper` bubble.
+
+## Monitoring
+
+Enable Opik:
+
+```bash
+OPIK_ENABLED=true
+OPIK_API_KEY=...
+OPIK_PROJECT_NAME=towards-ai-helper
+```
+
+Traces include URL, selected prompt, model, token usage, latency, and sources.
+They intentionally avoid logging the full page dataset.

data/assistant_notes.json

@@ -0,0 +1,92 @@
+{
+  "assistant_name": "Towards AI Helper",
+  "contact_email": "louis@towardsai.net",
+  "primary_goal": "Help prospective students and companies choose Towards AI courses, bundles, mentorship, free resources, book resources, or B2B training/consulting.",
+  "forced_prompts": [
+    "I want help deciding which course to take.",
+    "I want help to integrate AI into my company",
+    "I want a training inside my company",
+    "I'm looking for more free resources to learn before committing to buying a course",
+    "I want to find mentors"
+  ],
+  "guardrails": [
+    "Only answer questions related to Towards AI courses, bundles, mentorship, B2B training/consulting, the book, community, or free learning resources.",
+    "Do not teach valuable course lesson content, solve coding homework, or provide general AI tutoring. Briefly explain that the helper is for choosing the right Towards AI path and redirect to relevant pages.",
+    "Keep answers concise and useful to control costs.",
+    "For B2B, company training, and consulting leads, ask for company/team context and recommend emailing louis@towardsai.net.",
+    "For coupon code requests, do not provide a code. If the user insists, tell them to email louis@towardsai.net with context and what they need.",
+    "For eager learners who want broad access, recommend the Get it all bundle as the strongest value option."
+  ],
+  "course_routing": [
+    {
+      "name": "Get it all! From Novice to Expert",
+      "url": "https://academy.towardsai.net/bundles/get-it-all",
+      "when_to_recommend": "Best value for motivated learners who want broad access across the academy or are serious about going from fundamentals to advanced AI engineering."
+    },
+    {
+      "name": "Python for GenAI / Become a LLM Developer and Python Pro",
+      "url": "https://academy.towardsai.net/courses/python-for-genai",
+      "when_to_recommend": "Best first step for beginners, non-coders, or people who need Python foundations before building LLM products."
+    },
+    {
+      "name": "Full Stack AI Engineering / Beginner to Advanced LLM Dev",
+      "url": "https://academy.towardsai.net/courses/beginner-to-advanced-llm-dev",
+      "when_to_recommend": "Best for builders who want to ship LLM products with RAG, context engineering, deployment, and product-oriented AI engineering."
+    },
+    {
+      "name": "Agent Engineering: Building Multi-Agent Systems",
+      "url": "https://academy.towardsai.net/courses/agent-engineering",
+      "when_to_recommend": "Best for intermediate to advanced engineers who know Python/APIs and want production-grade autonomous agents, evaluation, monitoring, and deployment."
+    },
+    {
+      "name": "No-Code AI Mastery for Businesses and Professionals",
+      "url": "https://academy.towardsai.net/courses/ai-business-professionals",
+      "when_to_recommend": "Best for business users, operators, founders, and professionals who want practical AI workflows without heavy coding."
+    },
+    {
+      "name": "10-Hours LLM Fundamentals",
+      "url": "https://academy.towardsai.net/courses/llm-primer",
+      "when_to_recommend": "Best quick primer for LLM fundamentals before taking a deeper course."
+    },
+    {
+      "name": "Building LLMs for Production",
+      "url": "https://academy.towardsai.net/courses/buildingllmsforproduction",
+      "when_to_recommend": "Best for learners who want production LLM engineering concepts connected to the Towards AI book/resources."
+    },
+    {
+      "name": "Towards AI Mentorship",
+      "url": "https://academy.towardsai.net/bundles/tai-mentorship",
+      "when_to_recommend": "Best when the user asks for mentors, personalized guidance, accountability, project feedback, or career/course direction."
+    }
+  ],
+  "external_resources": [
+    {
+      "name": "What's AI YouTube",
+      "url": "https://www.youtube.com/channel/UCQNjFuhOJM1YqFTPY1Q_kYQ",
+      "when_to_recommend": "Free AI videos/tutorials before buying a course."
+    },
+    {
+      "name": "Towards AI Resource Library",
+      "url": "https://towardsai.net/towards-ai-resource-library",
+      "when_to_recommend": "Free articles, guides, and learning resources."
+    },
+    {
+      "name": "Towards AI book resources",
+      "url": "https://towardsai.net/book",
+      "when_to_recommend": "Book companion resources and production LLM learning path."
+    },
+    {
+      "name": "Book on Amazon",
+      "url": "https://www.amazon.com/s?k=Towards+AI+Building+LLMs+for+Production",
+      "when_to_recommend": "Purchase/search destination for the Towards AI book on Amazon."
+    }
+  ],
+  "b2b": {
+    "urls": [
+      "https://towardsai.net/b2b",
+      "https://towardsai.net/let-us-transform-your-team-into-ai-first-employees-to-stay-ahead-of-competitors"
+    ],
+    "email": "louis@towardsai.net",
+    "instruction": "Ask for company size, team background, use cases, desired training outcome, and timeline. Suggest emailing louis@towardsai.net with details or continuing in chat."
+  }
+}

data/discovered_urls.json

@@ -0,0 +1,48 @@
+{
+  "academy_sitemap_url": "https://academy.towardsai.net/sitemap.xml",
+  "towardsai_page_sitemap_url": "https://towardsai.net/page-sitemap1.xml",
+  "academy_urls": [
+    "https://academy.towardsai.net/",
+    "https://academy.towardsai.net/collections",
+    "https://academy.towardsai.net/collections/products",
+    "https://academy.towardsai.net/collections/developers",
+    "https://academy.towardsai.net/collections/professionals",
+    "https://academy.towardsai.net/courses/beginner-to-advanced-llm-dev",
+    "https://academy.towardsai.net/courses/agent-engineering",
+    "https://academy.towardsai.net/courses/llm-primer",
+    "https://academy.towardsai.net/courses/python-for-genai",
+    "https://academy.towardsai.net/bundles/tai-mentorship",
+    "https://academy.towardsai.net/courses/ai-business-professionals",
+    "https://academy.towardsai.net/products/digital_downloads/agents-cheatsheet",
+    "https://academy.towardsai.net/products/digital_downloads/anti-slop-framework",
+    "https://academy.towardsai.net/bundles/get-it-all",
+    "https://academy.towardsai.net/courses/buildingllmsforproduction",
+    "https://academy.towardsai.net/bundles/10-hour-crash-course-into-llm-developer-expert",
+    "https://academy.towardsai.net/bundles/from-coding-novice-to-advanced-llm-developer",
+    "https://academy.towardsai.net/pages/agent-course-landing-page",
+    "https://academy.towardsai.net/pages/towards-ai-insider",
+    "https://academy.towardsai.net/pages/agent-course-new-page-cro",
+    "https://academy.towardsai.net/pages/webinar",
+    "https://academy.towardsai.net/pages/new-home-page",
+    "https://academy.towardsai.net/pages/landing-page-free-email-course",
+    "https://academy.towardsai.net/pages/contact-us",
+    "https://academy.towardsai.net/pages/about-us",
+    "https://academy.towardsai.net/pages/affiliate",
+    "https://academy.towardsai.net/pages/choose-your-course",
+    "https://academy.towardsai.net/pages/free-resources"
+  ],
+  "selected_towardsai_pages": [
+    "https://towardsai.net/",
+    "https://towardsai.net/towards-ai-resource-library",
+    "https://towardsai.net/book",
+    "https://towardsai.net/community",
+    "https://towardsai.net/b2b",
+    "https://towardsai.net/let-us-transform-your-team-into-ai-first-employees-to-stay-ahead-of-competitors"
+  ],
+  "extra_external_urls": [
+    "https://www.youtube.com/channel/UCQNjFuhOJM1YqFTPY1Q_kYQ",
+    "https://towardsai.net/towards-ai-resource-library",
+    "https://towardsai.net/book",
+    "https://www.amazon.com/s?k=Towards+AI+Building+LLMs+for+Production"
+  ]
+}

pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "tai-helper"
+version = "0.1.0"
+description = "Public Towards AI course-selection helper chatbot"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "fastapi",
+    "google-genai",
+    "opik",
+    "pydantic",
+    "python-dotenv",
+    "requests",
+    "uvicorn",
+]
+
+[build-system]
+requires = ["setuptools>=70", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[dependency-groups]
+dev = [
+    "httpx",
+    "pytest",
+    "ruff",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+markers = [
+    "live: tests that call the deployed Hugging Face Space",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py313"
+
+[tool.setuptools.packages.find]
+include = ["tai_helper*"]

static/widget.js

@@ -0,0 +1,466 @@
+(function () {
+  "use strict";
+
+  var script = document.currentScript;
+  var apiBase = (
+    (script && script.getAttribute("data-api-base")) ||
+    window.TOWARDS_AI_HELPER_API_BASE ||
+    ""
+  ).replace(/\/+$/, "");
+  if (!apiBase && script && script.src) {
+    try {
+      apiBase = new URL(script.src).origin;
+    } catch (_error) {
+      apiBase = "";
+    }
+  }
+  if (!apiBase) return;
+
+  var state = {
+    config: null,
+    visible: false,
+    open: false,
+    streaming: false,
+    threadId: "",
+    messages: [],
+    firstMessageSent: false,
+    visitorId: visitorId(),
+  };
+
+  var root = document.createElement("div");
+  root.id = "towards-ai-helper-widget";
+  var shadow = root.attachShadow({ mode: "open" });
+  document.documentElement.appendChild(root);
+
+  shadow.innerHTML = [
+    "<style>",
+    ":host{all:initial;font-family:Inter,ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;color:#182235}",
+    ".wrap{position:fixed;right:20px;bottom:20px;z-index:2147483000}",
+    ".bubble{height:46px;min-width:146px;border:0;border-radius:999px;background:#182235;color:#fff;box-shadow:0 14px 34px rgba(24,34,53,.28);cursor:pointer;display:flex;align-items:center;justify-content:center;gap:9px;padding:0 16px 0 13px;font:750 14px/1 system-ui;letter-spacing:0}",
+    ".bubble:hover{background:#24324b;transform:translateY(-1px)}",
+    ".bubble-mark{width:24px;height:24px;border-radius:999px;background:#11b7ba;color:#082c33;display:flex;align-items:center;justify-content:center;font:800 15px/1 system-ui}",
+    ".panel{width:min(414px,calc(100vw - 32px));height:min(650px,calc(100vh - 96px));background:#fff;border:1px solid #d7e0ea;border-radius:14px;box-shadow:0 20px 70px rgba(24,34,53,.24);display:flex;flex-direction:column;overflow:hidden}",
+    ".head{min-height:68px;display:flex;align-items:center;justify-content:space-between;gap:10px;padding:0 14px 0 16px;border-bottom:1px solid #e7edf4;background:#fbfcfe}",
+    ".brand{min-width:0;display:flex;align-items:center;gap:10px}",
+    ".brand-mark{width:32px;height:32px;border-radius:8px;background:#182235;color:#fff;display:flex;align-items:center;justify-content:center;font:800 12px/1 system-ui}",
+    ".title{font:750 15px/1.2 system-ui;color:#182235;letter-spacing:0}",
+    ".subtitle{font:600 12px/1.25 system-ui;color:#64748b;max-width:285px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;margin-top:3px}",
+    ".iconbtn{width:34px;height:34px;flex:0 0 auto;border:0;border-radius:9px;background:#eef3f8;color:#475569;cursor:pointer;font:800 20px/1 system-ui}",
+    ".iconbtn:hover{background:#e2eaf3;color:#182235}",
+    ".msgs{flex:1;overflow:auto;padding:16px;background:#fff;display:flex;flex-direction:column;gap:12px}",
+    ".msg{max-width:88%;padding:11px 13px;border-radius:11px;font:400 14px/1.48 system-ui;overflow-wrap:anywhere}",
+    ".user{align-self:flex-end;background:#182235;color:#fff;border-bottom-right-radius:4px}",
+    ".assistant{align-self:flex-start;background:#f3f7fb;color:#182235;border:1px solid #e7edf4;border-bottom-left-radius:4px}",
+    ".assistant.empty{color:#64748b;font-style:italic}",
+    ".meta{align-self:flex-start;color:#64748b;font:600 12px/1.35 system-ui;background:#f8fafc;border:1px solid #edf2f7;border-radius:999px;padding:6px 10px}",
+    ".prompts{display:flex;flex-direction:column;gap:8px;align-self:stretch}",
+    ".prompt{border:1px solid #d7e0ea;border-radius:10px;background:#fff;color:#182235;text-align:left;padding:10px 11px;font:700 13px/1.35 system-ui;cursor:pointer}",
+    ".prompt:hover{border-color:#11a7b0;background:#f2fbfc}",
+    ".prompt:disabled{opacity:.55;cursor:not-allowed}",
+    ".sources{display:flex;flex-wrap:wrap;gap:6px;margin-top:9px}",
+    ".source{font:700 11px/1.2 system-ui;color:#087e8b;background:#e8f8f9;border-radius:999px;padding:5px 8px;text-decoration:none}",
+    ".md{white-space:normal}",
+    ".md p{margin:0 0 10px}",
+    ".md p:last-child{margin-bottom:0}",
+    ".md ol,.md ul{margin:8px 0 10px 20px;padding:0}",
+    ".md li{margin:5px 0;padding-left:2px}",
+    ".md a{color:#087e8b;text-decoration:underline;text-underline-offset:2px;font-weight:650}",
+    ".md code{background:#e8eef5;border:1px solid #d9e3ee;border-radius:5px;padding:1px 4px;font:500 12px/1.4 ui-monospace,SFMono-Regular,Menlo,monospace}",
+    ".md strong{font-weight:760}",
+    ".form{display:flex;gap:9px;padding:12px;border-top:1px solid #e7edf4;background:#fbfcfe}",
+    ".input{flex:1;resize:none;min-height:44px;max-height:116px;border:1px solid #c8d3df;border-radius:11px;padding:11px 12px;font:400 14px/1.35 system-ui;outline:none;background:#fff;color:#182235}",
+    ".input:focus{border-color:#11a7b0;box-shadow:0 0 0 3px rgba(17,167,176,.16)}",
+    ".send{width:46px;flex:0 0 46px;border:0;border-radius:11px;background:#182235;color:#fff;cursor:pointer;display:flex;align-items:center;justify-content:center}",
+    ".send:hover{background:#24324b}",
+    ".send:disabled{opacity:.45;cursor:not-allowed}",
+    ".send svg{width:18px;height:18px;display:block}",
+    ".hidden{display:none!important}",
+    "@media(max-width:520px){.wrap{right:12px;bottom:12px}.panel{width:calc(100vw - 24px);height:calc(100vh - 86px)}.subtitle{max-width:220px}.bubble{min-width:136px}}",
+    "</style>",
+    "<div class='wrap hidden' data-wrap>",
+    "  <button class='bubble' data-bubble aria-label='Ask the helper'><span class='bubble-mark'>?</span><span>Ask the helper</span></button>",
+    "  <section class='panel hidden' data-panel aria-label='Towards AI helper chat'>",
+    "    <header class='head'>",
+    "      <div class='brand'><div class='brand-mark'>TA</div><div><div class='title'>Towards AI Helper</div><div class='subtitle' data-subtitle></div></div></div>",
+    "      <button class='iconbtn' data-close aria-label='Minimize helper' title='Minimize'>&minus;</button>",
+    "    </header>",
+    "    <div class='msgs' data-msgs><div class='meta'>Choose a starter prompt.</div><div class='prompts' data-prompts></div></div>",
+    "    <form class='form hidden' data-form>",
+    "      <textarea class='input' data-input rows='1' placeholder='Ask a follow-up' data-gramm='false' data-gramm_editor='false' data-enable-grammarly='false'></textarea>",
+    "      <button class='send' data-send type='submit' aria-label='Send message'><svg viewBox='0 0 24 24' aria-hidden='true'><path d='M4 12h14M13 6l6 6-6 6' fill='none' stroke='currentColor' stroke-width='2.4' stroke-linecap='round' stroke-linejoin='round'/></svg></button>",
+    "    </form>",
+    "  </section>",
+    "</div>",
+  ].join("");
+
+  var wrap = shadow.querySelector("[data-wrap]");
+  var bubble = shadow.querySelector("[data-bubble]");
+  var panel = shadow.querySelector("[data-panel]");
+  var closeBtn = shadow.querySelector("[data-close]");
+  var form = shadow.querySelector("[data-form]");
+  var input = shadow.querySelector("[data-input]");
+  var sendBtn = shadow.querySelector("[data-send]");
+  var msgs = shadow.querySelector("[data-msgs]");
+  var prompts = shadow.querySelector("[data-prompts]");
+  var subtitle = shadow.querySelector("[data-subtitle]");
+
+  function safeString(value) {
+    if (value === null || value === undefined) return "";
+    return String(value);
+  }
+
+  function escapeHtml(value) {
+    return safeString(value)
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;")
+      .replace(/'/g, "&#39;");
+  }
+
+  function safeHref(value) {
+    try {
+      var candidate = safeString(value).trim();
+      if (/^www\./i.test(candidate)) candidate = "https://" + candidate;
+      var url = new URL(candidate, window.location.href);
+      if (url.protocol === "http:" || url.protocol === "https:") return url.href;
+    } catch (_error) {}
+    return "";
+  }
+
+  function displayUrl(value) {
+    return safeString(value).replace(/^https?:\/\//i, "").replace(/\/$/, "");
+  }
+
+  function splitTrailingUrlPunctuation(value) {
+    var url = safeString(value);
+    var suffix = "";
+    while (/[.,;:!?]$/.test(url)) {
+      suffix = url.slice(-1) + suffix;
+      url = url.slice(0, -1);
+    }
+    while (
+      url.slice(-1) === ")" &&
+      (url.match(/\)/g) || []).length > (url.match(/\(/g) || []).length
+    ) {
+      suffix = ")" + suffix;
+      url = url.slice(0, -1);
+    }
+    return { url: url, suffix: suffix };
+  }
+
+  function renderBasicMarkdown(text) {
+    return escapeHtml(text)
+      .replace(/`([^`]+)`/g, "<code>$1</code>")
+      .replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>");
+  }
+
+  function renderInlineMarkdown(text) {
+    var output = "";
+    var lastIndex = 0;
+    var linkPattern =
+      /\[([^\]]{1,180})\]\(((?:https?:\/\/|www\.)[^)\s]+)\)|\[((?:https?:\/\/|www\.)[^\]\s]+)\]|((?:https?:\/\/|www\.)[^\s<]+)/g;
+    var match;
+    while ((match = linkPattern.exec(text)) !== null) {
+      output += renderBasicMarkdown(text.slice(lastIndex, match.index));
+      var rawUrl = match[2] || match[3] || match[4] || "";
+      var suffix = "";
+      if (!match[2]) {
+        var splitUrl = splitTrailingUrlPunctuation(rawUrl);
+        rawUrl = splitUrl.url;
+        suffix = splitUrl.suffix;
+      }
+      var href = safeHref(rawUrl);
+      if (href) {
+        output +=
+          "<a href='" +
+          escapeHtml(href) +
+          "' target='_blank' rel='noopener noreferrer'>" +
+          (match[1] ? renderBasicMarkdown(match[1]) : escapeHtml(displayUrl(rawUrl))) +
+          "</a>";
+        if (suffix) output += renderBasicMarkdown(suffix);
+      } else {
+        output += renderBasicMarkdown(match[0]);
+      }
+      lastIndex = match.index + match[0].length;
+    }
+    output += renderBasicMarkdown(text.slice(lastIndex));
+    return output;
+  }
+
+  function isListLine(line) {
+    return /^\s*(?:[-*]\s+|\d+\.\s+)/.test(line);
+  }
+
+  function renderMarkdown(markdown) {
+    var lines = safeString(markdown).replace(/\r\n/g, "\n").split("\n");
+    var html = [];
+    var index = 0;
+    while (index < lines.length) {
+      var line = lines[index];
+      var trimmed = line.trim();
+      if (!trimmed) {
+        index += 1;
+        continue;
+      }
+      if (isListLine(line)) {
+        var ordered = /^\s*\d+\.\s+/.test(line);
+        var tag = ordered ? "ol" : "ul";
+        var items = [];
+        while (index < lines.length && isListLine(lines[index])) {
+          items.push(
+            "<li>" +
+              renderInlineMarkdown(lines[index].replace(/^\s*(?:[-*]\s+|\d+\.\s+)/, "")) +
+              "</li>",
+          );
+          index += 1;
+        }
+        html.push("<" + tag + ">" + items.join("") + "</" + tag + ">");
+        continue;
+      }
+      var paragraph = [trimmed];
+      index += 1;
+      while (index < lines.length && lines[index].trim() && !isListLine(lines[index])) {
+        paragraph.push(lines[index].trim());
+        index += 1;
+      }
+      html.push("<p>" + renderInlineMarkdown(paragraph.join(" ")) + "</p>");
+    }
+    return "<div class='md'>" + html.join("") + "</div>";
+  }
+
+  function visitorId() {
+    try {
+      var key = "towards_ai_helper_visitor";
+      var existing = window.localStorage.getItem(key);
+      if (existing) return existing;
+      var id =
+        Date.now().toString(36) + "-" + Math.random().toString(36).slice(2, 12);
+      window.localStorage.setItem(key, id);
+      return id;
+    } catch (_error) {
+      return "";
+    }
+  }
+
+  function normalizePath(pathname) {
+    var path = pathname || "/";
+    path = path.replace(/\/+$/, "");
+    return path || "/";
+  }
+
+  function isSignedIn() {
+    try {
+      if (window.Thinkific && window.Thinkific.current_user) return true;
+      if (document.body && document.body.classList.contains("logged-in")) return true;
+      if (document.getElementById("wpadminbar")) return true;
+      if (/wordpress_logged_in|thinkific_user|signed_in/i.test(document.cookie || "")) {
+        return true;
+      }
+      var signOutLink = document.querySelector(
+        "a[href*='sign_out'],a[href*='logout'],a[href*='/account']",
+      );
+      return Boolean(signOutLink && /sign out|logout|account/i.test(signOutLink.textContent || ""));
+    } catch (_error) {
+      return false;
+    }
+  }
+
+  function isBlockedPath() {
+    var path = normalizePath(window.location.pathname);
+    return /^(courses\/take|enroll|order|checkout|cart|users|account|admin)/.test(
+      path.replace(/^\//, ""),
+    );
+  }
+
+  function pageAllowed(config) {
+    if (!config || isSignedIn() || isBlockedPath()) return false;
+    var host = window.location.hostname.toLowerCase();
+    var path = normalizePath(window.location.pathname);
+    var paths = config.allowedPathsByHost && config.allowedPathsByHost[host];
+    if (!paths && host.indexOf("www.") === 0) {
+      paths = config.allowedPathsByHost && config.allowedPathsByHost[host.slice(4)];
+    }
+    return Array.isArray(paths) && paths.indexOf(path) !== -1;
+  }
+
+  function setVisible(visible) {
+    state.visible = visible;
+    wrap.classList.toggle("hidden", !visible);
+    if (!visible) {
+      state.open = false;
+      panel.classList.add("hidden");
+      bubble.classList.remove("hidden");
+    }
+  }
+
+  function setOpen(open) {
+    state.open = open;
+    panel.classList.toggle("hidden", !open);
+    bubble.classList.toggle("hidden", open);
+    if (open) setTimeout(function () { input.focus(); }, 50);
+  }
+
+  function contextPayload() {
+    return {
+      url: window.location.href.split("#", 1)[0],
+      pageTitle: document.title || "",
+      referrer: document.referrer || "",
+      signedIn: isSignedIn(),
+    };
+  }
+
+  function appendMessage(role, text, sources) {
+    var node = document.createElement("div");
+    node.className = "msg " + (role === "user" ? "user" : "assistant");
+    node.innerHTML = role === "assistant" ? renderMarkdown(text) : escapeHtml(text);
+    if (role === "assistant" && sources && sources.length) {
+      var sourceWrap = document.createElement("div");
+      sourceWrap.className = "sources";
+      sources.slice(0, 3).forEach(function (source) {
+        var a = document.createElement("a");
+        a.className = "source";
+        a.href = source.url;
+        a.target = "_blank";
+        a.rel = "noopener noreferrer";
+        a.textContent = source.title || source.kind || "Source";
+        sourceWrap.appendChild(a);
+      });
+      node.appendChild(sourceWrap);
+    }
+    msgs.appendChild(node);
+    msgs.scrollTop = msgs.scrollHeight;
+    return node;
+  }
+
+  function setBusy(busy) {
+    state.streaming = busy;
+    sendBtn.disabled = busy;
+    input.disabled = busy;
+    Array.prototype.forEach.call(prompts.querySelectorAll("button"), function (button) {
+      button.disabled = busy || state.firstMessageSent;
+    });
+  }
+
+  function showInput() {
+    form.classList.toggle("hidden", !state.firstMessageSent);
+  }
+
+  function send(text, selectedPrompt) {
+    text = safeString(text).trim();
+    if (!text || state.streaming) return;
+    appendMessage("user", text);
+    state.messages.push({ role: "user", content: text });
+    setBusy(true);
+    var loading = appendMessage("assistant", "Thinking...");
+    loading.classList.add("empty");
+
+    fetch(apiBase + "/api/helper/chat", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        query: text,
+        selectedPrompt: selectedPrompt || "",
+        visitorId: state.visitorId,
+        threadId: state.threadId,
+        history: state.messages.slice(0, -1).slice(-8),
+        context: contextPayload(),
+      }),
+    })
+      .then(function (response) {
+        if (!response.ok) {
+          if (response.status === 429) {
+            throw new Error("The helper is rate limited right now. Please try again later.");
+          }
+          throw new Error("The helper is unavailable on this page.");
+        }
+        return response.json();
+      })
+      .then(function (payload) {
+        state.threadId = payload.threadId || state.threadId;
+        loading.classList.remove("empty");
+        loading.innerHTML = renderMarkdown(payload.answer || "I could not answer that.");
+        if (payload.sources && payload.sources.length) {
+          var sourceWrap = document.createElement("div");
+          sourceWrap.className = "sources";
+          payload.sources.slice(0, 3).forEach(function (source) {
+            var a = document.createElement("a");
+            a.className = "source";
+            a.href = source.url;
+            a.target = "_blank";
+            a.rel = "noopener noreferrer";
+            a.textContent = source.title || source.kind || "Source";
+            sourceWrap.appendChild(a);
+          });
+          loading.appendChild(sourceWrap);
+        }
+        state.messages.push({ role: "assistant", content: payload.answer || "" });
+        state.firstMessageSent = true;
+        prompts.classList.add("hidden");
+        showInput();
+      })
+      .catch(function (error) {
+        loading.classList.remove("empty");
+        loading.innerHTML = renderMarkdown(error.message || "Something went wrong.");
+      })
+      .finally(function () {
+        setBusy(false);
+        input.value = "";
+        input.style.height = "auto";
+        msgs.scrollTop = msgs.scrollHeight;
+      });
+  }
+
+  function renderPrompts() {
+    prompts.innerHTML = "";
+    (state.config.forcedPrompts || []).forEach(function (text) {
+      var button = document.createElement("button");
+      button.type = "button";
+      button.className = "prompt";
+      button.textContent = text;
+      button.addEventListener("click", function () {
+        send(text, text);
+      });
+      prompts.appendChild(button);
+    });
+  }
+
+  bubble.addEventListener("click", function () {
+    setOpen(true);
+  });
+  closeBtn.addEventListener("click", function () {
+    setOpen(false);
+  });
+  form.addEventListener("submit", function (event) {
+    event.preventDefault();
+    send(input.value, "");
+  });
+  input.addEventListener("input", function () {
+    input.style.height = "auto";
+    input.style.height = Math.min(input.scrollHeight, 116) + "px";
+  });
+
+  function refreshVisibility() {
+    if (!state.config) return;
+    setVisible(pageAllowed(state.config));
+  }
+
+  function init() {
+    fetch(apiBase + "/api/helper/config")
+      .then(function (response) { return response.json(); })
+      .then(function (config) {
+        state.config = config;
+        subtitle.textContent = document.title || "Course and training guidance";
+        renderPrompts();
+        showInput();
+        refreshVisibility();
+      })
+      .catch(function () {
+        setVisible(false);
+      });
+  }
+
+  window.addEventListener("thnc.current_user-initialized", refreshVisibility);
+  setTimeout(refreshVisibility, 1000);
+  init();
+})();

tai_helper/__init__.py

@@ -0,0 +1 @@
+"""Towards AI public helper chatbot."""

tai_helper/api.py

@@ -0,0 +1,294 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+from urllib.parse import urlparse
+from uuid import uuid4
+
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+
+from . import llm
+from .catalog import (
+    allowed_paths_by_host,
+    coupon_followup,
+    coupon_intent,
+    forced_prompts,
+    in_scope,
+    page_is_allowed,
+    retrieve,
+    sources_from_pages,
+)
+from .monitoring import HelperMonitor
+from .rate_limiter import FixedWindowRateLimiter, RateLimit
+from .schemas import HelperChatRequest, HelperChatResponse, SourceOut
+from .settings import repo_root, settings
+
+logger = logging.getLogger(__name__)
+
+app = FastAPI(title="Towards AI Helper API", version="0.1.0")
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins(),
+    allow_credentials=False,
+    allow_methods=["GET", "POST", "OPTIONS"],
+    allow_headers=["*"],
+)
+
+
+@app.middleware("http")
+async def reject_oversized_bodies(request: Request, call_next):
+    content_length = request.headers.get("content-length")
+    try:
+        too_large = (
+            content_length is not None and int(content_length) > settings.max_body_bytes
+        )
+    except ValueError:
+        too_large = False
+    if too_large:
+        return JSONResponse({"detail": "Request body too large"}, status_code=413)
+    return await call_next(request)
+
+
+STATIC_DIR = repo_root() / "static"
+if STATIC_DIR.is_dir():
+    app.mount("/static", StaticFiles(directory=str(STATIC_DIR)), name="static")
+
+
+visitor_limiter = FixedWindowRateLimiter(
+    (
+        RateLimit("per_minute", settings.rate_limit_per_minute, 60),
+        RateLimit("per_day", settings.rate_limit_per_day, 24 * 60 * 60),
+    )
+)
+ip_limiter = FixedWindowRateLimiter(
+    (
+        RateLimit("ip_per_minute", settings.rate_limit_per_minute, 60),
+        RateLimit("ip_per_day", settings.rate_limit_per_day, 24 * 60 * 60),
+    )
+)
+global_limiter = FixedWindowRateLimiter(
+    (RateLimit("global_per_minute", settings.rate_limit_global_per_minute, 60),)
+)
+
+
+def _client_ip(request: Request) -> str:
+    forwarded_for = request.headers.get("x-forwarded-for", "")
+    if forwarded_for:
+        return forwarded_for.split(",", 1)[0].strip()
+    return request.client.host if request.client else "unknown"
+
+
+def _header_host_allowed(value: str) -> bool:
+    if not value:
+        return False
+    hostname = (urlparse(value).hostname or "").lower()
+    return any(
+        hostname == allowed.lower() or hostname.endswith("." + allowed.lower())
+        for allowed in settings.allowed_hosts
+    )
+
+
+def _require_allowed_browser_origin(request: Request) -> None:
+    origin = request.headers.get("origin", "")
+    referer = request.headers.get("referer", "")
+    if _header_host_allowed(origin) or _header_host_allowed(referer):
+        return
+    raise HTTPException(
+        status_code=403,
+        detail="Requests must come from a configured Towards AI public site.",
+    )
+
+
+def _rate_key(request: Request, payload: HelperChatRequest) -> str:
+    visitor_id = payload.visitorId.strip()[:80]
+    if visitor_id:
+        return f"visitor:{visitor_id}"
+    return f"ip:{_client_ip(request)}"
+
+
+def _check_rate_limits(request: Request, payload: HelperChatRequest) -> None:
+    global_result = global_limiter.check("global")
+    if not global_result.allowed:
+        raise HTTPException(
+            status_code=429,
+            detail=f"Global rate limit exceeded: {global_result.limit_name}",
+            headers={"Retry-After": str(global_result.retry_after_seconds)},
+        )
+
+    ip_result = ip_limiter.check(_client_ip(request))
+    if not ip_result.allowed:
+        raise HTTPException(
+            status_code=429,
+            detail=f"Rate limit exceeded: {ip_result.limit_name}",
+            headers={"Retry-After": str(ip_result.retry_after_seconds)},
+        )
+
+    visitor_result = visitor_limiter.check(_rate_key(request, payload))
+    if not visitor_result.allowed:
+        raise HTTPException(
+            status_code=429,
+            detail=f"Rate limit exceeded: {visitor_result.limit_name}",
+            headers={"Retry-After": str(visitor_result.retry_after_seconds)},
+        )
+
+
+def _history_text(payload: HelperChatRequest) -> list[str]:
+    return [turn.content for turn in payload.history[-settings.max_history_turns :]]
+
+
+def _validate_payload(payload: HelperChatRequest) -> None:
+    if payload.context.signedIn:
+        raise HTTPException(status_code=403, detail="Helper is only for signed-out visitors.")
+    if not page_is_allowed(payload.context.url):
+        raise HTTPException(status_code=403, detail="Helper is only available on public pages.")
+    if len(payload.query.strip()) > settings.max_query_chars:
+        raise HTTPException(status_code=400, detail="Question is too long.")
+    if not payload.history and payload.query.strip() not in forced_prompts():
+        raise HTTPException(
+            status_code=400,
+            detail="Please choose one of the starter prompts first.",
+        )
+
+
+def _fixed_coupon_answer(payload: HelperChatRequest) -> str:
+    history = _history_text(payload)
+    if coupon_followup(payload.query, history):
+        return (
+            "I can't provide a coupon code here. If you have specific context, "
+            "email louis@towardsai.net with what you need and we will do the best possible."
+        )
+    return (
+        "I can't provide a coupon code here. The best value option is usually the "
+        "Get it all bundle: https://academy.towardsai.net/bundles/get-it-all"
+    )
+
+
+def _out_of_scope_answer() -> str:
+    return (
+        "I can only help with choosing Towards AI courses, bundles, mentorship, "
+        "free resources, the book, or B2B training. Tell me your background and goal, "
+        "and I can point you to the right option."
+    )
+
+
+def _fallback_answer() -> str:
+    return (
+        "I can help, but I need one detail: are you learning for your own career, "
+        "building AI products, or looking for company training?"
+    )
+
+
+async def _flush_monitor(monitor: HelperMonitor) -> None:
+    await asyncio.to_thread(monitor.flush)
+
+
+def _schedule_monitor(monitor: HelperMonitor) -> None:
+    if not monitor.enabled:
+        return
+    task = asyncio.create_task(_flush_monitor(monitor))
+
+    def log_failure(done: asyncio.Task) -> None:
+        try:
+            done.result()
+        except Exception:
+            logger.warning("Background Opik monitor flush failed.", exc_info=True)
+
+    task.add_done_callback(log_failure)
+
+
+@app.get("/healthz")
+def healthcheck() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+@app.get("/widget.js")
+def widget() -> FileResponse:
+    path = STATIC_DIR / "widget.js"
+    if not path.is_file():
+        raise HTTPException(status_code=404, detail="Widget not found")
+    return FileResponse(path, media_type="application/javascript")
+
+
+@app.get("/api/helper/config")
+def public_config() -> dict[str, Any]:
+    opik_ready = bool(settings.opik_enabled and settings.opik_api_key)
+    return {
+        "name": "Towards AI Helper",
+        "allowedHosts": list(settings.allowed_hosts),
+        "allowedPathsByHost": allowed_paths_by_host(),
+        "forcedPrompts": forced_prompts(),
+        "rateLimits": {
+            "perMinute": settings.rate_limit_per_minute,
+            "perDay": settings.rate_limit_per_day,
+        },
+        "monitoring": {
+            "opikEnabled": opik_ready,
+            "opikProject": settings.opik_project_name if opik_ready else "",
+        },
+    }
+
+
+@app.post("/api/helper/chat")
+async def chat(request: Request, payload: HelperChatRequest) -> HelperChatResponse:
+    _require_allowed_browser_origin(request)
+    _validate_payload(payload)
+    _check_rate_limits(request, payload)
+
+    query = payload.query.strip()
+    thread_id = payload.threadId.strip() or uuid4().hex
+    selected_pages = retrieve(query, current_url=payload.context.url)
+    sources = sources_from_pages(selected_pages)
+    usage: dict[str, Any] = {}
+    latency_ms = 0
+    error_message = ""
+
+    try:
+        if coupon_intent(query):
+            answer = _fixed_coupon_answer(payload)
+        elif not in_scope(query, _history_text(payload)):
+            answer = _out_of_scope_answer()
+        else:
+            prompt = llm.build_prompt(
+                query=query,
+                selected_prompt=payload.selectedPrompt or query,
+                current_url=payload.context.url,
+                page_title=payload.context.pageTitle,
+                history=[
+                    (turn.role, turn.content)
+                    for turn in payload.history[-settings.max_history_turns :]
+                ],
+                selected_pages=selected_pages,
+            )
+            result = await asyncio.to_thread(llm.generate_answer, prompt)
+            answer = result.answer or _fallback_answer()
+            usage = result.usage
+            latency_ms = result.latency_ms
+    except Exception:
+        error_message = "helper generation failed"
+        logger.exception("helper generation failed")
+        answer = _fallback_answer()
+
+    monitor = HelperMonitor(
+        query=query,
+        answer=answer,
+        current_url=payload.context.url,
+        selected_prompt=payload.selectedPrompt or query,
+        visitor_key=_rate_key(request, payload),
+        thread_id=thread_id,
+        sources=sources,
+        usage=usage,
+        latency_ms=latency_ms,
+        error_message=error_message,
+    )
+    _schedule_monitor(monitor)
+
+    return HelperChatResponse(
+        answer=answer,
+        threadId=thread_id,
+        sources=[SourceOut(**source) for source in sources],
+        usage=usage,
+    )

tai_helper/catalog.py

@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+import json
+import re
+from functools import lru_cache
+from typing import Any
+from urllib.parse import urlparse
+
+from .settings import repo_root
+
+WORD_RE = re.compile(r"[a-z0-9][a-z0-9+#.-]*")
+
+
+@lru_cache(maxsize=1)
+def pages_payload() -> dict[str, Any]:
+    return json.loads((repo_root() / "data" / "pages.json").read_text())
+
+
+@lru_cache(maxsize=1)
+def assistant_notes() -> dict[str, Any]:
+    return json.loads((repo_root() / "data" / "assistant_notes.json").read_text())
+
+
+def forced_prompts() -> list[str]:
+    return list(assistant_notes()["forced_prompts"])
+
+
+def pages() -> list[dict[str, Any]]:
+    return list(pages_payload()["pages"])
+
+
+def tokenize(text: str) -> set[str]:
+    return {token.lower() for token in WORD_RE.findall(text.lower()) if len(token) > 2}
+
+
+def normalized_path(url: str) -> tuple[str, str]:
+    parsed = urlparse(url)
+    host = (parsed.hostname or "").lower()
+    path = parsed.path.rstrip("/") or "/"
+    return host, path
+
+
+def allowed_paths_by_host() -> dict[str, list[str]]:
+    result: dict[str, set[str]] = {}
+    for page in pages():
+        host = str(page.get("host", "")).lower()
+        path = str(page.get("path", "/")).rstrip("/") or "/"
+        if host:
+            result.setdefault(host, set()).add(path)
+            if host == "towardsai.net":
+                result.setdefault("www.towardsai.net", set()).add(path)
+    return {host: sorted(paths) for host, paths in result.items()}
+
+
+def page_is_allowed(url: str) -> bool:
+    host, path = normalized_path(url)
+    if not host:
+        return False
+    if path.startswith(("/courses/take", "/enroll", "/order", "/checkout", "/cart")):
+        return False
+    if path.startswith(("/users", "/account", "/admin")):
+        return False
+    allowed = allowed_paths_by_host()
+    return path in allowed.get(host, [])
+
+
+def source_for_url(url: str) -> dict[str, Any] | None:
+    host, path = normalized_path(url)
+    for page in pages():
+        if str(page.get("host", "")).lower() == host and (
+            str(page.get("path", "/")).rstrip("/") or "/"
+        ) == path:
+            return page
+    return None
+
+
+def retrieve(query: str, *, current_url: str = "", limit: int = 7) -> list[dict[str, Any]]:
+    query_tokens = tokenize(query)
+    scored: list[tuple[float, dict[str, Any]]] = []
+    current = source_for_url(current_url)
+    notes_text = json.dumps(assistant_notes(), ensure_ascii=False)
+
+    synthetic_notes = {
+        "title": "Towards AI Helper Routing Notes",
+        "url": "internal://assistant-notes",
+        "kind": "routing_notes",
+        "text": notes_text,
+        "headings": [],
+        "links": [],
+    }
+    all_pages = [synthetic_notes, *pages()]
+
+    for page in all_pages:
+        text = " ".join(
+            [
+                str(page.get("title", "")),
+                str(page.get("kind", "")),
+                " ".join(str(item) for item in page.get("headings", [])[:30]),
+                str(page.get("meta_description", "")),
+                str(page.get("text", ""))[:8000],
+            ]
+        )
+        tokens = tokenize(text)
+        overlap = len(query_tokens & tokens)
+        score = float(overlap)
+        kind = page.get("kind", "")
+        lowered = query.lower()
+        if page is current:
+            score += 7.0
+        if kind == "routing_notes":
+            score += 5.0
+        if "company" in lowered or "b2b" in lowered or "training" in lowered:
+            if kind == "b2b":
+                score += 8.0
+        if "mentor" in lowered or "mentorship" in lowered:
+            if "mentorship" in str(page.get("url", "")).lower():
+                score += 10.0
+        if "free" in lowered or "youtube" in lowered or "resource" in lowered:
+            if kind in {"free_resource", "free_content_external", "community"}:
+                score += 7.0
+        if "book" in lowered or "amazon" in lowered:
+            if kind in {"book", "book_external"}:
+                score += 8.0
+        if "bundle" in lowered or "all" in lowered or "value" in lowered:
+            if "get-it-all" in str(page.get("url", "")):
+                score += 8.0
+        if score > 0:
+            scored.append((score, page))
+
+    scored.sort(key=lambda item: item[0], reverse=True)
+    return [page for _score, page in scored[:limit]]
+
+
+def sources_from_pages(selected: list[dict[str, Any]], limit: int = 4) -> list[dict[str, str]]:
+    result = []
+    for page in selected:
+        url = str(page.get("url", ""))
+        if url.startswith("internal://"):
+            continue
+        result.append(
+            {
+                "title": str(page.get("title", "")) or url,
+                "url": url,
+                "kind": str(page.get("kind", "page")),
+            }
+        )
+    seen = set()
+    unique = []
+    for source in result:
+        if source["url"] not in seen:
+            seen.add(source["url"])
+            unique.append(source)
+    return unique[:limit]
+
+
+def in_scope(text: str, history: list[str] | None = None) -> bool:
+    haystack = " ".join([text, *(history or [])]).lower()
+    allowed_terms = {
+        "course",
+        "courses",
+        "bundle",
+        "academy",
+        "towards ai",
+        "mentor",
+        "mentorship",
+        "training",
+        "company",
+        "business",
+        "team",
+        "consulting",
+        "resource",
+        "resources",
+        "youtube",
+        "book",
+        "amazon",
+        "learn",
+        "learning",
+        "python",
+        "llm",
+        "agent",
+        "agents",
+        "genai",
+        "certificate",
+        "refund",
+        "price",
+        "coupon",
+        "discount",
+        "promo",
+        "career",
+    }
+    return any(term in haystack for term in allowed_terms)
+
+
+def coupon_intent(text: str) -> bool:
+    lowered = text.lower()
+    return any(term in lowered for term in ("coupon", "promo code", "discount code"))
+
+
+def coupon_followup(text: str, history: list[str]) -> bool:
+    lowered = " ".join([*history, text]).lower()
+    prior_coupon_mentions = sum(
+        lowered.count(term) for term in ("coupon", "promo code", "discount code")
+    )
+    return prior_coupon_mentions >= 2 or any(
+        term in text.lower() for term in ("please", "really", "need", "student", "can't")
+    )

tai_helper/llm.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from google import genai
+
+from .catalog import assistant_notes
+from .settings import settings
+
+
+SYSTEM_INSTRUCTION = """You are Towards AI Helper, a concise public assistant for anonymous prospective students.
+
+Your only job is to help users choose Towards AI courses, bundles, mentorship,
+free resources, the book, community, or B2B training/consulting.
+
+Rules:
+- Stay on this scope. If asked general AI, coding, homework, news, or unrelated questions, briefly say you can only help with choosing Towards AI learning/training options.
+- Do not teach course lesson content, reveal course material, or provide detailed technical lessons. Give high-level fit guidance and link to relevant public pages.
+- Keep answers short: usually 2-5 sentences plus links when useful.
+- For course-choice prompts, ask one practical follow-up if you need background, coding level, goals, or company context.
+- For B2B/company training/consulting, ask for use case, team background, timeline, and suggest emailing louis@towardsai.net.
+- For mentors, recommend the mentorship program and ask what kind of guidance they need.
+- For eager learners wanting the best value, recommend the Get it all bundle.
+- For coupon code requests, do not provide a code.
+"""
+
+
+@dataclass(frozen=True)
+class LLMResult:
+    answer: str
+    usage: dict[str, Any] = field(default_factory=dict)
+    latency_ms: int = 0
+
+
+def _context_block(selected_pages: list[dict[str, Any]], max_chars: int = 18000) -> str:
+    chunks = []
+    notes = assistant_notes()
+    chunks.append("ROUTING NOTES:\n" + str(notes))
+    for index, page in enumerate(selected_pages, start=1):
+        if str(page.get("url", "")).startswith("internal://"):
+            continue
+        text = str(page.get("text", ""))
+        chunks.append(
+            "\n".join(
+                [
+                    f"SOURCE {index}",
+                    f"Title: {page.get('title', '')}",
+                    f"Kind: {page.get('kind', '')}",
+                    f"URL: {page.get('url', '')}",
+                    f"Headings: {', '.join(str(h) for h in page.get('headings', [])[:12])}",
+                    f"Text: {text[:4500]}",
+                ]
+            )
+        )
+    block = "\n\n".join(chunks)
+    return block[:max_chars]
+
+
+def build_prompt(
+    *,
+    query: str,
+    selected_prompt: str,
+    current_url: str,
+    page_title: str,
+    history: list[tuple[str, str]],
+    selected_pages: list[dict[str, Any]],
+) -> str:
+    turns = "\n".join(
+        f"{role}: {content[:800]}" for role, content in history[-8:] if content.strip()
+    )
+    return f"""The visitor is on a public Towards AI page.
+
+Current URL: {current_url or "unknown"}
+Current page title: {page_title or "unknown"}
+Initial forced prompt: {selected_prompt or "unknown"}
+
+Conversation so far:
+{turns or "(none)"}
+
+Visitor message:
+{query}
+
+Use only these public sales/resource sources and the routing notes:
+{_context_block(selected_pages)}
+
+Answer now. Include links only when directly useful. Do not mention internal routing notes.
+"""
+
+
+def generate_answer(prompt: str) -> LLMResult:
+    if not settings.gemini_api_key:
+        raise RuntimeError("GEMINI_API_KEY is not configured")
+
+    started = time.monotonic()
+    client = genai.Client(api_key=settings.gemini_api_key)
+    response = client.models.generate_content(
+        model=settings.model_name,
+        contents=prompt,
+        config={
+            "system_instruction": SYSTEM_INSTRUCTION,
+            "temperature": 0.2,
+            "max_output_tokens": settings.max_output_tokens,
+        },
+    )
+    usage_metadata = getattr(response, "usage_metadata", None)
+    usage = {}
+    if usage_metadata is not None:
+        usage = {
+            "input_tokens": getattr(usage_metadata, "prompt_token_count", None),
+            "output_tokens": getattr(usage_metadata, "candidates_token_count", None),
+            "total_tokens": getattr(usage_metadata, "total_token_count", None),
+        }
+    return LLMResult(
+        answer=(getattr(response, "text", "") or "").strip(),
+        usage={key: value for key, value in usage.items() if value is not None},
+        latency_ms=int((time.monotonic() - started) * 1000),
+    )

tai_helper/monitoring.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import logging
+import os
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from .settings import Settings, settings
+
+logger = logging.getLogger(__name__)
+
+_OPIK_CONFIGURED_FOR: tuple[str, str, str] | None = None
+_OPIK_IMPORT_WARNING_EMITTED = False
+
+
+def _truncate(value: str, limit: int) -> str:
+    value = value.strip()
+    if limit <= 0 or len(value) <= limit:
+        return value
+    return value[: limit - 1].rstrip() + "..."
+
+
+def _import_opik() -> Any | None:
+    global _OPIK_IMPORT_WARNING_EMITTED
+    try:
+        import opik  # type: ignore[import-not-found]
+    except Exception:
+        if not _OPIK_IMPORT_WARNING_EMITTED:
+            logger.warning("Opik monitoring is enabled but the opik package is unavailable.")
+            _OPIK_IMPORT_WARNING_EMITTED = True
+        return None
+    return opik
+
+
+def _configure_opik(opik: Any, configured: Settings) -> None:
+    global _OPIK_CONFIGURED_FOR
+    signature = (
+        configured.opik_api_key,
+        configured.opik_workspace,
+        configured.opik_project_name,
+    )
+    if _OPIK_CONFIGURED_FOR == signature:
+        return
+
+    os.environ["OPIK_API_KEY"] = configured.opik_api_key
+    os.environ["OPIK_PROJECT_NAME"] = configured.opik_project_name
+    if configured.opik_workspace:
+        os.environ["OPIK_WORKSPACE"] = configured.opik_workspace
+
+    configure = getattr(opik, "configure", None)
+    if callable(configure):
+        kwargs = {
+            "api_key": configured.opik_api_key,
+            "use_local": False,
+            "force": True,
+            "automatic_approvals": True,
+        }
+        if configured.opik_workspace:
+            kwargs["workspace"] = configured.opik_workspace
+        configure(**kwargs)
+
+    _OPIK_CONFIGURED_FOR = signature
+
+
+@dataclass(slots=True)
+class HelperMonitor:
+    query: str
+    answer: str
+    current_url: str
+    selected_prompt: str
+    visitor_key: str
+    thread_id: str
+    sources: list[dict[str, str]]
+    usage: dict[str, Any]
+    latency_ms: int
+    error_message: str = ""
+    configured: Settings = settings
+    opik_module: Any | None = None
+    started_at: float = field(default_factory=time.monotonic)
+
+    @property
+    def enabled(self) -> bool:
+        return bool(self.configured.opik_enabled and self.configured.opik_api_key)
+
+    def flush(self) -> None:
+        if not self.enabled:
+            return
+        opik = self.opik_module or _import_opik()
+        if opik is None:
+            return
+        try:
+            _configure_opik(opik, self.configured)
+            self._write_span(opik)
+        except Exception:
+            logger.warning("Failed to write Opik helper trace.", exc_info=True)
+
+    def _write_span(self, opik: Any) -> None:
+        tags = ["towards-ai-helper", "public-sales-helper"]
+        if self.selected_prompt:
+            tags.append("forced-prompt")
+        span_kwargs = {
+            "name": "towards_ai_helper_chat",
+            "type": "llm",
+            "input": {
+                "query": _truncate(self.query, self.configured.opik_max_text_chars),
+                "selected_prompt": self.selected_prompt,
+                "current_url": self.current_url,
+            },
+            "output": {
+                "answer": _truncate(self.answer, self.configured.opik_max_text_chars)
+            },
+            "metadata": {
+                "thread_id": self.thread_id,
+                "visitor_key": self.visitor_key,
+                "current_url": self.current_url,
+                "sources": self.sources,
+                "latency_ms": self.latency_ms,
+                "status": "error" if self.error_message else "completed",
+            },
+            "tags": tags,
+            "project_name": self.configured.opik_project_name,
+            "model": self.configured.model_name,
+            "provider": "google_genai",
+            "flush": True,
+        }
+        with opik.start_as_current_span(**span_kwargs) as span:
+            if self.usage:
+                span.usage = {
+                    "prompt_tokens": self.usage.get("input_tokens"),
+                    "completion_tokens": self.usage.get("output_tokens"),
+                    "total_tokens": self.usage.get("total_tokens"),
+                }
+            if self.error_message:
+                span.error_info = {
+                    "type": "RuntimeError",
+                    "message": _truncate(self.error_message, 1000),
+                }

tai_helper/rate_limiter.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import time
+from collections import defaultdict, deque
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class RateLimit:
+    name: str
+    max_requests: int
+    window_seconds: int
+
+
+@dataclass(frozen=True)
+class RateLimitResult:
+    allowed: bool
+    limit_name: str = ""
+    retry_after_seconds: int = 0
+
+
+class FixedWindowRateLimiter:
+    def __init__(self, limits: tuple[RateLimit, ...]) -> None:
+        self.limits = limits
+        self._events: dict[tuple[str, str], deque[float]] = defaultdict(deque)
+
+    def check(self, key: str) -> RateLimitResult:
+        now = time.time()
+        for limit in self.limits:
+            events = self._events[(limit.name, key)]
+            while events and now - events[0] >= limit.window_seconds:
+                events.popleft()
+            if len(events) >= limit.max_requests:
+                retry_after = max(1, int(limit.window_seconds - (now - events[0])) + 1)
+                return RateLimitResult(False, limit.name, retry_after)
+
+        for limit in self.limits:
+            self._events[(limit.name, key)].append(now)
+        return RateLimitResult(True)
+
+    def clear(self) -> None:
+        self._events.clear()

tai_helper/schemas.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class HelperContext(BaseModel):
+    url: str = ""
+    pageTitle: str = ""
+    referrer: str = ""
+    signedIn: bool = False
+
+
+class ChatTurn(BaseModel):
+    role: Literal["user", "assistant"]
+    content: str = Field(default="", max_length=2000)
+
+
+class HelperChatRequest(BaseModel):
+    query: str = Field(min_length=1, max_length=1000)
+    selectedPrompt: str = ""
+    visitorId: str = ""
+    threadId: str = ""
+    history: list[ChatTurn] = Field(default_factory=list)
+    context: HelperContext = Field(default_factory=HelperContext)
+
+
+class SourceOut(BaseModel):
+    title: str
+    url: str
+    kind: str
+
+
+class HelperChatResponse(BaseModel):
+    answer: str
+    threadId: str
+    sources: list[SourceOut]
+    usage: dict[str, Any] = Field(default_factory=dict)

tai_helper/settings.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+def repo_root() -> Path:
+    return Path(__file__).resolve().parents[1]
+
+
+def _csv_env(name: str, default: str = "") -> tuple[str, ...]:
+    raw = os.getenv(name, default)
+    return tuple(item.strip() for item in raw.split(",") if item.strip())
+
+
+def _int_env(name: str, default: int) -> int:
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    try:
+        return int(raw)
+    except ValueError:
+        return default
+
+
+def _bool_env(name: str, default: bool = False) -> bool:
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() in {"1", "true", "yes", "on"}
+
+
+@dataclass(frozen=True)
+class Settings:
+    allowed_origins: tuple[str, ...] = field(
+        default_factory=lambda: _csv_env(
+            "HELPER_ALLOWED_ORIGINS",
+            "https://academy.towardsai.net,https://towardsai.net,https://www.towardsai.net",
+        )
+    )
+    allowed_hosts: tuple[str, ...] = field(
+        default_factory=lambda: _csv_env(
+            "HELPER_ALLOWED_HOSTS",
+            "academy.towardsai.net,towardsai.net,www.towardsai.net",
+        )
+    )
+    model_name: str = field(
+        default_factory=lambda: os.getenv("HELPER_MODEL", "gemini-2.5-flash").strip()
+        or "gemini-2.5-flash"
+    )
+    gemini_api_key: str = field(
+        default_factory=lambda: os.getenv("GEMINI_API_KEY", "").strip()
+    )
+    max_output_tokens: int = field(
+        default_factory=lambda: _int_env("HELPER_MAX_OUTPUT_TOKENS", 420)
+    )
+    max_body_bytes: int = field(
+        default_factory=lambda: _int_env("HELPER_MAX_BODY_BYTES", 64 * 1024)
+    )
+    max_query_chars: int = field(
+        default_factory=lambda: _int_env("HELPER_MAX_QUERY_CHARS", 600)
+    )
+    max_history_turns: int = field(
+        default_factory=lambda: _int_env("HELPER_MAX_HISTORY_TURNS", 8)
+    )
+    rate_limit_per_minute: int = field(
+        default_factory=lambda: _int_env("HELPER_RATE_LIMIT_PER_MINUTE", 3)
+    )
+    rate_limit_per_day: int = field(
+        default_factory=lambda: _int_env("HELPER_RATE_LIMIT_PER_DAY", 20)
+    )
+    rate_limit_global_per_minute: int = field(
+        default_factory=lambda: _int_env("HELPER_GLOBAL_RATE_LIMIT_PER_MINUTE", 120)
+    )
+    opik_enabled: bool = field(default_factory=lambda: _bool_env("OPIK_ENABLED", False))
+    opik_api_key: str = field(
+        default_factory=lambda: os.getenv("OPIK_API_KEY", "").strip()
+    )
+    opik_workspace: str = field(
+        default_factory=lambda: os.getenv("OPIK_WORKSPACE", "").strip()
+    )
+    opik_project_name: str = field(
+        default_factory=lambda: os.getenv(
+            "OPIK_PROJECT_NAME",
+            "towards-ai-helper",
+        ).strip()
+        or "towards-ai-helper"
+    )
+    opik_max_text_chars: int = field(
+        default_factory=lambda: _int_env("OPIK_MAX_TEXT_CHARS", 4000)
+    )
+
+    def cors_origins(self) -> list[str]:
+        return list(self.allowed_origins)
+
+
+settings = Settings()

tests/test_api.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+from fastapi.testclient import TestClient
+
+from tai_helper import api
+from tai_helper.llm import LLMResult
+from tai_helper.rate_limiter import FixedWindowRateLimiter, RateLimit
+
+client = TestClient(api.app)
+HEADERS = {"Origin": "https://academy.towardsai.net"}
+PUBLIC_URL = "https://academy.towardsai.net/courses/agent-engineering"
+FIRST_PROMPT = "I want help deciding which course to take."
+
+
+def reset_limiters() -> None:
+    api.visitor_limiter = FixedWindowRateLimiter(
+        (
+            RateLimit("per_minute", 100, 60),
+            RateLimit("per_day", 1000, 24 * 60 * 60),
+        )
+    )
+    api.ip_limiter = FixedWindowRateLimiter(
+        (
+            RateLimit("ip_per_minute", 100, 60),
+            RateLimit("ip_per_day", 1000, 24 * 60 * 60),
+        )
+    )
+    api.global_limiter = FixedWindowRateLimiter(
+        (RateLimit("global_per_minute", 1000, 60),)
+    )
+
+
+def payload(query: str = FIRST_PROMPT, *, url: str = PUBLIC_URL, signed_in: bool = False):
+    return {
+        "query": query,
+        "selectedPrompt": query if query == FIRST_PROMPT else FIRST_PROMPT,
+        "visitorId": "test-visitor",
+        "threadId": "",
+        "history": [],
+        "context": {
+            "url": url,
+            "pageTitle": "Agent course",
+            "signedIn": signed_in,
+        },
+    }
+
+
+def test_config_exposes_public_widget_contract() -> None:
+    response = client.get("/api/helper/config")
+
+    assert response.status_code == 200
+    data = response.json()
+    assert data["name"] == "Towards AI Helper"
+    assert FIRST_PROMPT in data["forcedPrompts"]
+    assert "/courses/agent-engineering" in data["allowedPathsByHost"]["academy.towardsai.net"]
+
+
+def test_chat_requires_allowed_origin_public_page_signed_out_and_first_prompt() -> None:
+    reset_limiters()
+
+    assert client.post("/api/helper/chat", json=payload()).status_code == 403
+    assert (
+        client.post(
+            "/api/helper/chat",
+            json=payload(url="https://academy.towardsai.net/courses/take/x"),
+            headers=HEADERS,
+        ).status_code
+        == 403
+    )
+    assert (
+        client.post(
+            "/api/helper/chat",
+            json=payload(signed_in=True),
+            headers=HEADERS,
+        ).status_code
+        == 403
+    )
+    assert (
+        client.post(
+            "/api/helper/chat",
+            json=payload(query="Can I type first?"),
+            headers=HEADERS,
+        ).status_code
+        == 400
+    )
+
+
+def test_chat_calls_gemini_with_retrieved_sources(monkeypatch) -> None:
+    reset_limiters()
+    prompts = []
+
+    def fake_generate_answer(prompt: str) -> LLMResult:
+        prompts.append(prompt)
+        return LLMResult(
+            answer="Tell me your coding background and goal.",
+            usage={"input_tokens": 10, "output_tokens": 8, "total_tokens": 18},
+            latency_ms=123,
+        )
+
+    monkeypatch.setattr(api.llm, "generate_answer", fake_generate_answer)
+
+    response = client.post("/api/helper/chat", json=payload(), headers=HEADERS)
+
+    assert response.status_code == 200
+    data = response.json()
+    assert data["answer"] == "Tell me your coding background and goal."
+    assert data["threadId"]
+    assert data["sources"]
+    assert data["usage"]["total_tokens"] == 18
+    assert "Agent Engineering" in prompts[0]
+
+
+def test_coupon_answer_is_deterministic_and_does_not_call_model(monkeypatch) -> None:
+    reset_limiters()
+
+    def unexpected_generate_answer(_prompt: str) -> LLMResult:
+        raise AssertionError("model should not be called for coupon intent")
+
+    monkeypatch.setattr(api.llm, "generate_answer", unexpected_generate_answer)
+    first = payload(query="Do you have a coupon code?")
+    first["selectedPrompt"] = FIRST_PROMPT
+    first["history"] = [{"role": "user", "content": FIRST_PROMPT}]
+    second = payload(query="Please I really need a coupon code")
+    second["selectedPrompt"] = FIRST_PROMPT
+    second["history"] = [
+        {"role": "user", "content": FIRST_PROMPT},
+        {"role": "assistant", "content": "I can't provide a coupon code here."},
+    ]
+
+    first_response = client.post("/api/helper/chat", json=first, headers=HEADERS)
+    second_response = client.post("/api/helper/chat", json=second, headers=HEADERS)
+
+    assert first_response.status_code == 200
+    assert "Get it all bundle" in first_response.json()["answer"]
+    assert second_response.status_code == 200
+    assert "louis@towardsai.net" in second_response.json()["answer"]
+
+
+def test_rate_limit_is_hard(monkeypatch) -> None:
+    api.visitor_limiter = FixedWindowRateLimiter((RateLimit("per_minute", 1, 60),))
+    api.ip_limiter = FixedWindowRateLimiter((RateLimit("ip_per_minute", 100, 60),))
+    api.global_limiter = FixedWindowRateLimiter(
+        (RateLimit("global_per_minute", 100, 60),)
+    )
+
+    monkeypatch.setattr(
+        api.llm,
+        "generate_answer",
+        lambda _prompt: LLMResult(answer="ok"),
+    )
+
+    first = client.post("/api/helper/chat", json=payload(), headers=HEADERS)
+    second = client.post("/api/helper/chat", json=payload(), headers=HEADERS)
+
+    assert first.status_code == 200
+    assert second.status_code == 429
+    assert int(second.headers["retry-after"]) > 0

tests/test_catalog.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from tai_helper.catalog import (
+    allowed_paths_by_host,
+    coupon_followup,
+    coupon_intent,
+    forced_prompts,
+    in_scope,
+    page_is_allowed,
+    retrieve,
+    sources_from_pages,
+)
+
+
+def test_forced_prompts_match_expected_options() -> None:
+    assert forced_prompts() == [
+        "I want help deciding which course to take.",
+        "I want help to integrate AI into my company",
+        "I want a training inside my company",
+        "I'm looking for more free resources to learn before committing to buying a course",
+        "I want to find mentors",
+    ]
+
+
+def test_allowed_public_pages_include_sitemap_urls_and_exclude_private_paths() -> None:
+    assert page_is_allowed("https://academy.towardsai.net/courses/agent-engineering")
+    assert page_is_allowed("https://towardsai.net/b2b")
+    assert page_is_allowed("https://www.towardsai.net/b2b")
+    assert not page_is_allowed(
+        "https://academy.towardsai.net/courses/take/agent-engineering/lessons/x"
+    )
+    assert not page_is_allowed("https://academy.towardsai.net/enroll/123")
+    assert "/b2b" in allowed_paths_by_host()["www.towardsai.net"]
+
+
+def test_retrieval_routes_mentorship_b2b_and_bundle_queries() -> None:
+    mentorship = sources_from_pages(retrieve("I want to find mentors"))
+    b2b = sources_from_pages(retrieve("I want training inside my company"))
+    bundle = sources_from_pages(retrieve("What is the best value bundle?"))
+
+    assert any("tai-mentorship" in source["url"] for source in mentorship)
+    assert any("towardsai.net/b2b" in source["url"] for source in b2b)
+    assert any("get-it-all" in source["url"] for source in bundle)
+
+
+def test_scope_and_coupon_detection() -> None:
+    assert in_scope("Which course is best for learning agents?")
+    assert not in_scope("Who won the world cup?")
+    assert coupon_intent("Do you have a coupon code?")
+    assert coupon_followup("Please I really need a discount code", ["coupon?"])

tests/test_live_smoke.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import os
+import time
+
+import pytest
+import requests
+
+LIVE_BASE_URL = os.getenv("LIVE_SPACE_BASE_URL", "").rstrip("/")
+RUN_LIVE_CHAT = os.getenv("RUN_LIVE_CHAT_SMOKE", "").lower() in {
+    "1",
+    "true",
+    "yes",
+    "on",
+}
+HEADERS = {"Origin": "https://academy.towardsai.net"}
+FIRST_PROMPT = "I want help deciding which course to take."
+
+
+def require_live_base_url() -> str:
+    if not LIVE_BASE_URL:
+        pytest.skip("LIVE_SPACE_BASE_URL is not set")
+    return LIVE_BASE_URL
+
+
+def max_seconds(name: str, default: float) -> float:
+    try:
+        return float(os.getenv(name, str(default)))
+    except ValueError:
+        return default
+
+
+def timed_request(method: str, url: str, **kwargs) -> tuple[requests.Response, float]:
+    start = time.perf_counter()
+    response = requests.request(method, url, **kwargs)
+    elapsed = time.perf_counter() - start
+    return response, elapsed
+
+
+@pytest.mark.live
+def test_live_health_widget_and_config() -> None:
+    base_url = require_live_base_url()
+
+    health, health_seconds = timed_request("GET", f"{base_url}/healthz", timeout=120)
+    widget, widget_seconds = timed_request("GET", f"{base_url}/widget.js", timeout=120)
+    config, config_seconds = timed_request(
+        "GET", f"{base_url}/api/helper/config", timeout=120
+    )
+
+    assert health.status_code == 200
+    assert health.json() == {"status": "ok"}
+    assert health_seconds <= max_seconds("LIVE_SMOKE_MAX_HEALTH_SECONDS", 120)
+    assert widget.status_code == 200
+    assert "Towards AI Helper" in widget.text
+    assert "Choose a starter prompt" in widget.text
+    assert "isSignedIn" in widget.text
+    assert widget_seconds <= max_seconds("LIVE_SMOKE_MAX_WIDGET_SECONDS", 30)
+    assert config.status_code == 200
+    payload = config.json()
+    assert FIRST_PROMPT in payload["forcedPrompts"]
+    assert "/courses/agent-engineering" in payload["allowedPathsByHost"]["academy.towardsai.net"]
+    assert config_seconds <= max_seconds("LIVE_SMOKE_MAX_CONFIG_SECONDS", 30)
+
+
+@pytest.mark.live
+@pytest.mark.skipif(
+    not RUN_LIVE_CHAT,
+    reason="RUN_LIVE_CHAT_SMOKE is not enabled",
+)
+def test_live_chat_returns_concise_answer() -> None:
+    base_url = require_live_base_url()
+    response, elapsed = timed_request(
+        "POST",
+        f"{base_url}/api/helper/chat",
+        json={
+            "query": FIRST_PROMPT,
+            "selectedPrompt": FIRST_PROMPT,
+            "visitorId": "github-action-smoke",
+            "context": {
+                "url": "https://academy.towardsai.net/courses/agent-engineering",
+                "pageTitle": "Agent course",
+                "signedIn": False,
+            },
+        },
+        headers=HEADERS,
+        timeout=120,
+    )
+
+    assert response.status_code == 200
+    payload = response.json()
+    assert payload["answer"].strip()
+    assert len(payload["answer"]) < 1400
+    assert payload["sources"]
+    assert elapsed <= max_seconds("LIVE_SMOKE_MAX_CHAT_SECONDS", 90)