launching

.env.example

@@ -1,12 +1,18 @@
 # ---- App
 ENV=development
+APP_NAME=Notestack
 FRONTEND_URL=http://localhost:5173
 API_URL=http://localhost:8000
 CORS_ORIGINS=http://localhost:5173
-JWT_SECRET=replace-with-64-random-chars
 INTERNAL_TOKEN=replace-with-random-token
 BILLING_ENABLED=false
 
+# ---- Auth (JWT). Revocation bumps users.token_version, so tokens can be long lived.
+JWT_SECRET=replace-with-64-random-chars
+JWT_ALGORITHM=HS256
+JWT_EXPIRATION_HOURS=72
+JWT_REFRESH_EXPIRATION_DAYS=30
+
 # ---- Database (also backs the job queue)
 # Local: a SQLite file, created by `alembic upgrade head` run from backend/.
 # Prod (Neon, Supabase, RDS...): Postgres with the psycopg driver, e.g.
@@ -29,6 +35,8 @@ RESEND_API_KEY=
 FROM_EMAIL=Notestack <hello@notestack.ai>
 ALERTS_EMAIL=arslan@firebird-technologies.com
 UNSUBSCRIBE_SECRET=replace-me
+# Hour (UTC, 0 to 23) at which scheduled update email campaigns send their daily batch.
+UPDATE_EMAIL_SEND_HOUR=9
 
 # ---- Local dev conveniences
 # The API runs the job worker in process when ENV=development (set false to use python -m app.worker).
@@ -46,25 +54,37 @@ R2_SECRET_ACCESS_KEY=minioadmin
 R2_BUCKET=notestack-assets
 R2_ENDPOINT_URL=
 R2_PUBLIC_BASE_URL=
+# How long presigned download links stay valid, in seconds.
+R2_PRESIGN_TTL_SECONDS=3600
+# Largest file a browser may upload (bytes). 209715200 = 200 MB.
+MAX_UPLOAD_BYTES=209715200
 
 # ---- LLM (any LiteLLM model string). Defaults target Z.ai GLM-5.3 via its OpenAI compatible API.
 # GLM-5.x always reasons; LLM_REASONING_EFFORT (low | high | max) trades cost for depth.
 # Cheaper: LLM_MODEL=openai/glm-5.3-flash. Free for local dev: openai/glm-4.7-flash
 LLM_MODEL=openai/glm-5.3
 LLM_FAST_MODEL=openai/glm-5.3-flash
-# Chat triage classifier (greetings, off topic, follow ups). Empty = LLM_FAST_MODEL.
-LLM_TRIAGE_MODEL=
 LLM_API_BASE=https://api.z.ai/api/paas/v4
 LLM_API_KEY=
 LLM_TEMPERATURE=1.0
 LLM_MAX_TOKENS=16000
 LLM_REASONING_EFFORT=low
+# Fallback chat triage model when Jev is not configured. Empty = LLM_FAST_MODEL.
+LLM_TRIAGE_MODEL=
+
+# ---- Chat triage: TypeSafe Jev (https://typesafe.ai)
+# A fast classifier (typed choices, no text generation) that decides what each chat message needs
+# before any research runs. With a key set, greetings, off topic and app questions never reach the
+# LLM, and archive questions get a quick or deep research budget. Empty = LLM triage above.
+TYPESAFE_API_KEY=
+TYPESAFE_MODEL=jev-latest
+TYPESAFE_URL=https://api.typesafe.ai
 
 # ---- Research corpus (posts as markdown files; the agent greps and reads them, no vector index)
 CORPUS_CACHE_DIR=.corpus-cache
 RESEARCH_MAX_STEPS=10
 
-# ---- Worker (jobs queue lives in Postgres; no Redis)
+# ---- Worker (jobs queue lives in the database; no Redis)
 WORKER_CONCURRENCY=4
 WORKER_POLL_SECONDS=1
 JOB_STALE_SECONDS=900
@@ -75,6 +95,9 @@ ELEVENLABS_MODEL=eleven_multilingual_v2
 ELEVENLABS_VOICE_A=EXAVITQu4vr4xnSDxMaL
 ELEVENLABS_VOICE_B=JBFqnCBsd6RMkjVDRZzb
 
