Installation

ThesisAgents targets Python 3.12+ on Windows, macOS, and Linux. This page covers every supported install path; pick the one that matches how you plan to use the project.

Install paths at a glance

Use case	Command	Pulls in
CLI only	`pip install thesisagents`	The 10-package core runtime — enough to search and emit `.pptx` / `.xlsx` / `.bib`.
CLI + MCP server	`pip install "thesisagents[mcp]"`	Adds the `mcp` SDK so `thesisagents-mcp` works.
CLI + PDF + LLM enrichment	`pip install "thesisagents[intelligence]"`	Adds `pypdf` + `pymupdf` + `anthropic` for the `--enrich` flow.
CLI + desktop GUI	`pip install "thesisagents[gui]"`	Adds PySide6 for `thesisagents-gui` / `thesisagents gui`.
Everything	`pip install "thesisagents[intelligence,mcp,gui]"`	All three extras.
Developer / contributor	`pip install -e ".[dev]"` from a clone	Full toolchain — pytest, pytest-asyncio, pytest-httpx, pytest-qt, ruff, bandit + every runtime extra.

The published distribution name on PyPI is thesisagents. The console scripts installed are thesisagents (CLI), thesisagents-mcp (MCP server), thesisagents-gui (desktop UI).

Supported runtimes

Component	Version
Python	3.12, 3.13, 3.14 (CI runs against all three)
Operating system	Windows 10/11, macOS 13+, Ubuntu 22.04+ / Debian 12+ / any modern Linux
Architecture	x86_64 on all OSes; arm64 on macOS (Apple Silicon) and Linux

Python 3.12 is the floor because the project uses PEP 695 type syntax, structural pattern matching, and httpx’s 3.12-only async helpers. Earlier Pythons would need a from __future__ and backport gymnastics that we chose not to take on.

The full dependency surface

Core (`pip install thesisagents`)

These come with every install. None has a heavy native step:

httpx >= 0.27               # async HTTP client
pydantic >= 2.7             # data models
pydantic-settings >= 2.3    # env-var loading
defusedxml >= 0.7           # secure XML parsing
python-pptx >= 0.6.23       # .pptx generation
openpyxl >= 3.1             # .xlsx generation
bibtexparser >= 1.4         # .bib round-trips
beautifulsoup4 >= 4.12      # HTML parsing for scrape fallbacks
lxml >= 5.2                 # parser backend for bs4 + python-pptx
markdown-it-py >= 3.0       # markdown export

lxml is the only one with a native compile step; pip serves a prebuilt wheel for every supported platform.

`[intelligence]` extra

pypdf >= 4.0                # text extraction from downloaded PDFs
pymupdf >= 1.24             # higher-fidelity PDF text extraction
anthropic >= 0.40           # Anthropic API client for --enrich

pymupdf carries a sizable native MuPDF dependency (~30 MB installed). Prebuilt wheels are available on PyPI for Windows / macOS / manylinux; on a very old Linux distro you may need to install MuPDF dev headers and let pip build from source.

`[mcp]` extra

mcp >= 1.2                  # Anthropic's MCP server SDK

Pure Python. Only needed if you actually run the MCP server.

`[gui]` extra

PySide6 >= 6.7              # Qt 6 Python bindings

PySide6 carries the Qt 6 runtime (~80 MB installed). Prebuilt wheels cover every supported platform. The wheel includes Qt’s QML, multimedia, charts, network, and SVG modules even though the current GUI only uses QtWidgets — sized for forward compat with the Deck-editor tab.

`[dev]` extra

Everything above plus:

pytest >= 8.2
pytest-asyncio >= 0.23
pytest-httpx >= 0.30
pytest-qt >= 4.4
ruff >= 0.5
bandit >= 1.7

Recommended local setup

A project-local virtualenv is strongly recommended so the install doesn’t pollute the system Python:

Windows (PowerShell)

git clone https://github.com/Integration-Automation/ThesisAgents.git
cd ThesisAgents

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -e ".[dev]"

# Sanity-check
python -m thesisagents --version
python -m pytest tests/

macOS / Linux (bash / zsh)

git clone https://github.com/Integration-Automation/ThesisAgents.git
cd ThesisAgents

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e ".[dev]"

