Skip to content

docs: add architecture decision records page - #349

Closed
stanlrt wants to merge 24 commits into
mainfrom
340-text-input-modality
Closed

stanlrt wants to merge 24 commits into
mainfrom
340-text-input-modality

Conversation

@stanlrt

@stanlrt stanlrt commented Jul 6, 2026

Copy link
Copy Markdown
Collaborator

What

Adds docs/contributor/adr.md — a decision log of RAITAP's durable design choices, wired into the contributor toctree.

Ten records, each with the same fixed structure (Context / Options / Decision / Consequences):

Sourced from contributor docs, code comments, and accumulated design notes.

Verification

Strict Sphinx build green:

uv run --frozen sphinx-build -b html -n -W --keep-going docs docs/_build/html
# build succeeded.

🤖 Generated with Claude Code

stanlrt added 24 commits July 5, 2026 20:24
…iner, LayerIG token reduction, batch panels) (refs #340)
Copilot AI review requested due to automatic review settings July 6, 2026 14:40

supported_modalities: frozenset[InputModality]

def parse(self, *, source: str) -> list[str]: ...
if TYPE_CHECKING:
from collections.abc import Callable

from raitap.data.input_parsers.base import InputParser

from __future__ import annotations

from typing import Any, ClassVar, cast
import pytest

if TYPE_CHECKING:
from raitap.configs.schema import AppConfig

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Breaking change: Yes — the backend interface is widened to support forward kwargs (ModelBackend.__call__(..., **kwargs)), which can impact custom/third-party backends that don’t accept keyword arguments.

Warning

The PR contains breaking changes, but the title does not contain "!". Please mark it as breaking by adding "!" after the type or scope (e.g. feat!: or feat(api)!:).

This PR goes well beyond adding the new contributor ADR page: it introduces an end-to-end text input modality (HuggingFace sequence-classification + tokenizer, input-parser registry, attention-mask threading into forward pass and Captum attribution) and updates docs/CI/deps accordingly.

Changes:

  • Add contributor ADR documentation and wire it into the contributor docs toctree.
  • Add text modality support end-to-end: data/inputs parser registry, tokenisation to (input_ids, attention_mask), forward-pass kwarg threading, Captum text attribution handling, and batched token visualisation support.
  • Introduce a new optional dependency extra (text) and update CI/package smoke workflows to install it.

Reviewed changes

Copilot reviewed 65 out of 66 changed files in this pull request and generated 3 comments.

Show a summary per file
File Description
uv.lock Adds text extra dependency set and locks new packages (transformers stack).
pyproject.toml Defines new text extra (transformers>=4.40).
.github/workflows/package-smoke.yml Includes text extra in wheel smoke installs.
.github/workflows/code-quality.yaml Installs --extra text in quality/pytest jobs.
src/raitap/models/base_backend.py Backend __call__ now accepts **kwargs; relaxes predict_callable typing.
src/raitap/models/torch_backend.py Forwards kwargs to torch models; adds load_hf_text_backend() + tokenizer attribute.
src/raitap/models/model.py Loads HF text backend when model.tokenizer is set.
src/raitap/models/onnx_backend.py Updates signature to accept **kwargs (ignored).
src/raitap/models/tree_backend.py Updates signature to accept **kwargs (ignored).
src/raitap/models/tests/test_backend.py Updates test backend signature to accept **kwargs.
src/raitap/models/tests/test_backend_kwargs.py New test asserting kwargs reach torch forward.
src/raitap/models/tests/test_hf_text_backend.py New test for HF text backend forwarding ids + mask.
src/raitap/data/types.py Adds InputModality.text and text extensions.
src/raitap/data/metadata.py Infers kind=text, layout=TOKENS for text modality.
src/raitap/data/data.py Adds text load branch: input parser -> tokenise -> store attention_mask.
src/raitap/data/_parser_factory.py New shared _target_ resolve + instantiate helper for parser families.
src/raitap/data/label_parsers/factory.py Refactors label parser factory to use shared parser factory.
src/raitap/data/input_parsers/base.py New InputParser protocol.
src/raitap/data/input_parsers/registration.py New @input_parser decorator / family registration.
src/raitap/data/input_parsers/factory.py New input-parser instantiation factory.
src/raitap/data/input_parsers/init.py Imports built-in input parsers to trigger registration.
src/raitap/data/input_parsers/text_csv.py Adds CSV/TSV/Parquet text-column parser.
src/raitap/data/input_parsers/text_jsonl.py Adds JSONL text-field parser.
src/raitap/data/input_parsers/text_dir.py Adds directory-of-text-files parser.
src/raitap/data/tests/test_types.py Updates modality enum tests for new text member.
src/raitap/data/tests/test_text_metadata.py New test for text metadata inference.
src/raitap/data/tests/test_text_input_parsers.py New tests for text input parsers.
src/raitap/data/tests/test_load_text.py New test for tokeniser output (input_ids, attention_mask).
src/raitap/data/tests/test_input_parser_registry.py New registry + Hydra compose coverage for data/inputs.
src/raitap/configs/schema.py Adds ModelConfig.tokenizer and DataConfig.inputs + inputs config schemas.
src/raitap/configs/zen.py Ensures input-parsers package is imported for config registration.
src/raitap/deps/inference.py Adds backend_extras() to infer both torch runtime and text extra when needed.
src/raitap/deps/tests/test_inference.py Adds tests for text extra inference based on model.tokenizer.
src/raitap/task_families/base.py Adds ATTENTION_MASK_KEY constant (used for threading mask).
src/raitap/task_families/classification.py Threads attention_mask through forward and explain paths; refactors batching.
src/raitap/task_families/tests/test_classification_forward_mask.py New regression test for forward-pass mask threading.
src/raitap/pipeline/phases/forward_pass.py Adds forward_kwargs plumbed into ForwardContext.extras.
src/raitap/pipeline/phases/tests/test_forward_pass.py Updates backend mock signature for new kwargs.
src/raitap/pipeline/orchestrator.py Passes attention_mask into forward_pass() when present.
src/raitap/pipeline/tests/test_text_classification_e2e.py New (skippable) e2e test for text-classification config.
src/raitap/transparency/explainers/captum_explainer.py Moves attention_mask into additional_forward_args; wraps text forward to logits; reduces (B,T,H)->(B,T).
src/raitap/transparency/semantics.py Gives text token attribution precedence over generic layer-space tagging.
src/raitap/transparency/visualisers/captum_visualisers.py Accepts 2-D token attributions; renders batched panels; validates token layout via TensorLayout.
src/raitap/transparency/visualisers/tests/test_visualisers.py Updates/adds tests for batched token attribution rendering and validation.
src/raitap/transparency/tests/test_captum_text_attribution.py New tests for Captum invoker mask handling + LayerIG mechanism.
src/raitap/transparency/tests/test_factory.py Updates test backend signature to accept **kwargs.
src/raitap/transparency/tests/test_assess_transparency_detection.py Updates routing test backend signature to accept **kwargs.
src/raitap/robustness/tests/test_factory.py Updates test backend signature to accept **kwargs.
src/raitap/robustness/tests/test_e2e_statistical_sampling.py Updates test backend signature to accept **kwargs.
src/raitap/robustness/tests/test_e2e_robustness_matrix.py Updates test backend signature to accept **kwargs.
src/raitap/robustness/tests/test_e2e_real_data.py Updates test backend signature to accept **kwargs.
docs/contributor/index.md Adds adr to contributor toctree.
docs/contributor/adr.md Adds ADR page content.
docs/contributor/architecture.md Updates architecture overview to mention text in data module.
docs/contributor/modules/data.md Documents text modality behavior and the data/inputs registry seam.
docs/contributor/adding/index.md Adds “adding an input parser” entry.
docs/contributor/adding/adding-an-input-parser.md New contributor guide for input parsers.
docs/contributor/adding/adding-a-task-family.md Updates data-layer boundary section to reflect text support.
docs/modules/data/configuration.md Documents data.inputs variants and how to configure them.
docs/modules/data/own-vs-built-in.md Adds user-facing guidance for text inputs.
docs/modules/model/configuration.md Documents model.tokenizer option and HF text config example.
docs/modules/model/own-vs-built-in.md Adds HF hub-id + tokenizer support to model source docs.
docs/modules/transparency/visualisers.md Updates Captum text visualiser docs to allow batched attributions.
contributor-configs/text-classification-sst2/assessment.yaml Adds runnable text-classification config.
contributor-configs/text-classification-sst2/README.md Documents how to generate fixtures and run the text demo.
contributor-configs/text-classification-sst2/build_data.py Adds fixture generator for the SST-2 demo.

Comment thread src/raitap/data/data.py
Comment on lines +125 to +129
inputs_cfg = _get_optional_config_value(cfg.data, "inputs")
model_cfg_for_text = getattr(cfg, "model", None)
tokenizer_id = _get_optional_config_value(model_cfg_for_text, "tokenizer")
if inputs_cfg is not None and tokenizer_id is not None:
try:
Comment on lines +99 to +103
found: dict[str, str] = {}
_add(found, backend_extra(source, hardware), f"model.source={source} + hardware={hardware}")
tokenizer = model.get("tokenizer")
if tokenizer is not None:
_add(found, "text", f"model.tokenizer={tokenizer!r}")
Comment on lines +660 to +662
attributions: Per-token attribution scores. Either 1-D ``(T,)`` for a
single sequence, or 2-D ``(B, T)`` for a batch (one panel per row).
Higher-rank tensors are rejected.
@stanlrt

stanlrt commented Jul 6, 2026

Copy link
Copy Markdown
Collaborator Author

Superseded by a clean docs-only branch (this branch was the squash-merged #340 branch, so the PR re-proposed already-merged code).

@stanlrt stanlrt closed this Jul 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants