refactor: reorganize dependencies following PEP 735 (#588)

ajbozarth · web-flow · commit 833fececb82c · 2026-03-06T17:20:52.000Z
* refactor: reorganize dependencies following PEP 735 - Remove unused dependencies (json5, ansicolors) - Move type stubs to typecheck group (types-requests, types-tqdm) - Move server components to optional server group (uvicorn, fastapi) - Move llm-sandbox to optional sandbox group - Move huggingface-hub to hf optional group - Create granite_retriever optional group (elasticsearch, pyarrow, sentence-transformers) - Split dev group into modular groups (lint, test, typecheck, build, release) - Add dev group using PEP 735 include-group syntax - Move langchain-community and ddgs to test group - Add langchain-core to tools group - Update CONTRIBUTING.md installation instructions Closes #583 Signed-off-by: Alex Bozarth <ajbozart@us.ibm.com> * chore: align import errors with new optional dependencies Signed-off-by: Alex Bozarth <ajbozart@us.ibm.com> * feat: add backends dependency group Adds 'backends' extra for installing just backend dependencies (watsonx, hf, vllm, litellm) without additional features. Signed-off-by: Alex Bozarth <ajbozart@us.ibm.com> --------- Signed-off-by: Alex Bozarth <ajbozart@us.ibm.com>
diff --git a/AGENTS.md b/AGENTS.md
@@ -17,16 +17,17 @@ AGENTS.md — Instructions for AI coding assistants (Claude, Cursor, Copilot, Co
 - The virtual environment is `.venv/` — `uv run` automatically uses it
 
 ```bash
-pre-commit install                  # Required: install git hooks
-uv sync --all-extras --all-groups   # Install all deps (required for tests)
-ollama serve                        # Start Ollama (required for most tests)
-uv run pytest                       # Default: qualitative tests, skip slow tests
-uv run pytest -m "not qualitative"  # Fast tests only (~2 min)
-uv run pytest -m slow               # Run only slow tests (>5 min)
-uv run pytest --co -q               # Run ALL tests including slow (bypass config)
-uv run ruff format .                # Format code
-uv run ruff check .                 # Lint code
-uv run mypy .                       # Type check
+pre-commit install                    # Required: install git hooks
+uv sync --all-extras --all-groups     # Install all deps (required for tests)
+uv sync --extra backends --all-groups # Install just backend deps (lighter)
+ollama serve                          # Start Ollama (required for most tests)
+uv run pytest                         # Default: qualitative tests, skip slow tests
+uv run pytest -m "not qualitative"    # Fast tests only (~2 min)
+uv run pytest -m slow                 # Run only slow tests (>5 min)
+uv run pytest --co -q                 # Run ALL tests including slow (bypass config)
+uv run ruff format .                  # Format code
+uv run ruff check .                   # Lint code
+uv run mypy .                         # Type check
 ```
 **Branches**: `feat/topic`, `fix/issue-id`, `docs/topic`
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -58,14 +58,13 @@ to melleaadmin@ibm.com.
    source .venv/bin/activate  # On Windows: .venv\Scripts\activate
    ```
 
-3. **Install with all dependencies:**
+3. **Install dependencies:**
    ```bash
+   # Install all dependencies (recommended for development)
    uv sync --all-extras --all-groups
-   ```
-
-   Or for minimal development setup:
-   ```bash
-   uv pip install -e ".[all]" --group dev --group notebook --group docs
+   
+   # Or install just the backend dependencies
+   uv sync --extra backends --all-groups
    ```
 
 4. **Install pre-commit hooks (Required):**
diff --git a/mellea/backends/tools.py b/mellea/backends/tools.py
@@ -76,7 +76,7 @@ def parameter_remapper(*args, **kwargs):
         except ImportError as e:
             raise ImportError(
                 f"It appears you are attempting to utilize a langchain tool '{type(tool)}'. "
-                "Please install langchain core: uv pip install langchain-core"
+                "Please install mellea with tools support: pip install 'mellea[tools]'"
             ) from e
 
     @classmethod
@@ -131,7 +131,7 @@ def tool_call(*args, **kwargs):
         except ImportError as e:
             raise ImportError(
                 f"It appears you are attempting to utilize a smolagents tool '{type(tool)}'. "
-                "Please install mellea with smolagents support: uv pip install 'mellea[smolagents]'"
+                "Please install mellea with tools support: pip install 'mellea[tools]'"
             ) from e
 
     @classmethod
diff --git a/mellea/stdlib/tools/interpreter.py b/mellea/stdlib/tools/interpreter.py
@@ -203,7 +203,7 @@ def execute(self, code: str, timeout: int) -> ExecutionResult:
                 stdout=None,
                 stderr=None,
                 skipped=True,
-                skip_message="llm-sandbox not installed. Install with: uv add 'llm-sandbox[docker]'",
+                skip_message="llm-sandbox not installed. Install with: pip install 'mellea[sandbox]'",
             )
 
         try:
diff --git a/pyproject.toml b/pyproject.toml
@@ -29,33 +29,23 @@ dependencies = [
     "pydantic",
     "openai",
     "jinja2",
-    "json5",
     "ollama>=0.5.1",
-    "ansicolors",
     "requests>=2.32.3",
-    "uvicorn",
-    "fastapi",
-    "types-requests",
-    "types-tqdm",
     "typer",
     "click<8.2.0", # Newer versions will cause errors with --help in typer CLIs.
     "mistletoe>=1.4.0",
-    "huggingface-hub>=0.33.4",
     "pillow", # Needed for Intrinsics (HF and OpenAI Backends).
     "math_verify", # Needed for Majority Voting Sampling Strategies.
     "rouge_score", # Needed for Majority Voting Sampling Strategies.
-    "llm-sandbox[docker]>=0.3.23",
 ]
 
 [project.scripts]
 m = "cli.m:cli"
 
 [project.optional-dependencies]
-# Use these like:
-# uv pip install "mellea[hf]"
-# uv pip install -e ".[hf, watsonx]"
-# if you want to install all dependencies, use uv sync --all-extras
+# Install optional features: pip install "mellea[all]" or uv sync --all-extras
 
+# Backend integrations
 hf = [
     "accelerate>=1.9.0",
     "datasets>=4.0.0",
@@ -64,11 +54,12 @@ hf = [
     "transformers>=4.53.2,<5",
     "trl==0.19.1",
     "xgrammar", # Necessary for granite_common intrinsics.
+    "huggingface-hub>=0.33.4",
 ]
 
 vllm = [
     "vllm>=0.13.0; sys_platform != 'darwin'",
-    "numpy<=2.2",               # ImportError: Numba needs NumPy 2.2 or less. Got NumPy 2.4.
+    "numpy<=2.2", # ImportError: Numba needs NumPy 2.2 or less. Got NumPy 2.4.
 ]
 
 litellm = [
@@ -80,14 +71,10 @@ watsonx = [
     "ibm-watsonx-ai>=1.3.31",
 ]
 
-docling = [
-    "docling>=2.45.0",
-]
-
+# Feature integrations
 tools = [
     "smolagents>=1.0.0",
-    "langchain-community>=0.3.0",
-    "ddgs>=9.0.0",  # Required by DuckDuckGoSearchResults in langchain-community
+    "langchain-core>=1.2.7",
 ]
 
 telemetry = [
@@ -97,31 +84,79 @@ telemetry = [
     "opentelemetry-distro>=0.59b0",
 ]
 
-all = ["mellea[watsonx,docling,hf,vllm,litellm,tools,telemetry]"]
+docling = [
+    "docling>=2.45.0",
+]
+
+granite_retriever = [
+    "sentence-transformers",
+    "pyarrow",
+    "elasticsearch>=8.0.0,<9.0.0",
+]
+
+# Infrastructure
+server = [
+    "uvicorn",
+    "fastapi",
+]
+
+sandbox = [
+    "llm-sandbox[docker]>=0.3.23",
+]
+
+backends = ["mellea[watsonx,hf,vllm,litellm]"]
+
+all = ["mellea[backends,docling,tools,telemetry,server,sandbox,granite_retriever]"]
 
 [dependency-groups]
-# Use these like:
-# pip install -e . --group dev
-# pip install mellea --group dev
-dev = [
+# Development groups: uv sync --all-groups
+
+# Code quality
+lint = [
+    "ruff>=0.11.6",
     "isort>=6.0.0",
     "pre-commit>=4.2.0",
     "pylint>=3.3.4",
-    "ruff>=0.11.6",
-    "pdm>=2.24.0",
+]
+
+test = [
     "pytest",
     "pytest-asyncio",
     "pytest-cov>=6.0.0",
     "pytest-timeout",  # For test suite timeout configuration
     "psutil",  # For test infrastructure: RAM detection in conftest.py
+    "nbmake>=1.5.5",  # Notebook testing
+    "sentencepiece==0.2.1",  # Necessary for test_huggingface_tools test because of Mistral model
+    "jsonschema",
+    # Example-only dependencies (run via pytest)
+    "langchain-community>=0.3.0",
+    "ddgs>=9.0.0",  # Required by DuckDuckGoSearchResults in langchain-community
+]
+
+typecheck = [
     "mypy>=1.17.0",
+    "types-requests",
+    "types-tqdm",
+]
+
+build = [
+    "pdm>=2.24.0",
+]
+
+release = [
     "python-semantic-release~=7.32",
-    "nbmake>=1.5.5",
-    "langchain-core>=1.2.7", # Necessary for mypy and some tool tests
-    "sentencepiece==0.2.1", # Necessary for test_huggingface_tools test because of Mistral model
-    "jsonschema",
 ]
 
+# Convenience: includes all dev dependencies (used by default with uv run)
+dev = [
+    {include-group = "lint"},
+    {include-group = "test"},
+    {include-group = "typecheck"},
+    {include-group = "build"},
+    {include-group = "release"},
+]
+
+# Documentation and notebooks
 notebook = [
     "ipykernel>=6.29.5",
     "ipython>=8.36.0",
@@ -134,13 +169,6 @@ docs = [
     "sphinx_mdinclude",
 ]
 
-# Necessary for granite retriever.
-granite_common_retriever = [
-    "sentence-transformers",
-    "pyarrow",
-    "elasticsearch>=8.0.0,<9.0.0"
-]
-
 # -----------------------------
 # Ruff - Linting and Formatting
 # -----------------------------
diff --git a/uv.lock b/uv.lock

Original file line number	Diff line number	Diff line change
`@@ -203,7 +203,7 @@ def execute(self, code: str, timeout: int) -> ExecutionResult:`
`203`	`203`	`stdout=None,`
`204`	`204`	`stderr=None,`
`205`	`205`	`skipped=True,`
`206`		`- skip_message="llm-sandbox not installed. Install with: uv add 'llm-sandbox[docker]'",`
	`206`	`+ skip_message="llm-sandbox not installed. Install with: pip install 'mellea[sandbox]'",`
`207`	`207`	`)`
`208`	`208`
`209`	`209`	`try:`