python -m thesisagents --version
python -m pytest tests/

After installation, the activated venv exposes three console scripts: thesisagents (CLI), thesisagents-mcp (MCP server), thesisagents-gui (desktop UI). All three also work as python -m invocations:

python -m thesisagents ...
python -m thesisagents.mcp
python -m thesisagents.gui.app

Linux: extra system packages for the GUI

PySide6’s wheels link to a handful of system libraries that some minimal Linux images don’t preinstall. On Debian / Ubuntu:

sudo apt-get install -y \
    libegl1 libgl1 \
    libxkbcommon0 libxkbcommon-x11-0 \
    libdbus-1-3 \
    libxcb-cursor0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 \
    libxcb-randr0 libxcb-render-util0 libxcb-shape0 libxcb-xinerama0 \
    libxcb-xkb1 libfontconfig1

Without these, importing PySide6.QtGui fails with libEGL.so.1: cannot open shared object file and pytest-qt crashes during pytest_configure (before any test runs).

On a headless Linux box (CI, server) the GUI still imports if you set QT_QPA_PLATFORM=offscreen — Qt renders into an in-memory buffer instead of an X server.

Windows: prebuilt `.exe`

Every release ships a self-contained Windows zip built with Nuitka. Download thesisagents-windows-x86_64.zip from the GitHub Releases page, unzip anywhere, and run thesisagents.exe directly. The bundle includes Python, every dependency (including PySide6), and the 11 source plugins — no separate Python install is needed.

The bundle entry point is python -m thesisagents, so all the same CLI flags work:

.\thesisagents.exe --query "diffusion models" --max 10 --out .\exports\
.\thesisagents.exe --paper "https://arxiv.org/abs/1706.03762" --out .\exports\
.\thesisagents.exe gui     # opens the desktop UI

A .sha256 companion is attached to every release for integrity checking.

Installing from a pre-release / development branch

# From a Git ref directly
pip install "git+https://github.com/Integration-Automation/ThesisAgents@dev"

# From a local clone (editable — picks up your changes live)
pip install -e .

The editable install is the recommended developer setup because it points the import path at your working copy, so source changes take effect on the next import without a reinstall.

Verifying an install

thesisagents --version       # prints package version + Python info
thesisagents --help          # full CLI flag list
python -c "import thesisagents; print(thesisagents.__file__)"

If the MCP extra is installed:

python -c "from thesisagents.mcp import build_server; import asyncio; \
    print(sorted(t.name for t in asyncio.run(build_server().list_tools())))"

You should see all twelve tool names: list_sources, list_exports, search, fetch_paper, fetch_pdf_text, download_pdfs, export, pptx_inspect, pptx_update_slide, pptx_delete_slide, pptx_reorder_slides, pptx_add_slide.

If the GUI extra is installed:

thesisagents gui             # opens the window
# or: python -m thesisagents.gui.app

Uninstall

pip uninstall thesisagents

Saved API keys / cookies-file paths live in your platform’s QSettings store and are not removed by pip uninstall. To clear them too:

Windows: HKEY_CURRENT_USER\Software\ThesisAgents\ThesisAgents
macOS: ~/Library/Preferences/com.ThesisAgents.ThesisAgents.plist
Linux: ~/.config/ThesisAgents/ThesisAgents.conf

Common install failures

error: Microsoft Visual C++ 14.0 or greater is required (Windows)

A dependency tried to build from source because pip couldn’t find a matching prebuilt wheel. Make sure you’re on Python 3.12, 3.13, or 3.14 — that covers every wheel published. If you’re on a prerelease Python, downgrade or install the MSVC C++ Build Tools.

No matching distribution found for thesisagents

pip is older than pip install needs to resolve a project with [project] metadata. Upgrade:

python -m pip install --upgrade pip

error: setuptools needs to be at least version 68

Same root cause as above. The pip install --upgrade pip line also pulls in a recent setuptools.

ImportError: libEGL.so.1 (Linux GUI)

Install the system packages listed in the “Linux: extra system packages for the GUI” section above.

OSError: [Errno 28] No space left on device during pip install

The cumulative install with [dev] is roughly 700 MB (PySide6 + pymupdf + lxml + Anthropic SDK are the heaviest items). Make sure the venv path has enough disk free.