Profiles & Environment¶
Chapter 02 of the ResearchTools manual. Back to table of contents.
Profiles¶
A domain profile centralizes everything domain-specific (Scopus subject areas and
exclusions, topical-relevance signals, off-topic flag, stats profile, author, course
context, language) in one YAML file under profiles/, so the agents and skills stay
shared across users and labs: one maintained core, N profiles.
| Profile | Domain | Author | Default |
|---|---|---|---|
engineering.yaml |
Mechanical / electrical / ML / control / systems engineering | Martin Otis (UQAC) | yes |
cosmetic.yaml |
Cosmetic / formulation science (SPF, microbiome, dermatology, sensory) | Lionel Ripoll (UQAC) | no |
_template.yaml |
Copy it to profiles/<domain>.yaml to add a new domain |
- | - |
The active profile is recorded in .claude/CLAUDE.md as the machine-readable line
active_profile: <name>. Select it at install time (.\install.ps1 -Profile <name>, or
the interactive prompt) or edit that line directly. Currently wired consumer:
scopus-researcher (search clauses, Step 3a relevance check, synthesis framework); the
remaining fields (author, stats_profile, course_context, language) are schema-ready
and will be wired incrementally. Field-by-field spec, fallback rules, and the add-a-profile
procedure: profiles/README.md.
Environment variables / API keys¶
Set these at the Windows User scope (PowerShell), then restart Claude Code:
[System.Environment]::SetEnvironmentVariable('SCOPUS_API_KEY', 'your-key', 'User')
| Variable / source | Required for | Where to get it |
|---|---|---|
SCOPUS_API_KEY |
Required — all /scopus, /auditreview, /auditpaper, /auditthesis, /litreview, /litupdate, /bibclean, /replyreviewer, and PDF retrieval |
Elsevier Developer Portal |
.scopus_key file |
Fallback for SCOPUS_API_KEY — place the key in .claude/skills/scopus/.scopus_key (gitignored) |
same key as above |
UNPAYWALL_EMAIL |
Optional — enables the Unpaywall open-access tier in download_pdf.py (HTML/PDF fallback when no publisher PDF); a plain contact email, or pass --email |
any institutional email |
ELSEVIER_INSTTOKEN |
Optional — the Elsevier institutional token sent with every Elsevier full-text and metadata call when --insttoken is absent (the flag wins). Without it, a closed-access paper returns a one-page preview from this key even on the UQAC VPN (measured 2026-11-05), so the chain falls through to the browser rung. The token itself is issued to the institution by Elsevier |
UQAC library, who request it from Elsevier |
BW_SESSION, KEEPASSXC_DATABASE, KEEPASSXC_PASSWORD (or KEEPASSXC_KEYFILE) |
Optional — only for the browser rung's institutional sign-in, and only for the chosen secret_provider in browser-fetch.json: the Bitwarden session key printed by bw unlock, or the KeePassXC database path and its master password. The host's user name is read from the variable its username_env entry names. None of them is ever logged |
bw unlock, your own KeePassXC database |
GEMINI_API_KEY |
Optional — the Gemini leg of the deliberation panel (cross-review, table enrichment). The model is resolved at run time from Google's own catalogue (--gemini-model auto), so no model name is set here |
Google AI Studio |
COPILOT_TOKEN or GH_OAUTH_TOKEN |
Optional — the GitHub Copilot leg of the deliberation panel. GH_OAUTH_TOKEN is exchanged automatically for a Copilot token. Without either, the panel uses a local Ollama model declared for the session role as the second voice, and without that too the leg is skipped without stopping the pipeline |
your GitHub account with Copilot |
GITHUB_TOKEN |
Legacy — Copilot refuses a personal access token and GitHub Models was retired on 2026-07-30, so this variable no longer gives a cross-review leg. It is still the last attempt of the provider chain | GitHub → Settings → Developer settings |
S2_API_KEY (or SEMANTIC_SCHOLAR_API_KEY) |
Optional — Semantic Scholar author/PDF backfill and keyword search; without it the throttled public pool is used, where a search can be refused (429) and exits 1 | Semantic Scholar API key request |
--insttoken (CLI flag, not an env var) |
Optional — off-campus Elsevier access when not on the UQAC network/VPN | UQAC library / Elsevier institutional token |
An on-campus network connection or active UQAC VPN is required for Scopus access unless an
--insttokenis supplied. Secrets are kept out of git:.env,secrets/, andcredentials/are listed in.gitignore.
Other variables¶
| Variable | Used by | Meaning |
|---|---|---|
OBSIDIAN_VAULT |
the vault hooks, the vault daemon, local-writer |
Root of your Obsidian vault. setup.ps1 offers to set it at user scope when it is unset and never replaces an existing value |
PROFESSOR_EXPERTISE_DATA |
professor-expertise-finder |
Folder holding the location tables and batch registries. Default ~/workspace/professor-expertise |
AUGUREAI_API_KEY |
claude-augure in scripts/local/claude-switch.ps1 |
Key sent as ANTHROPIC_API_KEY when a session is routed through AugureAI, see chapter 03 |
FORM_SERVICE_KEY, FORM_SERVICE_HOST |
deploy/form-service/ |
Shared secret and public host name of the PDF-form API, see chapter 17 |
WP_NONCE, WP_COOKIES, WP_BASE |
wp-portfolio-sync |
WordPress cookie authentication, its cookie file and the site address, for the one-time portfolio migration |
RT_PG_PASSWORD |
rt_store.py of the dashboard |
Password of the optional PostgreSQL identity layer, read only when observe-config.json declares a postgres block |
RT_OO_USER, RT_OO_PASSWORD |
rt_openobserve.py of the dashboard |
Credentials of the optional OpenObserve trace stream, read only when an openobserve block is declared |
CORPUS_INDEX_DSN |
the optional corpus index of extract-statistic |
Connection string of a PostgreSQL database with pgvector. Without it the four tests that need a live database are skipped |
The Ollama settings (OLLAMA_KEEP_ALIVE and others) are not API keys and belong to the user
registry, not to Claude Code's env block, see chapter 01.
Python environments: every library¶
A skill that imports a library nobody declared works on the machine that happens to have it and
fails on every other one, so this section lists every third-party library the repository's Python
code needs, one row per library and per environment. The repository has three environments, all
built in the main clone by .\setup.ps1 -InstallPython from one data file,
scripts/lib/rt-python-requirements.json:
.venv-skills, for the skills, the hooks' tests and the offline suite;.venv-docs, for this site;.venv-pdf2md, for thepdf2mdconversion.
The three are independent, so a library used in two of them has a row in each table with its own pin.
The tables below are generated, not written by hand. scripts/docs/python_libs.py reads the data
file, every requirements file it names, and the import statements of every .py file under
.claude/skills, .claude/hooks and scripts, then fills the tables between the
python-libs marker comments of this page. How to read them:
- ☑ in the first column means a requirements file declares the library. ☐ means the code imports
it and no file declares it, which
python_libs.py --checkreports as an error. - "Pin" is the version the requirements files fix, not a version measured on a machine.
python_libs.py --driftcompares it with what an environment holds. - "Optional" means the import is guarded (inside
tryor a function) or the requirements line says so. - The notes, licences included, come from
scripts/docs/python-libs-notes.json. - Programs that are not pip packages (pandoc, Poppler, MiKTeX, Ollama, Node.js) are in the Prerequisites table of chapter 01.
.venv-skills¶
The interpreter every skill script, hook test and launcher uses. It holds fourteen requirements
files (every skill file except pdf2md's) plus pip-audit, which audits the requirements files of
all three environments after the install.
| Declared | Library | Import | Pin | Declared in | Used by | Optional | Note |
|---|---|---|---|---|---|---|---|
| ☑ | claude-agent-sdk |
claude_agent_sdk | 0.2.172 | loop-engineer ==0.2.172 |
loop-engineer | yes | only the live loop path of loop_engineer.py |
| ☑ | cryptography |
cryptography | 50.0.2 | form-service ==50.0.2 |
form-service | yes | |
| ☑ | curl_cffi |
curl_cffi | 0.15.0 | scopus ==0.15.0 |
scopus | yes | |
| ☑ | defusedxml |
defusedxml | 0.7.1 | paper2talk ==0.7.1; drawio2tikz ==0.7.1; wp-portfolio-sync ==0.7.1 |
drawio2tikz, paper2talk, wp-portfolio-sync | yes | |
| ☑ | docling |
docling | 2.142.0 | extract-statistic ==2.142.0 |
extract-statistic | yes | MIT licence; pulls torch and downloads layout models on first run |
| ☑ | faster-whisper |
faster_whisper | 1.2.1 | opt-local-stt-vram ==1.2.1; rt-observe ==1.2.1 |
opt-local-stt-vram, rt-observe | yes | pulls ctranslate2 |
| ☑ | folium |
folium | 0.20.0 | geolocalisation ==0.20.0 |
geolocalisation | yes | |
| ☑ | google-genai |
2.8.0 | scopus ==2.8.0 |
scopus | yes | imported as google.genai | |
| ☑ | Jinja2 |
jinja2 | 3.1.6 | paper2talk ==3.1.6 |
paper2talk | yes | |
| ☑ | keyring |
keyring | 25.7.0 | scopus ==25.7.0 |
scopus | yes | |
| ☑ | lxml |
lxml | 6.1.3 | word2latex ==6.1.3 |
word2latex | ||
| ☑ | markitdown |
markitdown | 0.1.6 | extract-statistic [pdf]==0.1.6 |
extract-statistic | yes | MIT licence |
| ☑ | MarkupSafe |
markupsafe | 3.0.3 | paper2talk ==3.0.3 |
paper2talk | yes | a dependency of Jinja2, imported directly by talk_model.py |
| ☑ | matplotlib |
matplotlib | 3.9.2 | geolocalisation ==3.9.2 |
geolocalisation | yes | |
| ☑ | numpy |
numpy | 2.4.6 | word2latex ==2.4.6 |
aider-setup, word2latex | yes | aider-setup also imports it, in aider's own interpreter |
| ☑ | nvidia-cublas-cu12 |
(none) | 12.9.2.10 | rt-observe ==12.9.2.10 |
- | yes | never imported: stt_engine.py puts its DLL folder on PATH for GPU speech-to-text; Windows and Linux only |
| ☑ | nvidia-cuda-nvrtc-cu12 |
(none) | 12.9.86 | rt-observe ==12.9.86 |
- | yes | same, Windows and Linux only |
| ☑ | nvidia-cudnn-cu12 |
(none) | 9.26.0.51 | rt-observe ==9.26.0.51 |
- | yes | same, Windows and Linux only |
| ☑ | openai |
openai | 2.43.0 | scopus ==2.43.0 |
scopus | yes | |
| ☑ | openpyxl |
openpyxl | 3.1.5 | professor-expertise-finder ==3.1.5 |
professor-expertise-finder | yes | only for .xlsx and .xlsm input |
| ☑ | pgvector |
(none) | 0.5.0 | extract-statistic ==0.5.0 |
- | yes | no .py file imports it: the vector store is SQL |
| ☑ | pillow |
PIL | 13.0.0 | extract-statistic ==13.0.0; geolocalisation ==13.0.0; word2latex ==13.0.0 |
word2latex | yes | also pinned where it is only transitive, to keep the fixed version |
| ☑ | pip-audit |
(none) | 2.10.1 | data file tools ==2.10.1 |
- | run as a module (python -m pip_audit), never imported | |
| ☑ | playwright |
playwright | 1.61.0 | scopus ==1.61.0 |
scopus | yes | the Chromium binary is a separate playwright install chromium |
| ☑ | psycopg |
psycopg | 3.3.6 | extract-statistic [binary]==3.3.6; rt-observe [binary]==3.3.6 |
extract-statistic, rt-observe | yes | |
| ☑ | pyHanko |
pyhanko | 0.37.0 | form-service ==0.37.0 |
form-service | MIT licence | |
| ☑ | PyMuPDF |
fitz, pymupdf | 1.27.2.3 | paper2talk ==1.27.2.3; extract-statistic ==1.27.2.3; word2latex ==1.27.2.3; work-ugs-audit ==1.27.2.3; figure-review ==1.27.2.3 |
extract-statistic, figure-review, geolocalisation, paper2talk, scopus, word2latex, work-ugs-audit | yes | AGPL-3.0 licence; scopus uses it when present without declaring it |
| ☑ | pymupdf4llm |
pymupdf4llm | 1.27.2.3 | extract-statistic ==1.27.2.3; work-ugs-audit ==1.27.2.3 |
extract-statistic, work-ugs-audit | yes | AGPL-3.0 licence |
| ☑ | pypdf |
pypdf | 6.21.2 | paper2talk ==6.21.2; form-service ==6.21.2; narrative-cv ==6.21.2 |
form-service, narrative-cv, paper2talk | ||
| ☑ | python-docx |
docx | 1.2.0 | word2latex ==1.2.0 |
word2latex | yes | word2latex test fixtures only (test_docx_track.py); docx_track.py itself edits the XML with lxml |
| ☑ | python-pptx |
pptx | 1.0.2 | paper2talk ==1.0.2 |
paper2talk | yes | |
| ☑ | PyYAML |
yaml | 6.0.3 | recommendation-letter ==6.0.3; narrative-cv ==6.0.3; wp-portfolio-sync ==6.0.3; work-ugs-audit ==6.0.3 |
narrative-cv, recommendation-letter, work-ugs-audit, wp-portfolio-sync | read with yaml.safe_load only | |
| ☑ | requests |
requests | 2.34.2 | scopus ==2.34.2; extract-statistic ==2.34.2; form-service ==2.34.2; wp-portfolio-sync ==2.34.2 |
extract-statistic, form-service, scopus, wp-portfolio-sync | ||
| ☑ | tiktoken |
tiktoken | 0.14.0 | loop-engineer ==0.14.0 |
aider-setup, loop-engineer | yes | aider-setup also uses the copy in aider's own interpreter |
.venv-docs¶
The interpreter that builds this site (see chapter 16). It holds
requirements-docs.txt, every line pinned, transitive dependencies included. The site needs
mkdocs and mkdocs-material (the theme), pymdown-extensions and Markdown (the extensions
listed in mkdocs.yml: attr_list, md_in_html, tables, toc, pymdownx.superfences,
pymdownx.highlight and pymdownx.slugs), ghp-import (the gh-deploy command), Pygments and
PyYAML. Those are direct in the Role column, and every other line is transitive. The build
hook scripts/docs/mkdocs_hooks.py uses the standard library only. Eleven lines that nothing in
this environment required were removed on 2026-10-22. A .venv-docs built before that date still
holds them until it is deleted and rebuilt.
| Declared | Library | Pin | Role | Note |
|---|---|---|---|---|
| ☑ | babel |
2.18.0 | transitive | |
| ☑ | backrefs |
8.0 | transitive | |
| ☑ | certifi |
2026.10.19 | transitive | |
| ☑ | charset-normalizer |
3.5.1 | transitive | |
| ☑ | click |
8.5.0 | transitive | |
| ☑ | colorama |
0.4.6 | transitive | |
| ☑ | ghp-import |
2.1.0 | direct | |
| ☑ | idna |
3.20 | transitive | |
| ☑ | Jinja2 |
3.1.6 | transitive | |
| ☑ | Markdown |
3.11 | direct | |
| ☑ | MarkupSafe |
3.0.3 | transitive | a dependency of Jinja2, imported directly by talk_model.py |
| ☑ | mergedeep |
1.3.4 | transitive | |
| ☑ | mkdocs |
1.6.1 | direct | |
| ☑ | mkdocs-get-deps |
0.2.2 | transitive | |
| ☑ | mkdocs-material |
9.7.7 | direct | |
| ☑ | mkdocs-material-extensions |
1.3.1 | transitive | |
| ☑ | packaging |
26.3 | transitive | |
| ☑ | paginate |
0.5.7 | transitive | |
| ☑ | pathspec |
1.1.1 | transitive | |
| ☑ | platformdirs |
4.12.0 | transitive | |
| ☑ | Pygments |
2.21.0 | direct | |
| ☑ | pymdown-extensions |
12.1 | direct | |
| ☑ | python-dateutil |
2.9.0.post0 | transitive | |
| ☑ | PyYAML |
6.0.3 | direct | read with yaml.safe_load only |
| ☑ | pyyaml_env_tag |
1.1 | transitive | |
| ☑ | requests |
2.34.2 | transitive | |
| ☑ | six |
1.17.0 | transitive | |
| ☑ | urllib3 |
2.8.0 | transitive | |
| ☑ | watchdog |
6.0.0 | transitive |
.venv-pdf2md¶
The interpreter of the pdf2md conversion (mineru, mineru-llama-cpp). It is kept apart from
.venv-skills by the owner's decision of 2026-10-22: mineru 4.0.11 needs gradio, every
gradio up to 6.30.0 caps pillow below 13.0.0, and 13.0.0 is the version that clears the
advisories of pillow 12.3.0 in .venv-skills. This environment therefore keeps pillow 12, with
its advisories accepted and recorded in IMPROVEMENTS.md.
| Declared | Library | Import | Pin | Declared in | Used by | Optional | Note |
|---|---|---|---|---|---|---|---|
| ☑ | mineru |
(none) | 4.0.11 | pdf2md ==4.0.11 |
- | used through the mineru-kit command | |
| ☑ | mineru-llama-cpp |
mineru_llama_cpp | 0.1.2 | pdf2md ==0.1.2 |
pdf2md | yes | the VLM server binary mineru starts |
| ☑ | PyMuPDF |
fitz, pymupdf | 1.27.2.3 | pdf2md ==1.27.2.3 |
pdf2md | AGPL-3.0 licence; scopus uses it when present without declaring it | |
| ☑ | pymupdf4llm |
pymupdf4llm | 1.27.2.3 | pdf2md ==1.27.2.3 |
- | yes | AGPL-3.0 licence |
| ☑ | PyYAML |
yaml | 6.0.3 | pdf2md ==6.0.3 |
pdf2md | read with yaml.safe_load only |
The form service¶
deploy/form-service/ has its own environment, %LOCALAPPDATA%\ResearchTools\venv-form-service,
which setup.ps1 does not build. It is described by deploy/form-service/requirements.txt:
fastapi==0.141.1, uvicorn==0.54.0, pypdf==6.21.2, pyHanko==0.37.0, cryptography==50.0.2
and requests==2.34.2. Its pins of the libraries it shares with the form-service skill are the
same, and verify-python-env.ps1 checks that. The service tests run in that environment, not in
.venv-skills.
Keeping these tables true¶
A change that adds an import of a new third-party library also adds its line to the skill's
requirements file, with an exact version checked by pip-audit (chapter 16).
A new requirements file is also named in scripts/lib/rt-python-requirements.json. Then, with
the .venv-skills interpreter:
python scripts\docs\python_libs.py --write # regenerate the tables of this page
python scripts\docs\python_libs.py --check # exit 1 on an omission or a stale table
python scripts\docs\python_libs.py --drift # compare the pins with what each environment holds
scripts\test\verify-python-libs.ps1, run by run-all-checks.ps1, fails when --check does. An
import the notes file cannot map to a distribution is reported too, and a new entry in
scripts/docs/python-libs-notes.json fixes it.
← 01 Installation | Table of contents | 03 Token management →