Spaces:
Running
Running
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 +12 -3
- CLAUDE.md +1 -1
- README.md +1 -1
- app/server.py +6 -2
- app/static/app.js +1 -1
- curatorbot/config.py +17 -1
- curatorbot/llm.py +103 -19
- docs/deploy-huggingface.md +1 -1
- docs/model-providers.md +30 -0
- docs/real-data-runbook.md +1 -1
- notebooks/prepare_on_colab.ipynb +3 -3
- project-kit/knowledge/03_repository_overview.md +1 -1
- tests/test_llm_providers.py +85 -0
.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
|
| 4 |
-
|
| 5 |
-
|
|
|
|
| 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`
|
| 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
|
| 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(),
|
| 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 |
-
|
|
|
|
|
|
|
|
|
|
| 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", "
|
| 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
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 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 |
-
|
| 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.
|
| 51 |
-
|
|
|
|
| 52 |
if not self.model:
|
| 53 |
raise LLMError("Set CURATORBOT_LLM_MODEL.")
|
|
|
|
|
|
|
| 54 |
|
| 55 |
def available(self) -> bool:
|
| 56 |
-
|
| 57 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 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=
|
| 66 |
messages=[{"role": "user", "content": user}],
|
| 67 |
)
|
| 68 |
text = "".join(b.text for b in res.content if getattr(b, "type", "") == "text")
|
| 69 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 70 |
else:
|
| 71 |
-
|
| 72 |
-
|
| 73 |
-
|
| 74 |
-
|
| 75 |
-
|
| 76 |
-
|
| 77 |
-
|
| 78 |
-
|
| 79 |
-
|
| 80 |
-
|
|
|
|
|
|
|
|
|
| 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 |
-
- `
|
| 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 `
|
| 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\
|
| 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
|
| 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"))
|