ignatius commited on
Commit
fa829bf
·
1 Parent(s): be9517e

Model providers: Claude via OpenRouter by default, OpenAI fallback, any OpenAI-compatible endpoint

Browse files

- New default provider openrouter (anthropic/claude-sonnet-5.5), with
openai/gpt-4.1-mini tried once on outages, rate limits or unreadable
answers; account errors (bad key, no credit) are not retried.
- New 'compatible' provider for an institution's own gateway or local
open models (vLLM, Ollama) via CURATORBOT_LLM_BASE_URL.
- Plain-English errors for curators; details go to the server log.
- /api/health and the How it works tab show the model and any fallback.
- docs/model-providers.md explains the choice and data protection.

Claude-Session: https://claude.ai/code/session_01AteuhwysR4rHp4fqUteLAE

.env.example CHANGED
@@ -1,10 +1,19 @@
1
  # Copy to .env for local runs. On Hugging Face, set these as Space secrets/variables.
2
 
3
- # Language model (anthropic | openai). The key for the chosen provider is required for live analysis.
4
- CURATORBOT_LLM_PROVIDER=anthropic
5
- CURATORBOT_LLM_MODEL=
 
6
  ANTHROPIC_API_KEY=
7
  OPENAI_API_KEY=
 
 
 
 
 
 
 
 
8
 
9
  # Live features
10
  CURATORBOT_ENABLE_LIVE=1
 
1
  # Copy to .env for local runs. On Hugging Face, set these as Space secrets/variables.
2
 
3
+ # Language model: openrouter (default) | anthropic | openai | compatible. See docs/model-providers.md.
4
+ # The key for the chosen provider is required for live analysis.
5
+ CURATORBOT_LLM_PROVIDER=openrouter
6
+ OPENROUTER_API_KEY=
7
  ANTHROPIC_API_KEY=
8
  OPENAI_API_KEY=
9
+ # Leave empty for the provider default (OpenRouter: anthropic/claude-sonnet-5.5).
10
+ CURATORBOT_LLM_MODEL=
11
+ # Tried once if the main model fails. Unset: provider default (OpenRouter: openai/gpt-4.1-mini).
12
+ # Set to an empty value to switch the fallback off.
13
+ # CURATORBOT_LLM_FALLBACK_MODEL=
14
+ # For CURATORBOT_LLM_PROVIDER=compatible (own gateway, vLLM, Ollama):
15
+ # CURATORBOT_LLM_BASE_URL=http://localhost:11434/v1
16
+ # CURATORBOT_LLM_API_KEY=
17
 
18
  # Live features
19
  CURATORBOT_ENABLE_LIVE=1
CLAUDE.md CHANGED
@@ -14,7 +14,7 @@ CuratorBot drafts Curator Briefs for donated Holocaust oral history interviews,
14
  - `curatorbot/transcript.py` segments (segId, start, role Q/A, text, lang, translation)
15
  - `curatorbot/annotate.py` spatio-textual 0.4.1 (pinned tag) on narrator turns
16
  - `curatorbot/gazetteer.py` + `data/period_gazetteer.json` period names and review reasons
17
- - `curatorbot/agent.py` prompt, schema and validators; `llm.py` Anthropic/OpenAI switch via env
18
  - `curatorbot/pipeline.py` builds the brief (schema in `docs/brief-schema.md`)
19
  - `app/server.py` FastAPI; `app/static/` viewer (vanilla JS, no build step)
20
  - `scripts/prepare_interview.py` GPU path for released interviews; `curatorbot/backtest.py` headings vs catalogue
 
14
  - `curatorbot/transcript.py` segments (segId, start, role Q/A, text, lang, translation)
15
  - `curatorbot/annotate.py` spatio-textual 0.4.1 (pinned tag) on narrator turns
16
  - `curatorbot/gazetteer.py` + `data/period_gazetteer.json` period names and review reasons
17
+ - `curatorbot/agent.py` prompt, schema and validators; `llm.py` provider switch via env (OpenRouter default with fallback; Anthropic, OpenAI, any OpenAI-compatible endpoint)
18
  - `curatorbot/pipeline.py` builds the brief (schema in `docs/brief-schema.md`)
19
  - `app/server.py` FastAPI; `app/static/` viewer (vanilla JS, no build step)
20
  - `scripts/prepare_interview.py` GPU path for released interviews; `curatorbot/backtest.py` headings vs catalogue
README.md CHANGED
@@ -34,7 +34,7 @@ It is built on [spatio-textual](https://github.com/SpaceTimeNarratives/spatio-te
34
  ```bash
35
  python -m venv .venv && source .venv/bin/activate
36
  pip install -r requirements.txt && pip install --no-deps -e . && python -m spacy download en_core_web_sm
37
- cp .env.example .env # add ANTHROPIC_API_KEY (or OPENAI_API_KEY with CURATORBOT_LLM_PROVIDER=openai)
38
  set -a; . ./.env; set +a
39
  curatorbot serve # http://localhost:7860
40
  pytest -q
 
34
  ```bash
35
  python -m venv .venv && source .venv/bin/activate
36
  pip install -r requirements.txt && pip install --no-deps -e . && python -m spacy download en_core_web_sm
37
+ cp .env.example .env # add OPENROUTER_API_KEY (other providers: docs/model-providers.md)
38
  set -a; . ./.env; set +a
39
  curatorbot serve # http://localhost:7860
40
  pytest -q
app/server.py CHANGED
@@ -25,6 +25,7 @@ import os
25
  from contextlib import asynccontextmanager
26
  from datetime import datetime, timezone
27
  import re
 
28
  import tempfile
29
  from pathlib import Path
30
  from typing import Any
@@ -178,7 +179,7 @@ def _llm_ready() -> tuple[bool, str]:
178
  try:
179
  from curatorbot.llm import LLMClient
180
  c = LLMClient()
181
- return c.available(), f"{c.provider}:{c.model}"
182
  except Exception as exc: # misconfiguration should show in /api/health, not crash
183
  return False, str(exc)
184
 
@@ -286,7 +287,10 @@ async def analyse(req: AnalyseRequest, x_demo_passcode: str | None = Header(defa
286
  build_brief, segments, interview_id="LIVE", title=req.title[:120],
287
  donor={k: v[:300] for k, v in req.donor.items() if v}, note="Analysed live; not saved.")
288
  except Exception as exc:
289
- raise HTTPException(502, f"The analysis failed: {exc}") from exc
 
 
 
290
 
291
 
292
  @app.post("/api/transcribe")
 
25
  from contextlib import asynccontextmanager
26
  from datetime import datetime, timezone
27
  import re
28
+ import sys
29
  import tempfile
30
  from pathlib import Path
31
  from typing import Any
 
179
  try:
180
  from curatorbot.llm import LLMClient
181
  c = LLMClient()
182
+ return c.available(), c.describe()
183
  except Exception as exc: # misconfiguration should show in /api/health, not crash
184
  return False, str(exc)
185
 
 
287
  build_brief, segments, interview_id="LIVE", title=req.title[:120],
288
  donor={k: v[:300] for k, v in req.donor.items() if v}, note="Analysed live; not saved.")
289
  except Exception as exc:
290
+ from curatorbot.llm import LLMError, friendly_error
291
+ msg = str(exc) if isinstance(exc, LLMError) else friendly_error(exc)
292
+ print(f"[curatorbot] analysis failed: {type(exc).__name__}: {exc}", file=sys.stderr)
293
+ raise HTTPException(502, msg) from exc
294
 
295
 
296
  @app.post("/api/transcribe")
app/static/app.js CHANGED
@@ -323,7 +323,7 @@ function renderDonor(){
323
  /* ---------- how it works ---------- */
324
  function renderHood(){
325
  const r = D.run || {}, lat = (D.annotations || []).reduce((a,x) => a + (x.latency_ms || 0), 0);
326
- const llm = r.llm ? `${r.llm.provider}:${r.llm.model}, ${(r.llm.latency_ms/1000).toFixed(1)} s, ${r.llm.input_tokens} in / ${r.llm.output_tokens} out tokens` : "precomputed or not run";
327
  const steps = [
328
  ["Media preparation and language ID","Parts grouped and checked, audio extracted, languages detected per segment.", G.media?.simulated ? "Simulated" : (G.media ? "Run offline" : "Not run: transcript supplied"), G.media && !G.media.simulated ? "good" : "flag"],
329
  ["Transcription with speaker roles","faster-whisper; interviewer and narrator separated.", G.media && !G.media.simulated ? "Run offline" : "Transcript supplied", G.media && !G.media.simulated ? "good" : "flag"],
 
323
  /* ---------- how it works ---------- */
324
  function renderHood(){
325
  const r = D.run || {}, lat = (D.annotations || []).reduce((a,x) => a + (x.latency_ms || 0), 0);
326
+ const llm = r.llm ? `${r.llm.provider}:${r.llm.model}${r.llm.fallback_from ? ` (fallback; ${r.llm.fallback_from} failed)` : ""}, ${(r.llm.latency_ms/1000).toFixed(1)} s, ${r.llm.input_tokens} in / ${r.llm.output_tokens} out tokens` : "precomputed or not run";
327
  const steps = [
328
  ["Media preparation and language ID","Parts grouped and checked, audio extracted, languages detected per segment.", G.media?.simulated ? "Simulated" : (G.media ? "Run offline" : "Not run: transcript supplied"), G.media && !G.media.simulated ? "good" : "flag"],
329
  ["Transcription with speaker roles","faster-whisper; interviewer and narrator separated.", G.media && !G.media.simulated ? "Run offline" : "Transcript supplied", G.media && !G.media.simulated ? "good" : "flag"],
curatorbot/config.py CHANGED
@@ -10,9 +10,14 @@ from dataclasses import dataclass, field
10
  from pathlib import Path
11
 
12
  DEFAULT_MODELS = {
 
13
  "anthropic": "claude-sonnet-5-5",
14
  "openai": "gpt-4.1-mini",
15
  }
 
 
 
 
16
 
17
 
18
  def _flag(name: str, default: bool = False) -> bool:
@@ -21,8 +26,12 @@ def _flag(name: str, default: bool = False) -> bool:
21
 
22
  @dataclass(frozen=True)
23
  class Settings:
24
- llm_provider: str = field(default_factory=lambda: os.getenv("CURATORBOT_LLM_PROVIDER", "anthropic").lower())
25
  llm_model: str = field(default_factory=lambda: os.getenv("CURATORBOT_LLM_MODEL", ""))
 
 
 
 
26
  llm_max_tokens: int = field(default_factory=lambda: int(os.getenv("CURATORBOT_LLM_MAX_TOKENS", "6000")))
27
  ner_model: str = field(default_factory=lambda: os.getenv("CURATORBOT_NER_MODEL", "en_core_web_sm"))
28
  data_dir: Path = field(default_factory=lambda: Path(os.getenv("CURATORBOT_DATA_DIR", str(Path(__file__).resolve().parent.parent / "data" / "interviews"))))
@@ -50,6 +59,13 @@ class Settings:
50
  def model(self) -> str:
51
  return self.llm_model or DEFAULT_MODELS.get(self.llm_provider, "")
52
 
 
 
 
 
 
 
 
53
 
54
  def settings() -> Settings:
55
  return Settings()
 
10
  from pathlib import Path
11
 
12
  DEFAULT_MODELS = {
13
+ "openrouter": "anthropic/claude-sonnet-5.5",
14
  "anthropic": "claude-sonnet-5-5",
15
  "openai": "gpt-4.1-mini",
16
  }
17
+ # Tried once if the main model fails for a reason another model could fix.
18
+ DEFAULT_FALLBACKS = {
19
+ "openrouter": "openai/gpt-4.1-mini",
20
+ }
21
 
22
 
23
  def _flag(name: str, default: bool = False) -> bool:
 
26
 
27
  @dataclass(frozen=True)
28
  class Settings:
29
+ llm_provider: str = field(default_factory=lambda: os.getenv("CURATORBOT_LLM_PROVIDER", "openrouter").strip().lower())
30
  llm_model: str = field(default_factory=lambda: os.getenv("CURATORBOT_LLM_MODEL", ""))
31
+ llm_fallback_model: str | None = field(default_factory=lambda: os.getenv("CURATORBOT_LLM_FALLBACK_MODEL"))
32
+ # For the 'compatible' provider: an institution's own gateway or a local vLLM/Ollama server.
33
+ llm_base_url: str = field(default_factory=lambda: os.getenv("CURATORBOT_LLM_BASE_URL", ""))
34
+ llm_json_mode: bool = field(default_factory=lambda: _flag("CURATORBOT_LLM_JSON_MODE", True))
35
  llm_max_tokens: int = field(default_factory=lambda: int(os.getenv("CURATORBOT_LLM_MAX_TOKENS", "6000")))
36
  ner_model: str = field(default_factory=lambda: os.getenv("CURATORBOT_NER_MODEL", "en_core_web_sm"))
37
  data_dir: Path = field(default_factory=lambda: Path(os.getenv("CURATORBOT_DATA_DIR", str(Path(__file__).resolve().parent.parent / "data" / "interviews"))))
 
59
  def model(self) -> str:
60
  return self.llm_model or DEFAULT_MODELS.get(self.llm_provider, "")
61
 
62
+ @property
63
+ def fallback_model(self) -> str:
64
+ """Empty string disables the fallback; unset uses the provider default."""
65
+ if self.llm_fallback_model is not None:
66
+ return self.llm_fallback_model.strip()
67
+ return DEFAULT_FALLBACKS.get(self.llm_provider, "")
68
+
69
 
70
  def settings() -> Settings:
71
  return Settings()
curatorbot/llm.py CHANGED
@@ -1,17 +1,35 @@
1
- """Provider-agnostic JSON completion (Anthropic by default, OpenAI optional)."""
 
 
 
 
 
 
 
 
 
 
 
 
2
  from __future__ import annotations
3
 
4
  import json
5
  import os
6
  import re
 
7
  import time
8
  from typing import Any
9
 
10
  from .config import Settings, settings
11
 
 
 
 
 
 
12
 
13
  class LLMError(RuntimeError):
14
- pass
15
 
16
 
17
  def extract_json(text: str) -> dict[str, Any]:
@@ -42,39 +60,105 @@ def extract_json(text: str) -> dict[str, Any]:
42
  raise LLMError("The model's JSON was incomplete; raise CURATORBOT_LLM_MAX_TOKENS.")
43
 
44
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
45
  class LLMClient:
46
  def __init__(self, cfg: Settings | None = None):
47
  self.cfg = cfg or settings()
48
  self.provider = self.cfg.llm_provider
49
  self.model = self.cfg.model
50
- if self.provider not in {"anthropic", "openai"}:
51
- raise LLMError(f"Unsupported provider {self.provider!r}; use 'anthropic' or 'openai'.")
 
52
  if not self.model:
53
  raise LLMError("Set CURATORBOT_LLM_MODEL.")
 
 
54
 
55
  def available(self) -> bool:
56
- key = "ANTHROPIC_API_KEY" if self.provider == "anthropic" else "OPENAI_API_KEY"
57
- return bool(os.getenv(key))
 
 
 
 
58
 
59
  def complete_json(self, system: str, user: str) -> tuple[dict[str, Any], dict[str, Any]]:
60
- """Return (parsed JSON, telemetry)."""
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
61
  t0 = time.perf_counter()
 
 
 
 
 
 
62
  if self.provider == "anthropic":
63
  from anthropic import Anthropic
64
  res = Anthropic().messages.create(
65
- model=self.model, max_tokens=self.cfg.llm_max_tokens, system=system,
66
  messages=[{"role": "user", "content": user}],
67
  )
68
  text = "".join(b.text for b in res.content if getattr(b, "type", "") == "text")
69
- usage = {"input_tokens": res.usage.input_tokens, "output_tokens": res.usage.output_tokens}
 
 
 
 
 
 
 
70
  else:
71
- from openai import OpenAI
72
- res = OpenAI().chat.completions.create(
73
- model=self.model, max_tokens=self.cfg.llm_max_tokens,
74
- response_format={"type": "json_object"},
75
- messages=[{"role": "system", "content": system}, {"role": "user", "content": user}],
76
- )
77
- text = res.choices[0].message.content or ""
78
- usage = {"input_tokens": res.usage.prompt_tokens, "output_tokens": res.usage.completion_tokens}
79
- telemetry = {"provider": self.provider, "model": self.model, "latency_ms": round((time.perf_counter() - t0) * 1000), **usage}
80
- return extract_json(text), telemetry
 
 
 
1
+ """Provider-agnostic JSON completion.
2
+
3
+ Providers (CURATORBOT_LLM_PROVIDER):
4
+ openrouter (default) one key, many models; default Claude Sonnet with an OpenAI fallback
5
+ anthropic Anthropic API directly
6
+ openai OpenAI API directly
7
+ compatible any OpenAI-compatible endpoint (CURATORBOT_LLM_BASE_URL): an institution's
8
+ own gateway, or open models served locally with vLLM or Ollama
9
+
10
+ If the main model fails for a reason a second model could fix (an outage, rate
11
+ limit or unreadable answer), the fallback model (CURATORBOT_LLM_FALLBACK_MODEL)
12
+ is tried once. Account problems (bad key, no credit) are not retried.
13
+ """
14
  from __future__ import annotations
15
 
16
  import json
17
  import os
18
  import re
19
+ import sys
20
  import time
21
  from typing import Any
22
 
23
  from .config import Settings, settings
24
 
25
+ PROVIDERS = {"openrouter", "anthropic", "openai", "compatible"}
26
+ KEY_ENV = {"openrouter": "OPENROUTER_API_KEY", "anthropic": "ANTHROPIC_API_KEY",
27
+ "openai": "OPENAI_API_KEY", "compatible": "CURATORBOT_LLM_API_KEY"}
28
+ OPENROUTER_URL = "https://openrouter.ai/api/v1"
29
+
30
 
31
  class LLMError(RuntimeError):
32
+ """An error whose message is safe to show to demo users."""
33
 
34
 
35
  def extract_json(text: str) -> dict[str, Any]:
 
60
  raise LLMError("The model's JSON was incomplete; raise CURATORBOT_LLM_MAX_TOKENS.")
61
 
62
 
63
+ def _status(exc: Exception) -> int | None:
64
+ s = getattr(exc, "status_code", None) or getattr(getattr(exc, "response", None), "status_code", None)
65
+ return s if isinstance(s, int) else None
66
+
67
+
68
+ def is_account_error(exc: Exception) -> bool:
69
+ """Bad key or no credit: the same account would fail for any model."""
70
+ msg = str(exc).lower()
71
+ return _status(exc) in {401, 402, 403} or any(w in msg for w in ("credit", "billing", "api key", "api_key", "insufficient_quota"))
72
+
73
+
74
+ def friendly_error(exc: Exception) -> str:
75
+ """One sentence for curators; details go to the server log only."""
76
+ s, msg = _status(exc), str(exc).lower()
77
+ if s == 402 or any(w in msg for w in ("credit", "billing", "insufficient_quota")):
78
+ why = "the model account has run out of credit"
79
+ elif s in {401, 403} or "api key" in msg or "api_key" in msg:
80
+ why = "the model provider did not accept the API key"
81
+ elif s == 429:
82
+ why = "the model provider is busy"
83
+ elif isinstance(exc, LLMError):
84
+ why = str(exc).rstrip(".")
85
+ why = why[:1].lower() + why[1:]
86
+ else:
87
+ why = "the model provider could not be reached"
88
+ return f"Live analysis is unavailable right now: {why}. The precomputed interviews still work."
89
+
90
+
91
  class LLMClient:
92
  def __init__(self, cfg: Settings | None = None):
93
  self.cfg = cfg or settings()
94
  self.provider = self.cfg.llm_provider
95
  self.model = self.cfg.model
96
+ self.fallback = self.cfg.fallback_model if self.cfg.fallback_model != self.model else ""
97
+ if self.provider not in PROVIDERS:
98
+ raise LLMError(f"Unsupported provider {self.provider!r}; use one of {', '.join(sorted(PROVIDERS))}.")
99
  if not self.model:
100
  raise LLMError("Set CURATORBOT_LLM_MODEL.")
101
+ if self.provider == "compatible" and not self.cfg.llm_base_url:
102
+ raise LLMError("Set CURATORBOT_LLM_BASE_URL for the 'compatible' provider.")
103
 
104
  def available(self) -> bool:
105
+ if self.provider == "compatible": # local servers often need no key
106
+ return bool(self.cfg.llm_base_url)
107
+ return bool(os.getenv(KEY_ENV[self.provider]))
108
+
109
+ def describe(self) -> str:
110
+ return f"{self.provider}:{self.model}" + (f" (fallback {self.fallback})" if self.fallback else "")
111
 
112
  def complete_json(self, system: str, user: str) -> tuple[dict[str, Any], dict[str, Any]]:
113
+ """Return (parsed JSON, telemetry). Raises LLMError with a user-safe message."""
114
+ try:
115
+ return self._attempt(self.model, system, user)
116
+ except Exception as exc:
117
+ print(f"[curatorbot] model call failed ({self.model}): {type(exc).__name__}: {exc}", file=sys.stderr)
118
+ if not self.fallback or is_account_error(exc):
119
+ raise LLMError(friendly_error(exc)) from exc
120
+ first = exc
121
+ try:
122
+ data, tel = self._attempt(self.fallback, system, user)
123
+ except Exception as exc:
124
+ print(f"[curatorbot] fallback failed ({self.fallback}): {type(exc).__name__}: {exc}", file=sys.stderr)
125
+ raise LLMError(friendly_error(exc)) from exc
126
+ tel.update(fallback_from=self.model, fallback_reason=type(first).__name__)
127
+ return data, tel
128
+
129
+ def _attempt(self, model: str, system: str, user: str) -> tuple[dict[str, Any], dict[str, Any]]:
130
  t0 = time.perf_counter()
131
+ text, usage, used = self._call(model, system, user)
132
+ telemetry = {"provider": self.provider, "model": used or model,
133
+ "latency_ms": round((time.perf_counter() - t0) * 1000), **usage}
134
+ return extract_json(text), telemetry
135
+
136
+ def _call(self, model: str, system: str, user: str) -> tuple[str, dict[str, int], str]:
137
  if self.provider == "anthropic":
138
  from anthropic import Anthropic
139
  res = Anthropic().messages.create(
140
+ model=model, max_tokens=self.cfg.llm_max_tokens, system=system,
141
  messages=[{"role": "user", "content": user}],
142
  )
143
  text = "".join(b.text for b in res.content if getattr(b, "type", "") == "text")
144
+ return text, {"input_tokens": res.usage.input_tokens, "output_tokens": res.usage.output_tokens}, res.model
145
+
146
+ from openai import OpenAI
147
+ if self.provider == "openrouter":
148
+ client = OpenAI(base_url=OPENROUTER_URL, api_key=os.getenv("OPENROUTER_API_KEY"),
149
+ default_headers={"X-Title": "CuratorBot"})
150
+ elif self.provider == "compatible":
151
+ client = OpenAI(base_url=self.cfg.llm_base_url, api_key=os.getenv("CURATORBOT_LLM_API_KEY") or "not-needed")
152
  else:
153
+ client = OpenAI()
154
+ kwargs: dict[str, Any] = {}
155
+ if self.cfg.llm_json_mode:
156
+ kwargs["response_format"] = {"type": "json_object"}
157
+ res = client.chat.completions.create(
158
+ model=model, max_tokens=self.cfg.llm_max_tokens,
159
+ messages=[{"role": "system", "content": system}, {"role": "user", "content": user}], **kwargs,
160
+ )
161
+ text = res.choices[0].message.content or ""
162
+ usage = res.usage
163
+ return text, {"input_tokens": getattr(usage, "prompt_tokens", 0) or 0,
164
+ "output_tokens": getattr(usage, "completion_tokens", 0) or 0}, getattr(res, "model", "") or model
docs/deploy-huggingface.md CHANGED
@@ -11,7 +11,7 @@ This project hosts the Space on the lead's personal Hugging Face account (`ignat
11
  1. **Subscribe to PRO** on the personal Hugging Face account (Settings > Billing, or huggingface.co/pro).
12
  2. **Create the Space.** New Space: owner `ignatius`, name `curatorbot`, SDK **Docker**, blank template, hardware **CPU basic**, visibility **Private**.
13
  3. **Add secrets** (Space > Settings > Variables and secrets):
14
- - `ANTHROPIC_API_KEY` (secret), or `OPENAI_API_KEY` with variable `CURATORBOT_LLM_PROVIDER=openai`
15
  - `CURATORBOT_DEMO_PASSCODE` (secret): protects your API credit on a public or shared Space
16
  - `CURATORBOT_SITE_PASSCODE` (secret): locks the whole demo behind a sign-in page (see Privacy settings)
17
  - for real interviews: secret `HF_TOKEN` (read access to the private dataset) and variable `CURATORBOT_DATA_REPO=ignatius/curatorbot-data` (see `docs/real-data-runbook.md`)
 
11
  1. **Subscribe to PRO** on the personal Hugging Face account (Settings > Billing, or huggingface.co/pro).
12
  2. **Create the Space.** New Space: owner `ignatius`, name `curatorbot`, SDK **Docker**, blank template, hardware **CPU basic**, visibility **Private**.
13
  3. **Add secrets** (Space > Settings > Variables and secrets):
14
+ - `OPENROUTER_API_KEY` (secret). By default the demo uses Claude Sonnet through OpenRouter, falling back to an OpenAI model if Claude fails. To use another provider, see `docs/model-providers.md`
15
  - `CURATORBOT_DEMO_PASSCODE` (secret): protects your API credit on a public or shared Space
16
  - `CURATORBOT_SITE_PASSCODE` (secret): locks the whole demo behind a sign-in page (see Privacy settings)
17
  - for real interviews: secret `HF_TOKEN` (read access to the private dataset) and variable `CURATORBOT_DATA_REPO=ignatius/curatorbot-data` (see `docs/real-data-runbook.md`)
docs/model-providers.md ADDED
@@ -0,0 +1,30 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Choosing the language model
2
+
3
+ CuratorBot sends one request per interview to a language model, which drafts the summary, chapters, subject headings, journeys and donor checks. The validators then check every quote against the transcript, whichever model wrote it.
4
+
5
+ Each institution chooses where its testimony goes. An administrator sets this once with environment variables (Space secrets and variables on Hugging Face, `.env` locally). Nothing is chosen per user.
6
+
7
+ | `CURATORBOT_LLM_PROVIDER` | Key | Default model | Use it when |
8
+ | --- | --- | --- | --- |
9
+ | `openrouter` (default) | `OPENROUTER_API_KEY` | `anthropic/claude-sonnet-5.5`, falling back to `openai/gpt-4.1-mini` | One account reaches many models; good for demos and comparisons |
10
+ | `anthropic` | `ANTHROPIC_API_KEY` | `claude-sonnet-5-5` | The institution has an Anthropic contract |
11
+ | `openai` | `OPENAI_API_KEY` | `gpt-4.1-mini` | The institution has an OpenAI contract |
12
+ | `compatible` | `CURATORBOT_LLM_API_KEY` (if needed) | set `CURATORBOT_LLM_MODEL` | Testimony must not leave the institution: its own gateway, or open models served with vLLM or Ollama |
13
+
14
+ Other settings:
15
+
16
+ - `CURATORBOT_LLM_MODEL`: use a different model from the provider's catalogue.
17
+ - `CURATORBOT_LLM_FALLBACK_MODEL`: tried once if the main model fails for a reason another model could fix (an outage, a rate limit, an unreadable answer). It is not tried for account problems such as a wrong key or no credit. Set it to an empty value to switch the fallback off. Briefs record which model actually answered.
18
+ - `CURATORBOT_LLM_BASE_URL`: the address of a `compatible` endpoint, for example `http://localhost:11434/v1` for Ollama.
19
+ - `CURATORBOT_LLM_JSON_MODE=0`: for local servers that reject the JSON-mode option.
20
+ - `CURATORBOT_LLM_MAX_TOKENS`: raise it if long interviews return incomplete answers.
21
+
22
+ `/api/health` shows the active provider, model and fallback.
23
+
24
+ ## Data protection
25
+
26
+ - **OpenRouter** forwards each request to the company running the chosen model (Anthropic, OpenAI, or a cloud host of either). In the OpenRouter account's privacy settings, allow only providers that neither train on nor retain prompts before sending pre-accession material.
27
+ - **Direct contracts** (Anthropic, OpenAI) fall under the institution's own terms with that company.
28
+ - **`compatible` with a local server** keeps testimony on the institution's own machines. Quality depends on the open model chosen; run the back-test (`docs/real-data-runbook.md`) before relying on it.
29
+
30
+ When a model call fails, curators see a plain sentence ("Live analysis is unavailable right now: …"); the technical detail goes to the server log only.
docs/real-data-runbook.md CHANGED
@@ -32,7 +32,7 @@ Everything under `private/` stays out of git, and so do the real briefs. Finishe
32
  python scripts/prepare_interview.py --id <ID> --status released \
33
  --transcript private/<ID>/transcript.txt --catalogue private/<ID>/catalogue.json
34
  ```
35
- This needs `ANTHROPIC_API_KEY` in your environment and prints recall against the catalogue.
36
 
37
  Released transcripts carry no timestamps, so the brief cites turn numbers (p001, p002 …) instead of times.
38
 
 
32
  python scripts/prepare_interview.py --id <ID> --status released \
33
  --transcript private/<ID>/transcript.txt --catalogue private/<ID>/catalogue.json
34
  ```
35
+ This needs `OPENROUTER_API_KEY` (or another provider's key, see `docs/model-providers.md`) in your environment and prints recall against the catalogue.
36
 
37
  Released transcripts carry no timestamps, so the brief cites turn numbers (p001, p002 …) instead of times.
38
 
notebooks/prepare_on_colab.ipynb CHANGED
@@ -3,7 +3,7 @@
3
  {
4
  "cell_type": "markdown",
5
  "metadata": {},
6
- "source": "# Prepare a released interview on a Colab GPU\n\nRuntime > Change runtime type > GPU. In Colab's Secrets panel (key icon) add `GH_TOKEN` (a GitHub fine-grained token with read access to SpaceTimeNarratives/curatorbot, needed while the repo is private) and `ANTHROPIC_API_KEY`, and allow this notebook to use them. Media stays in your Google Drive; only the resulting brief is copied back.\n\n1. Put the parts in Drive under `CuratorBot/<ID>/media/`, plus `donor.json` for a Box submission or `catalogue.json` for a released interview (see docs/real-data-runbook.md).\n2. Run the cells in order. The first run stops after transcription so you can review `transcript.txt`.\n3. Confirm release terms with the museum before adding the brief to the public Space."
7
  },
8
  {
9
  "cell_type": "code",
@@ -17,7 +17,7 @@
17
  "metadata": {},
18
  "execution_count": null,
19
  "outputs": [],
20
- "source": "from google.colab import drive\ndrive.mount('/content/drive')\nimport os\nos.environ['ANTHROPIC_API_KEY'] = userdata.get('ANTHROPIC_API_KEY') # add it under Colab Secrets\nID = 'RG-50.030.0001' # change me\nSRC = f'/content/drive/MyDrive/CuratorBot/{ID}'\nSTATUS = 'under_review' # 'under_review' for Box submissions, 'released' for catalogued interviews\nimport os.path\nEXTRA = (f'--donor {SRC}/donor.json' if os.path.exists(f'{SRC}/donor.json') else '') + (f' --catalogue {SRC}/catalogue.json' if os.path.exists(f'{SRC}/catalogue.json') else '')\n"
21
  },
22
  {
23
  "cell_type": "code",
@@ -58,4 +58,4 @@
58
  },
59
  "nbformat": 4,
60
  "nbformat_minor": 5
61
- }
 
3
  {
4
  "cell_type": "markdown",
5
  "metadata": {},
6
+ "source": "# Prepare a released interview on a Colab GPU\n\nRuntime > Change runtime type > GPU. In Colab's Secrets panel (key icon) add `GH_TOKEN` (a GitHub fine-grained token with read access to SpaceTimeNarratives/curatorbot, needed while the repo is private) and `OPENROUTER_API_KEY` (or `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` with `CURATORBOT_LLM_PROVIDER` set), and allow this notebook to use them. Media stays in your Google Drive; only the resulting brief is copied back.\n\n1. Put the parts in Drive under `CuratorBot/<ID>/media/`, plus `donor.json` for a Box submission or `catalogue.json` for a released interview (see docs/real-data-runbook.md).\n2. Run the cells in order. The first run stops after transcription so you can review `transcript.txt`.\n3. Confirm release terms with the museum before adding the brief to the public Space."
7
  },
8
  {
9
  "cell_type": "code",
 
17
  "metadata": {},
18
  "execution_count": null,
19
  "outputs": [],
20
+ "source": "from google.colab import drive\ndrive.mount('/content/drive')\nimport os\nfor _k in ('OPENROUTER_API_KEY', 'ANTHROPIC_API_KEY', 'OPENAI_API_KEY', 'CURATORBOT_LLM_PROVIDER'): # from Colab Secrets\n try:\n os.environ[_k] = userdata.get(_k)\n except Exception:\n pass\nID = 'RG-50.030.0001' # change me\nSRC = f'/content/drive/MyDrive/CuratorBot/{ID}'\nSTATUS = 'under_review' # 'under_review' for Box submissions, 'released' for catalogued interviews\nimport os.path\nEXTRA = (f'--donor {SRC}/donor.json' if os.path.exists(f'{SRC}/donor.json') else '') + (f' --catalogue {SRC}/catalogue.json' if os.path.exists(f'{SRC}/catalogue.json') else '')\n"
21
  },
22
  {
23
  "cell_type": "code",
 
58
  },
59
  "nbformat": 4,
60
  "nbformat_minor": 5
61
+ }
project-kit/knowledge/03_repository_overview.md CHANGED
@@ -22,7 +22,7 @@ It is built on [spatio-textual](https://github.com/SpaceTimeNarratives/spatio-te
22
  ```bash
23
  python -m venv .venv && source .venv/bin/activate
24
  pip install -r requirements.txt && pip install --no-deps -e . && python -m spacy download en_core_web_sm
25
- cp .env.example .env # add ANTHROPIC_API_KEY (or OPENAI_API_KEY with CURATORBOT_LLM_PROVIDER=openai)
26
  set -a; . ./.env; set +a
27
  curatorbot serve # http://localhost:7860
28
  pytest -q
 
22
  ```bash
23
  python -m venv .venv && source .venv/bin/activate
24
  pip install -r requirements.txt && pip install --no-deps -e . && python -m spacy download en_core_web_sm
25
+ cp .env.example .env # add OPENROUTER_API_KEY (other providers: docs/model-providers.md)
26
  set -a; . ./.env; set +a
27
  curatorbot serve # http://localhost:7860
28
  pytest -q
tests/test_llm_providers.py ADDED
@@ -0,0 +1,85 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import pytest
2
+
3
+ from curatorbot import llm
4
+ from curatorbot.config import Settings
5
+
6
+
7
+ class Boom(Exception):
8
+ def __init__(self, msg, status=None):
9
+ super().__init__(msg)
10
+ self.status_code = status
11
+
12
+
13
+ def make(monkeypatch, **env):
14
+ for k in ("CURATORBOT_LLM_PROVIDER", "CURATORBOT_LLM_MODEL", "CURATORBOT_LLM_FALLBACK_MODEL", "CURATORBOT_LLM_BASE_URL"):
15
+ monkeypatch.delenv(k, raising=False)
16
+ for k, v in env.items():
17
+ monkeypatch.setenv(k, v)
18
+ return llm.LLMClient(Settings())
19
+
20
+
21
+ def test_default_is_claude_via_openrouter_with_openai_fallback(monkeypatch):
22
+ c = make(monkeypatch)
23
+ assert (c.provider, c.model, c.fallback) == ("openrouter", "anthropic/claude-sonnet-5.5", "openai/gpt-4.1-mini")
24
+ monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
25
+ assert not c.available()
26
+ monkeypatch.setenv("OPENROUTER_API_KEY", "k")
27
+ assert c.available() and "fallback openai/gpt-4.1-mini" in c.describe()
28
+
29
+
30
+ def test_fallback_can_be_disabled_and_other_providers_have_none(monkeypatch):
31
+ assert make(monkeypatch, CURATORBOT_LLM_FALLBACK_MODEL="").fallback == ""
32
+ assert make(monkeypatch, CURATORBOT_LLM_PROVIDER="anthropic").fallback == ""
33
+
34
+
35
+ def test_compatible_endpoint_needs_a_base_url(monkeypatch):
36
+ with pytest.raises(llm.LLMError):
37
+ make(monkeypatch, CURATORBOT_LLM_PROVIDER="compatible", CURATORBOT_LLM_MODEL="llama")
38
+ c = make(monkeypatch, CURATORBOT_LLM_PROVIDER="compatible", CURATORBOT_LLM_MODEL="llama",
39
+ CURATORBOT_LLM_BASE_URL="http://localhost:11434/v1")
40
+ assert c.available()
41
+
42
+
43
+ def test_fallback_used_on_outage(monkeypatch):
44
+ c = make(monkeypatch)
45
+ calls = []
46
+
47
+ def fake_call(model, system, user):
48
+ calls.append(model)
49
+ if model == c.model:
50
+ raise Boom("upstream overloaded", 503)
51
+ return '{"summary": "ok"}', {"input_tokens": 1, "output_tokens": 1}, model
52
+
53
+ monkeypatch.setattr(c, "_call", fake_call)
54
+ data, tel = c.complete_json("s", "u")
55
+ assert data == {"summary": "ok"} and calls == [c.model, c.fallback]
56
+ assert tel["model"] == c.fallback and tel["fallback_from"] == c.model
57
+
58
+
59
+ def test_fallback_used_when_answer_is_not_json(monkeypatch):
60
+ c = make(monkeypatch)
61
+ monkeypatch.setattr(c, "_call", lambda m, s, u: ("no json here" if m == c.model else '{"a": 1}', {}, m))
62
+ assert c.complete_json("s", "u")[0] == {"a": 1}
63
+
64
+
65
+ def test_no_retry_on_account_errors_and_message_is_plain(monkeypatch):
66
+ c = make(monkeypatch)
67
+ calls = []
68
+
69
+ def fake_call(model, system, user):
70
+ calls.append(model)
71
+ raise Boom("Error code: 402 - {'error': {'message': 'Insufficient credits'}}", 402)
72
+
73
+ monkeypatch.setattr(c, "_call", fake_call)
74
+ with pytest.raises(llm.LLMError) as e:
75
+ c.complete_json("s", "u")
76
+ assert calls == [c.model]
77
+ assert str(e.value) == ("Live analysis is unavailable right now: the model account has run out of credit. "
78
+ "The precomputed interviews still work.")
79
+ assert "402" not in str(e.value)
80
+
81
+
82
+ def test_friendly_errors():
83
+ assert "did not accept the API key" in llm.friendly_error(Boom("invalid x-api-key", 401))
84
+ assert "busy" in llm.friendly_error(Boom("slow down", 429))
85
+ assert "could not be reached" in llm.friendly_error(ConnectionError("dns"))