+# ---- Renderer (Remotion service for videos, quote cards and carousels: cd renderer && npm start)
+RENDERER_URL=http://localhost:3100
+
 # ---- Launchpad social publishing
 # Bluesky needs nothing here (users connect with an app password).
 # X: developer app with OAuth 2.0, type Web App, scopes tweet.read tweet.write users.read offline.access.

backend/app/config.py

@@ -1,6 +1,7 @@
 from functools import lru_cache
 from pathlib import Path
 
+from pydantic import field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 # One .env at the repo root serves every way of running the API; a backend/.env (or the
@@ -65,6 +66,10 @@ class Settings(BaseSettings):
     llm_fast_model: str = "openai/glm-5.3-flash"
     # Chat triage (small talk, off topic, follow up rewriting). Empty = LLM_FAST_MODEL.
     llm_triage_model: str = ""
+    # TypeSafe Jev classifier for chat triage. When set, triage uses Jev instead of an LLM call.
+    typesafe_api_key: str = ""
+    typesafe_model: str = "jev-latest"
+    typesafe_url: str = "https://api.typesafe.ai"
     llm_api_base: str = "https://api.z.ai/api/paas/v4"
     llm_api_key: str = ""
     llm_temperature: float = 1.0  # Z.ai recommends 1.0 for GLM-5.x
@@ -97,6 +102,12 @@ class Settings(BaseSettings):
     # Billing
     billing_enabled: bool = False
 
+    @field_validator("run_worker_in_api", mode="before")
+    @classmethod
+    def _blank_is_default(cls, value):
+        """RUN_WORKER_IN_API= (blank, as in .env.example) means "decide from ENV", not a parse error."""
+        return None if isinstance(value, str) and not value.strip() else value
+
     @property
     def worker_in_api(self) -> bool:
         return self.env == "development" if self.run_worker_in_api is None else self.run_worker_in_api

backend/app/pipeline/research.py

@@ -7,6 +7,8 @@ conversation, answers off topic and app questions directly, and turns follow ups
 questions. Only real archive questions run the research agent, with a small step budget for simple
 lookups and the full budget for synthesis."""
 
+import logging
+import random
 import re
 from collections.abc import Callable
 from dataclasses import dataclass, field
@@ -18,8 +20,10 @@ from app.corpus import Corpus, ScopedTools
 from app.llm.postprocess import strip_em_dashes
 from app.llm.provider import main_lm, track_usage, triage_lm
 from app.llm.signatures import ResearchArchive, TriageMessage
+from app.services import jev
 
 _MARKER = re.compile(r"\[(\d+)\]")
+log = logging.getLogger(__name__)
 
 
 @dataclass
@@ -98,8 +102,78 @@ class Triage:
     completion_tokens: int = 0
 
 
+JEV_INTENT = {
+    "archive": {
+        "what": "Needs facts, ideas, quotes, opinions or history from the writer's own posts, including follow "
+                "ups to the conversation like 'say more', 'why?', 'what about last year?'",
+        "examples": ["What have I written about pricing?", "Summarize my take on AI", "Tell me more about that"],
+    },
+    "chitchat": {
+        "what": "Greetings, thanks, reactions or small talk with no question about the posts",
+        "examples": ["hello there", "that was helpful, thanks", "you are great"],
+    },
+    "about_app": {
+        "what": "How to use Notestack itself: sources, notebooks, audio, video, launch kits, settings",
+        "examples": ["How do I add another Substack?", "Can you make a podcast from this?"],
+    },
+    "off_topic": {
+        "what": "General knowledge, coding, math, news, homework or tasks unrelated to the writer's posts",
+        "not_for": "Questions about what the writer wrote, even if the subject is general",
+        "examples": ["What is the capital of France?", "Write me a Python script", "Who won the game last night?"],
+    },
+}
+JEV_DEPTH = {
+    "quick": "A single fact, quote or lookup in one or two posts",
+    "deep": "Synthesis, comparison or change over time across many posts",
+}
+JEV_MIN_CONFIDENCE = 0.55  # below this, research anyway: a wasted search beats a wrong brush off
+
+
+def canned_reply(kind: str, allowed: dict[str, str]) -> str:
+    """Templated replies for messages that need no research (no model call)."""
+    titles = [t for t in allowed.values() if t]
+    sample = random.choice(titles) if titles else None
+    try_this = f' For example: "What is the main argument in {sample}?"' if sample else ""
+    if kind == "about_app":
+        return ("Add more Substacks, blogs or files on the Sources page, then group posts into notebooks. From "
+                "any notebook, the Studio panel on the right makes summaries, audio overviews, videos and quote "
+                "cards, and Launch Kit and Launchpad turn a post into scheduled social posts. In this chat I "
+                "answer questions about the posts in this notebook." + try_this)
+    if kind == "off_topic":
+        return ("I only answer from the posts in this notebook, so I cannot help with that one. Ask me about "
+                "something you have written instead." + try_this)
+    return "Happy to help. Ask me anything about the posts in this notebook." + try_this
+
+
+def triage_with_jev(message: str, history: list[Turn], notebook: str) -> Triage:
+    state = {"notebook": notebook, "conversation": conversation_text(history, limit=4), "message": message}
+    answers = jev.decide(state, {
+        "intent": {"instructions": "What does the latest message need from a research assistant that only "
+                                   "knows this writer's posts?", "criteria": JEV_INTENT},
+        "depth": {"instructions": "If it is about the posts, how much research does it need?",
+                  "criteria": JEV_DEPTH},
+    })
+    intent, depth = answers["intent"], answers["depth"]
+    kind = intent.choice if intent.choice in JEV_INTENT else "archive"
+    if kind != "archive" and intent.confidence < JEV_MIN_CONFIDENCE:
+        kind = "archive"
+    # Jev does not write text: the research agent resolves follow ups using the conversation it is given.
+    return Triage(kind, message, depth.choice if depth.choice in JEV_DEPTH else "deep", "")
+
+
 def triage(message: str, history: list[Turn], notebook: str) -> Triage:
-    """One cheap call: is this worth researching, and what exactly should be researched?"""
+    """Decide whether a message is worth researching. Jev when configured (fast, typed, no generation),
+    otherwise one cheap call on the triage LLM."""
+    if jev.configured():
+        try:
+            return triage_with_jev(message, history, notebook)
+        except jev.JevError:
+            log.warning("Jev triage failed, falling back to the LLM", exc_info=True)
+    return triage_llm(message, history, notebook)
+
+
+def triage_llm(message: str, history: list[Turn], notebook: str) -> Triage:
+    """One cheap LLM call: is this worth researching, and what exactly should be researched?"""
     lm = triage_lm()
     try:
         with track_usage(lm) as usage, dspy.context(lm=lm):
@@ -175,7 +249,9 @@ def research(
         on_step("think", "Reading the conversation")
     route = triage(question, history, notebook_brief(notebook_title, allowed))
     if route.kind != "archive":
-        return ResearchResult(route.reply, False, [], route.prompt_tokens, route.completion_tokens,
+        # App help is always the vetted template: a model would invent product facts.
+        reply = canned_reply(route.kind, allowed) if route.kind == "about_app" or not route.reply else route.reply
+        return ResearchResult(reply, False, [], route.prompt_tokens, route.completion_tokens,
                               kind=route.kind, question=question)
 
     corpus.sync()

backend/app/services/jev.py

@@ -0,0 +1,53 @@
+"""TypeSafe Jev: a System One classifier. It picks from options we define (with probabilities) and never
+generates text, so it is the fast, cheap way to decide what a chat message needs.
+
+API: POST {TYPESAFE_URL}/v1/systemone with {"state", "model", "questions"}; answers come back per
+question id with "choice", "confidence" and "probabilities". https://docs.typesafe.ai/primitives/choice
+"""
+
+from dataclasses import dataclass
+
+import httpx
+
+from app.config import settings
+
+
+class JevError(RuntimeError):
+    pass
+
+
+@dataclass
+class Choice:
+    choice: str
+    confidence: float
+    probabilities: dict[str, float]
+
+
+def configured() -> bool:
+    return bool(settings.typesafe_api_key)
+
+
+def decide(state: str | dict, questions: dict[str, dict], timeout: float = 6.0) -> dict[str, Choice]:
+    """Ask several Choice questions about one state in a single request (Jev evaluates them in parallel)."""
+    if not configured():
+        raise JevError("TYPESAFE_API_KEY is not set")
+    body = {
+        "state": state,
+        "model": settings.typesafe_model,
+        "questions": {qid: {"type": "choice", **q} for qid, q in questions.items()},
+    }
+    try:
+        resp = httpx.post(f"{settings.typesafe_url.rstrip('/')}/v1/systemone", json=body, timeout=timeout,
+                          headers={"Authorization": f"Bearer {settings.typesafe_api_key}"})
+    except httpx.HTTPError as exc:
+        raise JevError(f"Jev unreachable: {exc}") from exc
+    if resp.status_code >= 400:
+        raise JevError(f"Jev {resp.status_code}: {resp.text[:300]}")
+    answers = resp.json().get("answers") or {}
+    out = {}
+    for qid in questions:
+        a = answers.get(qid) or {}
+        if "choice" not in a:
+            raise JevError(f"Jev returned no answer for {qid}")
+        out[qid] = Choice(a["choice"], float(a.get("confidence") or 0), a.get("probabilities") or {})
+    return out

backend/tests/test_buildout.py

@@ -708,3 +708,117 @@ def test_tts_retries_rate_limits(monkeypatch):
     monkeypatch.setattr(httpx, "request", lambda *a, **k: httpx.Response(401, json={"detail": {"message": "bad"}}))
     with pytest.raises(tts.TTSError, match="API key"):
         tts._request("GET", "/voices")
+
+
+# Chat: memory and triage (no LLM calls for chatter)
+
+
+def _no_research(monkeypatch):
+    import dspy
+
+    def boom(*a, **k):
+        raise AssertionError("research agent should not run")
+
+    monkeypatch.setattr(dspy, "ReAct", boom)
+
+
+def test_small_talk_needs_no_model(monkeypatch, tmp_path):
+    from app.corpus import Corpus
+    from app.pipeline import research as r
+
+    _no_research(monkeypatch)
+    monkeypatch.setattr(r, "triage", lambda *a: (_ for _ in ()).throw(AssertionError("no triage for chatter")))
+    out = r.research(Corpus(uuid.uuid4(), cache_dir=str(tmp_path)), {"a.md": "On Pricing"}, "thanks!",
+                     history=[r.Turn("user", "q"), r.Turn("assistant", "a")])
+    assert out.kind == "chitchat" and "helped" in out.text and out.prompt_tokens == 0
+
+
+def test_jev_triage_routes_off_topic_without_llm(monkeypatch, tmp_path):
+    from app.config import settings
+    from app.corpus import Corpus
+    from app.pipeline import research as r
+    from app.services import jev
+
+    _no_research(monkeypatch)
+    monkeypatch.setattr(settings, "typesafe_api_key", "sk-test")
+    seen = {}
+
+    def decide(state, questions, timeout=6.0):
+        seen.update(state=state, questions=questions)
+        return {"intent": jev.Choice("off_topic", 0.93, {}), "depth": jev.Choice("quick", 0.8, {})}
+
+    monkeypatch.setattr(jev, "decide", decide)
+    monkeypatch.setattr(r, "triage_llm", lambda *a: (_ for _ in ()).throw(AssertionError("LLM triage not needed")))
+    out = r.research(Corpus(uuid.uuid4(), cache_dir=str(tmp_path)), {"a.md": "On Pricing"},
+                     "Write me a python script", history=[r.Turn("user", "What did I say about pricing?")])
+    assert out.kind == "off_topic" and "On Pricing" in out.text
+    assert seen["questions"]["intent"]["criteria"]["archive"]
+    assert "pricing" in seen["state"]["conversation"]
+
+
+def test_jev_low_confidence_or_failure_still_researches(monkeypatch, tmp_path):
+    from app.config import settings
+    from app.pipeline import research as r
+    from app.services import jev
+
+    monkeypatch.setattr(settings, "typesafe_api_key", "sk-test")
+    monkeypatch.setattr(jev, "decide", lambda *a, **k: {"intent": jev.Choice("off_topic", 0.4, {}),
+                                                         "depth": jev.Choice("deep", 0.9, {})})
+    assert r.triage("hmm what about that", [], "nb").kind == "archive"
+
+    def down(*a, **k):
+        raise jev.JevError("down")
+
+    monkeypatch.setattr(jev, "decide", down)
+    monkeypatch.setattr(r, "triage_llm", lambda *a: r.Triage("archive", "standalone q", "quick", ""))
+    t = r.triage("tell me more", [], "nb")
+    assert t.question == "standalone q" and t.depth == "quick"
+
+
+def test_jev_request_shape(monkeypatch):
+    from app.config import settings
+    from app.services import jev
+
+    monkeypatch.setattr(settings, "typesafe_api_key", "sk-test")
+    captured = {}
+
+    def post(url, json, timeout, headers):
+        captured.update(url=url, body=json, headers=headers)
+        return httpx.Response(200, json={"answers": {"intent": {"type": "choice", "choice": "archive",
+                                                                "confidence": 0.9,
+                                                                "probabilities": {"archive": 0.9}}}})
+
+    monkeypatch.setattr(httpx, "post", post)
+    out = jev.decide("state", {"intent": {"instructions": "?", "criteria": {"archive": "x"}}})
+    assert out["intent"].choice == "archive"
+    assert captured["url"].endswith("/v1/systemone") and captured["headers"]["Authorization"] == "Bearer sk-test"
+    assert captured["body"]["questions"]["intent"]["type"] == "choice" and captured["body"]["model"] == "jev-latest"
+
+
+def test_chat_passes_history_as_memory(client, auth, run_jobs, feed, monkeypatch):
+    from app.pipeline.research import ResearchResult
+    from app.routers import notebooks as nbr
+
+    connect(client, auth, run_jobs)
+    doc = docs(client, auth)[0]
+    nb = client.post("/api/notebooks", json={"title": "N", "document_ids": [doc["id"]]}, headers=auth).json()
+    calls = []
+
+    def fake_research(corpus, allowed, question, on_step=None, history=None, notebook_title=""):
+        calls.append((question, [(t.role, t.text) for t in history or []], notebook_title))
+        return ResearchResult(f"answer to {question}", False, [])
+
+    monkeypatch.setattr(nbr, "research", fake_research)
+
+    def ask(q, chat_id=None):
+        body = client.post(f"/api/notebooks/{nb['id']}/chat", json={"question": q, "chat_id": chat_id},
+                           headers=auth).text
+        import json as _json
+        import re as _re
+        return _json.loads(_re.search(r"event: status\ndata: (.*)", body).group(1))["chat_id"]
+
+    chat_id = ask("What did I say about pricing?")
+    ask("Why?", chat_id)
+    assert calls[0][1] == [] and calls[0][2] == "N"
+    assert calls[1][1] == [("user", "What did I say about pricing?"),
+                           ("assistant", "answer to What did I say about pricing?")]

backend/tests/test_corpus.py

@@ -125,12 +125,14 @@ def test_react_agent_end_to_end_with_scripted_model(corpus_pair, monkeypatch):
     ])
     monkeypatch.setattr(research_mod, "main_lm", lambda: lm)
     monkeypatch.setattr(research_mod, "track_usage", _no_usage)
+    monkeypatch.setattr(research_mod, "triage", lambda *a: research_mod.Triage("archive", "What did I charge?",
+                                                                                "deep", ""))
     seen = []
     with dspy.context(adapter=dspy.ChatAdapter()):
         result = research_mod.research(
             reader, {p1: "On pricing"}, "What did I charge?", on_step=lambda k, d: seen.append(k)
         )
-    assert seen == ["search", "read"]
+    assert seen == ["think", "search", "read"]
     assert result.unsupported is False
     assert result.text.endswith("[1].")
     assert result.citations[0].path == p1 and "$5 to $8" in result.citations[0].quote