docs: fix 36 docstring quality gate failures across 17 files

- Fix missing_param_type, missing_return_type, param_type_mismatch,
  return_type_mismatch, no_args, no_returns, and missing docstring issues
- Add TYPE_CHECKING imports for HuggingFace types in util.py with
  type: ignore[union-attr] for pre-existing None-safety gaps
- Add Granite3ChatCompletion import to granite32/33 input.py for
  correct sanitize() parent signature match
- Convert reST-style docstrings to Google style in intrinsics/input.py
- Document AST single-quote normalization for Literal types in
  CONTRIBUTING.md

Author: planetf1

cli/alora/intrinsic_uploader.py

@@ -40,7 +40,7 @@ def upload_intrinsic(
         base_model (str): Base model ID or path (e.g.
             ``"ibm-granite/granite-3.3-2b-instruct"``). Must contain at most
             one ``"/"`` separator.
-        type (Literal["lora", "alora"]): Adapter type, used as the leaf
+        type (Literal['lora', 'alora']): Adapter type, used as the leaf
             directory name in the repository layout.
         io_yaml (str): Path to the ``io.yaml`` configuration file for
             intrinsic input/output processing.

cli/alora/train.py

@@ -16,7 +16,14 @@
 import typer
 from datasets import Dataset
 from peft import LoraConfig, get_peft_model
-from transformers import AutoModelForCausalLM, AutoTokenizer, TrainerCallback
+from transformers import (
+    AutoModelForCausalLM,
+    AutoTokenizer,
+    TrainerCallback,
+    TrainerControl,
+    TrainerState,
+    TrainingArguments,
+)
 from trl import DataCollatorForCompletionOnlyLM, SFTConfig, SFTTrainer
 
 # Handle MPS with old PyTorch versions on macOS only
@@ -39,7 +46,9 @@
             )
 
 
-def load_dataset_from_json(json_path, tokenizer, invocation_prompt):
+def load_dataset_from_json(
+    json_path: str, tokenizer: AutoTokenizer, invocation_prompt: str
+) -> Dataset:
     """Load a JSONL dataset and format it for SFT training.
 
     Reads ``item``/``label`` pairs from a JSONL file and builds a HuggingFace
@@ -73,7 +82,7 @@ def load_dataset_from_json(json_path, tokenizer, invocation_prompt):
     return Dataset.from_dict({"input": inputs, "target": targets})
 
 
-def formatting_prompts_func(example):
+def formatting_prompts_func(example: dict) -> list[str]:
     """Concatenate input and target columns for SFT prompt formatting.
 
     Args:
@@ -101,7 +110,13 @@ class SaveBestModelCallback(TrainerCallback):
     def __init__(self):
         self.best_eval_loss = float("inf")
 
-    def on_evaluate(self, args, state, control, **kwargs):
+    def on_evaluate(
+        self,
+        args: TrainingArguments,
+        state: TrainerState,
+        control: TrainerControl,
+        **kwargs,
+    ):
         """Save the adapter weights if the current evaluation loss is a new best.
 
         Called automatically by the HuggingFace Trainer after each evaluation

cli/decompose/decompose.py

@@ -49,6 +49,19 @@ class DecompVersion(StrEnum):
 def reorder_subtasks(
     subtasks: list[DecompSubtasksResult],
 ) -> list[DecompSubtasksResult]:
+    """Topologically sort subtasks by their ``depends_on`` relationships.
+
+    Args:
+        subtasks: List of subtask dicts, each with a ``"tag"`` and optional
+            ``"depends_on"`` field.
+
+    Returns:
+        list[DecompSubtasksResult]: The subtasks reordered so that dependencies
+        come before dependents, with numbering prefixes updated.
+
+    Raises:
+        ValueError: If a circular dependency is detected.
+    """
     subtask_map = {subtask["tag"].lower(): subtask for subtask in subtasks}
 
     graph = {}
@@ -78,6 +91,19 @@ def reorder_subtasks(
 def verify_user_variables(
     decomp_data: DecompPipelineResult, input_var: list[str] | None
 ) -> DecompPipelineResult:
+    """Validate that all required input variables and dependencies exist.
+
+    Args:
+        decomp_data: The decomposition pipeline result containing subtasks.
+        input_var: User-provided input variable names, or ``None`` for none.
+
+    Returns:
+        DecompPipelineResult: The (possibly reordered) decomposition data.
+
+    Raises:
+        ValueError: If a subtask requires an input variable that was not
+            provided, or depends on a subtask tag that does not exist.
+    """
     if input_var is None:
         input_var = []
 

cli/eval/runner.py

@@ -49,7 +49,7 @@ def __init__(
         self.score = score
         self.validation_reason = validation_reason
 
-    def to_dict(self):
+    def to_dict(self) -> dict:
         """Serialise the input evaluation result to a plain dictionary.
 
         Returns:
