build: add 'notebooks' optional-dependency extra; harden empty-key test

- pyproject: [project.optional-dependencies].notebooks = matplotlib/seaborn/
  networkx/numpy/jupyter/ipykernel so the example notebooks run via
  'pip install vynco[notebooks]' or 'uv run --extra notebooks ...'.
- notebooks/README: document the extra + the Professional-tier requirement.
- test_empty_api_key_raises_config_error: delenv VYNCO_API_KEY so it stays
  hermetic when the key is exported for the live suite.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mivertowski

CHANGELOG.md

@@ -72,6 +72,10 @@ Tooling:
 
 - Reproducible route-gap diff at `scripts/api_gap.py`.
 - Opt-in live smoke suite (`uv run pytest -m live`, gated on `VYNCO_API_KEY`).
+- All `examples/` are now tier-resilient (`examples/_common.py`): a section whose
+  endpoint the key's tier doesn't unlock is skipped with a note instead of crashing.
+- `notebooks` optional-dependency extra (`pip install "vynco[notebooks]"`) bundling
+  matplotlib/seaborn/networkx/numpy/jupyter for the example notebooks.
 
 ### Fixed
 

notebooks/README.md

@@ -4,18 +4,26 @@ Jupyter notebooks that produce publication-ready charts from the VynCo API. Ever
 
 ## Setup
 
+The charting/runtime dependencies are bundled in the `notebooks` extra:
+
 ```bash
-pip install vynco matplotlib seaborn networkx jupyter
+pip install "vynco[notebooks]"        # or: uv sync --extra notebooks
 export VYNCO_API_KEY=vc_live_your_api_key
-jupyter lab
+jupyter lab                            # or: uv run --extra notebooks jupyter lab
 ```
 
 Or execute headlessly:
 
 ```bash
 jupyter nbconvert --to notebook --execute notebooks/<name>.ipynb --output <name>.ipynb
+# with uv:
+uv run --extra notebooks jupyter nbconvert --to notebook --execute notebooks/<name>.ipynb --output <name>.ipynb
 ```
 
+> Most notebooks call analytics, AI, and methodology endpoints, so they need a
+> **Professional** (or higher) API key to run end-to-end; on a lower tier those
+> cells return `ForbiddenError`.
+
 ## Notebooks
 
 ### [swiss_market_analytics.ipynb](swiss_market_analytics.ipynb) — Market landscape

pyproject.toml

@@ -21,6 +21,18 @@ dependencies = [
     "pydantic>=2.0",
 ]
 
+[project.optional-dependencies]
+# Charting/runtime deps for the example notebooks under notebooks/.
+# Install with:  pip install "vynco[notebooks]"   (or  uv sync --extra notebooks)
+notebooks = [
+    "matplotlib>=3.7",
+    "seaborn>=0.13",
+    "networkx>=3.0",
+    "numpy>=1.24",
+    "jupyter>=1.0",
+    "ipykernel>=6.0",
+]
+
 [project.urls]
 Homepage = "https://github.com/VynCorp/vc-python"
 Documentation = "https://docs.vynco.ch"

tests/test_client.py

@@ -16,7 +16,10 @@
 # ---------------------------------------------------------------------------
 
 
-def test_empty_api_key_raises_config_error():
+def test_empty_api_key_raises_config_error(monkeypatch):
+    # An empty key falls back to the env var, so null it to keep this hermetic
+    # even when VYNCO_API_KEY is exported (e.g. for the live suite).
+    monkeypatch.delenv("VYNCO_API_KEY", raising=False)
     with pytest.raises(vynco.ConfigError, match="empty"):
         vynco.Client("")