From 4e689d057fd5e1d8078fb6a0c2a31a31880cc2c9 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 16 Aug 2026 06:33:29 +0000 Subject: [PATCH] Lean PyPI install: graphier setup fetches the engine, no ML downloads MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 'pip install graphier' previously declared semantica as a hard dependency — whose own dependency list pulls torch/transformers/spacy (multi-gigabyte) that Graphier's deterministic path never imports. - dependencies are now the lean set Graphier actually uses (fastapi, uvicorn, pypdf, python-multipart, numpy, pandas, scipy, networkx); semantica moves to the optional [ml] extra. - New graphier.cli entry points: 'graphier setup' installs the engine package alone (pip install --no-deps semantica); launching without it prints the one command to run instead of a traceback. graphier-mcp gets the same guard. - Release workflow gains a publish-pypi job using PyPI trusted publishing (OIDC, no token) — gated on the PYPI_PUBLISH repo variable and documented step-by-step in docs/launch-checklist.md. - README gains the pip quick start; CHANGELOG updated. - 4 new tests (55 total). Co-Authored-By: Claude Claude-Session: https://claude.ai/code/session_01QVbxD1gd3gsC6zXKE6L3ya --- .github/workflows/release.yml | 28 ++++++++++++++--- CHANGELOG.md | 6 ++++ README.md | 7 +++++ backend/graphier/cli.py | 58 +++++++++++++++++++++++++++++++++++ backend/pyproject.toml | 15 +++++++-- backend/tests/test_cli.py | 33 ++++++++++++++++++++ docs/launch-checklist.md | 6 ++++ 7 files changed, 145 insertions(+), 8 deletions(-) create mode 100644 backend/graphier/cli.py create mode 100644 backend/tests/test_cli.py diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 008486e..d53085c 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -34,8 +34,26 @@ jobs: with: files: dist/* generate_release_notes: true - # To publish on PyPI, add a PYPI_API_TOKEN secret and uncomment: - # - name: Publish to PyPI - # run: | - # pip install twine - # twine upload -u __token__ -p "${{ secrets.PYPI_API_TOKEN }}" dist/* + - name: Upload dist for PyPI job + uses: actions/upload-artifact@v4 + with: + name: dist + path: dist/ + + # Publishes to PyPI via trusted publishing (no token/secret needed). + # One-time setup on pypi.org: Account → Publishing → add a "pending + # publisher" for Joshuaakaspace/Graphier, workflow release.yml, + # environment pypi. Then set the repo variable PYPI_PUBLISH to "true". + publish-pypi: + needs: build + if: vars.PYPI_PUBLISH == 'true' + runs-on: ubuntu-latest + environment: pypi + permissions: + id-token: write + steps: + - uses: actions/download-artifact@v4 + with: + name: dist + path: dist/ + - uses: pypa/gh-action-pypi-publish@release/v1 diff --git a/CHANGELOG.md b/CHANGELOG.md index 8e3d7d6..60dc95c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,12 @@ ## Unreleased +- Lean PyPI install: `pip install graphier` no longer drags in + multi-gigabyte ML dependencies; `graphier setup` fetches the extraction + engine with `--no-deps`, and a friendly message explains the one + command if it's missing. Release workflow gains PyPI trusted + publishing (no token needed). + - **MCP server** (`graphier-mcp`): the vault's knowledge graph queryable by Claude Code, Claude Desktop, Cursor, and any MCP client over stdio — nine tools (search, entity dossiers, relations, Datalog, conflicts, diff --git a/README.md b/README.md index 1ff66ec..366aaab 100644 --- a/README.md +++ b/README.md @@ -181,6 +181,13 @@ self-programmable vault — is Graphier. ## Run it +**pip** (once v0.1.0 is on PyPI): + +```bash +pip install graphier && graphier setup # setup fetches the extraction engine — no multi-GB ML downloads +GRAPHIER_VAULT=~/notes graphier --demo +``` + **Docker (one command, demo content included):** ```bash diff --git a/backend/graphier/cli.py b/backend/graphier/cli.py new file mode 100644 index 0000000..3efd0b6 --- /dev/null +++ b/backend/graphier/cli.py @@ -0,0 +1,58 @@ +"""Console entry points with a friendly engine bootstrap. + +`pip install graphier` deliberately does NOT pull the extraction engine: +Semantica's own dependency list includes torch/transformers/spacy +(multi-gigabyte), while Graphier's deterministic path needs none of it. +`graphier setup` installs just the engine package itself (~no ML +downloads); the scientific deps it does use are already Graphier +dependencies. +""" + +from __future__ import annotations + +import importlib.util +import subprocess +import sys + +MISSING_ENGINE = """\ +Graphier's extraction engine isn't installed yet. One command fixes it: + + graphier setup + +(This runs `pip install --no-deps semantica` — the engine package alone, +no multi-gigabyte ML downloads. For Semantica's optional ML extractors +later: `pip install semantica`.) +""" + + +def engine_installed() -> bool: + return importlib.util.find_spec("semantica") is not None + + +def install_engine() -> int: + return subprocess.call( + [sys.executable, "-m", "pip", "install", "--no-deps", "semantica"] + ) + + +def main() -> None: + if sys.argv[1:2] == ["setup"]: + code = install_engine() + if code == 0: + print("Engine installed. Start Graphier with: graphier --demo") + raise SystemExit(code) + if not engine_installed(): + print(MISSING_ENGINE, file=sys.stderr) + raise SystemExit(1) + from .main import main as run_app + + run_app() + + +def mcp_main() -> None: + if not engine_installed(): + print(MISSING_ENGINE, file=sys.stderr) + raise SystemExit(1) + from .mcp import main as run_mcp + + run_mcp() diff --git a/backend/pyproject.toml b/backend/pyproject.toml index 96f4c57..12e9273 100644 --- a/backend/pyproject.toml +++ b/backend/pyproject.toml @@ -13,12 +13,19 @@ classifiers = [ "Topic :: Office/Business :: Groupware", "Topic :: Text Processing :: Markup :: Markdown", ] +# Lean by design: the engine package (semantica) installs via `graphier +# setup` with --no-deps, because its own dependency list pulls torch/ +# transformers/spacy (multi-GB) that the deterministic path never uses. +# The scientific deps Graphier's path DOES use are declared here. dependencies = [ "fastapi>=0.110", "uvicorn[standard]>=0.29", - "semantica>=0.6.0", "pypdf>=4.0", "python-multipart>=0.0.9", + "numpy", + "pandas", + "scipy", + "networkx", ] [project.urls] @@ -28,10 +35,12 @@ Changelog = "https://github.com/Joshuaakaspace/Graphier/blob/main/CHANGELOG.md" [project.optional-dependencies] dev = ["pytest>=8.0", "httpx>=0.27"] +# Full Semantica including its ML extractors (large download): +ml = ["semantica>=0.6.0"] [project.scripts] -graphier = "graphier.main:main" -graphier-mcp = "graphier.mcp:main" +graphier = "graphier.cli:main" +graphier-mcp = "graphier.cli:mcp_main" [build-system] requires = ["setuptools>=68"] diff --git a/backend/tests/test_cli.py b/backend/tests/test_cli.py new file mode 100644 index 0000000..7f17212 --- /dev/null +++ b/backend/tests/test_cli.py @@ -0,0 +1,33 @@ +import pytest + +from graphier import cli + + +def test_engine_detected_in_dev_environment(): + assert cli.engine_installed() is True + + +def test_missing_engine_message_and_exit(monkeypatch, capsys): + monkeypatch.setattr(cli, "engine_installed", lambda: False) + with pytest.raises(SystemExit) as exc: + cli.main() + assert exc.value.code == 1 + err = capsys.readouterr().err + assert "graphier setup" in err and "--no-deps" in err + + +def test_setup_invokes_lean_pip_install(monkeypatch): + calls = [] + monkeypatch.setattr(cli.subprocess, "call", lambda cmd: calls.append(cmd) or 0) + monkeypatch.setattr(cli.sys, "argv", ["graphier", "setup"]) + with pytest.raises(SystemExit) as exc: + cli.main() + assert exc.value.code == 0 + assert calls and "--no-deps" in calls[0] and "semantica" in calls[0] + + +def test_mcp_guard(monkeypatch, capsys): + monkeypatch.setattr(cli, "engine_installed", lambda: False) + with pytest.raises(SystemExit): + cli.mcp_main() + assert "graphier setup" in capsys.readouterr().err diff --git a/docs/launch-checklist.md b/docs/launch-checklist.md index b0ef3d3..22d02ee 100644 --- a/docs/launch-checklist.md +++ b/docs/launch-checklist.md @@ -12,6 +12,12 @@ CONTRIBUTING, ROADMAP, templates). What remains needs the repo owner. - [ ] Social preview image: upload `docs/graph-view.png` - [ ] Enable **Discussions** - [ ] Tag `v0.1.0` (the release workflow builds and attaches the wheel) +- [ ] PyPI (optional but recommended): create a pypi.org account → + Publishing → add a *pending publisher* for `Joshuaakaspace/Graphier`, + workflow `release.yml`, environment `pypi` → set the GitHub repo + **variable** `PYPI_PUBLISH=true` → re-tag or re-run the release + workflow. No token/secret needed (trusted publishing). After that, + `pip install graphier` works for everyone. ## Seed issues (copy, adjust, post — label the first four `good first issue`)