@@ -84,7 +84,7 @@ def __init__(self, test_eval: TestBasedEval, input_results: list[InputEvalResult
         self.test_eval = test_eval
         self.input_results = input_results
 
-    def to_dict(self):
+    def to_dict(self) -> dict:
         """Serialise the test evaluation result to a plain dictionary.
 
         Returns:
@@ -366,7 +366,7 @@ def execute_test_eval(
     return test_result
 
 
-def parse_judge_output(judge_output: str):
+def parse_judge_output(judge_output: str) -> tuple[int | None, str]:
     """Parse score and justification from a judge model's output string.
 
     Args:

docs/docs/guide/CONTRIBUTING.md

@@ -391,7 +391,7 @@ in the table below, follow the fix instructions, and re-push.
 | `no_raises` | Function source contains `raise` but the docstring has no `Raises:` section | Add a `Raises:` section listing each exception type and the condition that triggers it |
 | `missing_param_type` | `Args:` section exists but one or more parameters have no Python type annotation — the type column is absent from the generated API docs | Add a type annotation to each listed parameter in the function signature (e.g. `def f(x: int)`). Only fires when `no_args` is already satisfied; `*args`/`**kwargs` are excluded. |
 | `missing_return_type` | `Returns:` section is documented but the function has no return type annotation — the return type is absent from the generated API docs | Add a return annotation to the function signature (e.g. `-> str`). Only fires when `no_returns` is already satisfied. |
-| `param_type_mismatch` | A parameter's `Args:` entry states an explicit type (e.g. `x (int): …`) that does not match the Python annotation in the function signature | Align the docstring type with the annotation, or vice versa. The check normalises common equivalents (`Optional[X]` ↔ `X \| None`, `List` ↔ `list`, union ordering) before comparing, so only genuine disagreements are flagged. Only fires when both the docstring and the signature have an explicit type. |
+| `param_type_mismatch` | A parameter's `Args:` entry states an explicit type (e.g. `x (int): …`) that does not match the Python annotation in the function signature | Align the docstring type with the annotation, or vice versa. The check normalises common equivalents (`Optional[X]` ↔ `X \| None`, `List` ↔ `list`, union ordering) before comparing, so only genuine disagreements are flagged. Only fires when both the docstring and the signature have an explicit type. **Note:** Python's AST normalises string literals to single quotes, so `Literal["a", "b"]` in source is read as `Literal['a', 'b']` — use single quotes in docstrings to match. |
 | `return_type_mismatch` | The `Returns:` section has a type prefix (e.g. `Returns: \n    str: …`) that does not match the Python return annotation | Align the docstring return type with the annotation, or vice versa. Same normalisation rules as `param_type_mismatch`. Only fires when both sides have an explicit type. |
 
 #### Class docstrings (Option C)

mellea/backends/tools.py

@@ -70,7 +70,7 @@ def as_json_tool(self) -> dict[str, Any]:
         return self._as_json_tool.copy()
 
     @classmethod
-    def from_langchain(cls, tool: Any):
+    def from_langchain(cls, tool: Any) -> "MelleaTool":
         """Create a MelleaTool from a LangChain tool object.
 
         Args:
@@ -117,7 +117,7 @@ def parameter_remapper(*args, **kwargs):
             ) from e
 
     @classmethod
-    def from_smolagents(cls, tool: Any):
+    def from_smolagents(cls, tool: Any) -> "MelleaTool":
         """Create a Tool from a HuggingFace smolagents tool object.
 
         Args:
@@ -172,7 +172,7 @@ def tool_call(*args, **kwargs):
             ) from e
 
     @classmethod
-    def from_callable(cls, func: Callable, name: str | None = None):
+    def from_callable(cls, func: Callable, name: str | None = None) -> "MelleaTool":
         """Create a MelleaTool from a plain Python callable.
 
         Introspects the callable's signature and docstring to build an
@@ -379,7 +379,7 @@ def json_extraction(text: str) -> Generator[dict, None, None]:
         index = text.find("{", index)
 
 
-def find_func(d) -> tuple[str | None, Mapping | None]:
+def find_func(d: object) -> tuple[str | None, Mapping | None]:
     """Find the first function in a json-like dictionary.
 
     Most llms output tool requests in the form ``...{"name": string, "arguments": {}}...``

mellea/core/sampling.py

@@ -133,5 +133,5 @@ async def sample(
             tool_calls: True if tool calls should be used during this sampling strategy.
 
         Returns:
-            SamplingResult: A result object indicating the success or failure of the sampling process.
+            SamplingResult[S]: A result object indicating the success or failure of the sampling process.
         """

mellea/core/utils.py

@@ -67,14 +67,18 @@ class JsonFormatter(logging.Formatter):
     process ID, thread ID, and (if present) exception information.
     """
 
-    def format(self, record):  # type: ignore
+    def format(self, record: logging.LogRecord) -> dict:  # type: ignore[override]
         """Formats a log record as a JSON-serialisable dictionary.
 
         Includes timestamp, level, message, module, function name, line number,
         process ID, thread ID, and exception info if present.
 
         Args:
             record (logging.LogRecord): The log record to format.
+
+        Returns:
+            dict: A dictionary containing timestamp, level, message, module, function,
+            line number, process/thread IDs, and optional exception info.
         """
         log_record = {
             "timestamp": self.formatTime(record, self.datefmt),

mellea/formatters/granite/base/util.py

@@ -3,17 +3,23 @@
 """Common utility functions for the library and tests."""
 
 # Standard
+from __future__ import annotations
+
 import contextlib
 import itertools
 import json
 import logging
 import os
 import re
 import uuid
+from typing import TYPE_CHECKING
 
 # Third Party
 import pydantic
 
+if TYPE_CHECKING:
+    from transformers import PreTrainedModel, PreTrainedTokenizerBase
+
 # First Party
 from .types import ChatCompletionResponse, ChatCompletionResponseChoice
 
@@ -98,7 +104,7 @@ def random_uuid() -> str:
     return str(uuid.uuid4())
 
 
-def load_transformers_lora(local_or_remote_path):
+def load_transformers_lora(local_or_remote_path: str) -> tuple:
     """Load transformers LoRA model.
 
     AutoModelForCausalLM.from_pretrained() is supposed to auto-load base models if you
@@ -136,7 +142,10 @@ def load_transformers_lora(local_or_remote_path):
 
 
 def chat_completion_request_to_transformers_inputs(
-    request, tokenizer=None, model=None, constrained_decoding_prefix=None
+    request: dict,
+    tokenizer: PreTrainedTokenizerBase | None = None,
+    model: PreTrainedModel | None = None,
+    constrained_decoding_prefix: str | None = None,
 ) -> tuple[dict, dict]:
     """Translate an OpenAI-style chat completion request.
 
@@ -191,7 +200,7 @@ def chat_completion_request_to_transformers_inputs(
     ):
         tokenizer_input["documents"] = request["extra_body"]["documents"]
 
-    input_tokens = tokenizer.apply_chat_template(**tokenizer_input, return_tensors="pt")
+    input_tokens = tokenizer.apply_chat_template(**tokenizer_input, return_tensors="pt")  # type: ignore[union-attr]
 
     # Transformers 5 switched the return type of apply_chat_template() from Tensor to
     # BatchEncoding. Adjust our behavior depending on which direction the currently
@@ -208,17 +217,17 @@ def chat_completion_request_to_transformers_inputs(
 
     # generate() will fail with many different creative error messages if tokens aren't
     # on the right device.
-    input_tokens = input_tokens.to(model.device)
+    input_tokens = input_tokens.to(model.device)  # type: ignore[union-attr]
     generate_input["input_tokens"] = input_tokens
 
     # The generate() method sometimes needs to know what is the integer ID
     # of the padding token, and for some reason this critical piece of information
     # isn't included in the serialized model. We get it from the tokenizer.
     # And of course some tokenizers don't set this parameter, in which case
     # we use the end of string token and hope for the best.
-    pad_token_id = tokenizer.pad_token_id
+    pad_token_id = tokenizer.pad_token_id  # type: ignore[union-attr]
     if pad_token_id is None:
-        pad_token_id = tokenizer.eos_token_id
+        pad_token_id = tokenizer.eos_token_id  # type: ignore[union-attr]
     if pad_token_id is None:
         # Raise an error here because the some branches of the generate
         # method won't complain about an invalid value of this parameter,
@@ -229,7 +238,7 @@ def chat_completion_request_to_transformers_inputs(
 
     # Make sure you specify this parameter explicitly, or you will have
     # a bad time.
-    generate_input["eos_token_id"] = tokenizer.eos_token_id
+    generate_input["eos_token_id"] = tokenizer.eos_token_id  # type: ignore[union-attr]
 
     other_input = {}
 
@@ -316,7 +325,10 @@ def chat_completion_request_to_transformers_inputs(
 
 
 def generate_with_transformers(
-    tokenizer, model, generate_input: dict, other_input: dict
+    tokenizer: PreTrainedTokenizerBase,
+    model: PreTrainedModel,
+    generate_input: dict,
+    other_input: dict,
 ) -> ChatCompletionResponse:
     """Call Transformers generate and get usable results.
 

mellea/formatters/granite/granite3/granite32/input.py

@@ -13,6 +13,7 @@
     NO_TOOLS_NO_DOCS_NO_THINKING_SYSTEM_MESSAGE_PART,
 )
 from ...granite3.input import Granite3InputProcessor
+from ...granite3.types import Granite3ChatCompletion
 
 # Local
 from .constants import (
@@ -221,12 +222,14 @@ def _remove_special_tokens(cls, text: str) -> str:
         return new_text
 
     @classmethod
-    def sanitize(cls, chat_completion, parts="all"):
+    def sanitize(
+        cls, chat_completion: Granite3ChatCompletion, parts: list[str] | str = "all"
+    ) -> Granite3ChatCompletion:
         """Sanitize the chat completion by removing Granite 3.2 special tokens.
 
         Args:
             chat_completion: The chat completion request to sanitize.
-            parts (str): Which parts of the chat completion to sanitize;
+            parts (list[str] | str): Which parts of the chat completion to sanitize;
                 defaults to ``"all"``.
 
         Returns: