docs(examples): standardize adapter, granite-switch, aLoRA, and SOFAI examples by rafvasq · Pull Request #1765 · generative-computing/mellea

rafvasq · 2026-10-27T15:12:12Z

Pull Request

Issue

Towards #1746

Description

Standardizes intrinsics/, granite-switch/, aLora/, and sofai/, keeping the original docstring and README wording and adding structure.

Docstrings

Added docstrings to scripts that had none
Added Prerequisites: and Usage: blocks

READMEs

Each is now a short description with links to the matching site docs, and includes an ## Examples table, using the original per-file descriptions where they were accurate.
Removed content was checked against docs like advanced/intrinsics.md, advanced/lora-and-alora-adapters.md, and advanced/inference-time-scaling.md. Content that isn't covered wasn't removed: the Granite Switch overview, the architecture diagram, and the SOFAI flow diagram.
Kept the train/upload/add-readme workflow in aLora/ since no script contains it.

Other fixes

Fixed the architecture diagram links in intrinsics/ and granite-switch/. The image moved to docs/static/images/ in docs: migrate from Mintlify to Docusaurus 3 #1174.
In aLora/README.md:
- Fixed the clone URL (missing https://) and quoted ".[all]" so it works in zsh.
- Added the missing \ in the --hints command.
- Added the huggingface-cli login prerequisite.
- Updated "(Adaptive)" to "(Activated)" Low-Rank Adapters.
sofai/README.md used parameter names that don't exist (s1_backend, escalate_on_failure). I removed them along with the code sample.
Added # pytest: huggingface, e2e to query_rewrite.py, which had no marker.

Testing

Tests added to the respective file if code was changed
New code has 100% coverage if code was added
Ensure existing tests and github automation passes (a maintainer will kick off the github automation when the rest of the PR is populated)

Attribution

AI coding assistants used

Adding a new component, requirement, sampling strategy, or tool?

If your PR adds or modifies one of the types below, check the matching box. A checklist of type-specific review items will be posted as a comment.

Component
Requirement
Sampling Strategy
Tool

NOTE: Please ensure you have an issue that has been acknowledged by a core contributor and routed you to open a pull request against this repository. Otherwise, please open an issue before continuing with this pull request.

… examples Towards generative-computing#1746. Standardize header docstrings (description, Prerequisites, Usage) across intrinsics/, granite-switch/, aLora/, and sofai/. Reduce intri nsics/, granite-switch/, and sofai/ READMEs to a description plus an Examples table, linking to the site docs for concepts. Keep the aLoRA train/upload/add- readme workflow in its README since no script covers it. Assisted-by: IBM Bob Signed-off-by: Rafael Vasquez <rafvasq21@gmail.com>

…n example_readme_generator Signed-off-by: Rafael Vasquez <rafvasq21@gmail.com> Assisted-by: IBM Bob

ajbozarth · 2026-10-30T22:59:48Z

cc @planetf1 as you wrote pretty much all of these

planetf1

Thanks for doing this, the new structure and Examples tables are a clear improvement. I'm requesting changes because a few of the docs now say things that aren't true when you run them. The details are inline. The aLora/102_example.py failure was already there on main, so I've opened #1790 for it, and #1791 covers the upload error. The changed .py files differ from base only in their docstrings, and CI is green. Thanks for the cc @ajbozarth.

planetf1 · 2026-11-05T08:03:55Z

+Uploading requires a Hugging Face account; run `huggingface-cli login` first, or
+`m alora upload` and `m alora add-readme` fail with "Hugging Face token not found".


I ran m alora upload with no token and it never says "Hugging Face token not found". It exits with ImportError: The 'm alora upload' command requires extra dependencies, even with all extras installed. cli/alora/upload.py:15 imports HfFolder, and huggingface_hub 1.16.1 (what uv.lock pins) no longer has it. The huggingface-cli login advice is fine, so I'd just drop the quoted error. The import itself is existing code, so I've opened #1791 for that.

Suggested change

Uploading requires a Hugging Face account; run `huggingface-cli login` first, or

`m alora upload` and `m alora add-readme` fail with "Hugging Face token not found".

Uploading requires a Hugging Face account; run `huggingface-cli login` first.

planetf1 · 2026-11-05T09:11:21Z

+using fast and slow models. For usage guidance and `s2_solver_mode`, see
+[Inference-time scaling](../../docs/advanced/inference-time-scaling.md#sofai--dual-model-escalation).
+The `SOFAISamplingStrategy` docstring in `mellea/stdlib/sampling/sofai.py` documents
+the remaining options, including `judge_backend` and `feedback_strategy`.


The old README had a short section saying what simple, first_error and all_errors mean for feedback_strategy. The docstring this now points to only lists the three values, and I couldn't find them in inference-time-scaling.md either, so that explanation has gone from the docs. A sentence or two on the three values in the SOFAI section of that page would cover it. They only matter when judge_backend is set, which is probably worth saying too.

Added a section to docs/docs/advanced/inference-time-scaling.md to capture this.

planetf1 · 2026-11-05T09:16:37Z

+`mfuncs.act(Intrinsic(...))`. The raw JSON output
+(`{"requirement_check": {"score": ...}}`) is printed; `ALoraRequirement` parses
+the same output when validating. Prefer the helper functions for everyday use;
+see `mellea/stdlib/components/intrinsic/` for them.


Nit: this docstring has the right path (mellea/stdlib/components/intrinsic/), but line 39 still says mellea/stdlib/intrinsics/rag.py, which doesn't exist. It was there before this PR, but since you're in the file anyway it's a cheap fix:

# This is an example for how you would directly use intrinsics. See `mellea/stdlib/components/intrinsic/rag.py`

planetf1 · 2026-11-05T09:17:22Z

+`{"item": ..., "label": "<json string>"}` — the format `m alora train` expects (see
+`stembolt_failure_dataset.jsonl`). Output goes to stdout unless `-o` is given.
+
+Usage:


Nit: the trailing \ sits inside a regular (non-raw) docstring, so Python treats it as a line continuation and joins the two lines. ast.get_docstring gives you the command on one line with a stretch of spaces before the file name. It's cosmetic, since it only shows in help() or generated docs, but making it r""" or putting the command on one line avoids it.

Used r""" here and in a couple of others too where the command is long.

planetf1 · 2026-11-05T09:23:44Z

 ```bash
-git clone github.com/generative-computing/mellea;
+git clone https://github.com/generative-computing/mellea;
 cd mellea;


why are there ; at the end of each line in this section?

Seems they were there previously, removed now

planetf1 · 2026-11-05T09:51:04Z

+Compose the adapter from an `Identity`, an output contract, and a `LocalFileBinding`,
+then register it on a `LocalHFBackend` with `backend.add_adapter()`. The code is in
+[LoRA and aLoRA adapters](../../docs/advanced/lora-and-alora-adapters.md), and
+`stembolts_intrinsic.py` is a complete, runnable version with the `stembolts` adapter;


This says stembolts_intrinsic.py is "a complete, runnable version", but the file has no entry point, and the example that uses it (102_example.py) doesn't work at the moment. I ran it with two notes piped in and it stops with AloraActivationError: aLoRA 'stembolts' ... never activates for this call. That happens on current main too, so it isn't from this PR.

The cause is io.yaml. It has no instruction: line, so the <|start_of_role|>check_requirement<|end_of_role|> tokens the aLoRA needs never reach the prompt. The copy in this directory is identical to the one on nfulton/stembolts, and m alora train defaults to that same invocation string. With the instruction: line added to a copy of io.yaml, the example ran and returned a diagnosis. Since 102 is skip-marked, CI never runs it.

For this PR, could the sentence just say it's the helper 102_example.py imports, rather than a runnable version? I've opened #1790 for the real fix (the instruction: line here, plus the HF repo).

Updated the description here.

planetf1 · 2026-11-05T10:07:54Z

+| [`101_example.py`](./101_example.py) | Comparing aLoRA-backed requirement validation against LLM-as-a-judge, using the catalog-native `requirement-check` adapter (not a custom one — see `stembolts_intrinsic.py` for loading your own). |
+| [`102_example.py`](./102_example.py) | Interactive loop that exercises the custom `stembolts` adapter — skip-marked because it blocks on stdin in an infinite loop. |
+| [`stembolts_intrinsic.py`](./stembolts_intrinsic.py) | Helper module for loading and calling the fully custom `stembolts` adapter (no standalone entry point — `102_example.py` consumes it). |
+| [`make_training_data.py`](./make_training_data.py) | Utility for preparing training datasets for adapter training. |


Nit: the old README listed "Data validation" for this script, and that is worth keeping in the description. It checks each label against a JSON schema (so it needs jsonschema installed) and stops with an error on a row that doesn't match, which "Utility for preparing training datasets" doesn't tell you.

Updated the description.

planetf1 · 2026-11-05T10:11:50Z

+Ollama can retain one model identity (mapped through `adapter_models`). Unless
+`MELLEA_OLLAMA_UNCERTAINTY_MODEL` names an existing tag, the script builds one by
+running `test/scripts/build_ollama_uncertainty_adapter.sh` (needs `git`, `uv`, and
+network access to download the base model and adapter). If the build fails, the


This example can't succeed on current Ollama, and the docstring doesn't say so. Ollama removed adapter creation in v0.34.1. I ran the build script on 0.40.14 and it fails with Error: LoRA adapters are no longer supported, after which the script prints "SKIPPED" and exits 0. "If the build fails..." reads like an edge case, but for anyone starting from scratch it is the only outcome, and the same is true for the section in advanced/intrinsics.md that points readers here. Because it exits 0, the examples runner reports it as passed, not skipped, so CI shows green without exercising anything.

I think this should be marked as deprecated rather than left as a fallback. Something like this at the top of the docstring:

Deprecated: Ollama no longer supports building LoRA/aLoRA adapter models (v0.34.1 and later), so this example cannot run on current Ollama. See #1633.

I'd leave removal itself (the build script, the uncertainty_adapter_model test fixture, the CI step, the intrinsics.md section) to #1633, since that touches tests and CI and the issue is still deciding between freezing and maintaining.

Added a deprecated line and pointed to #1633 here.

planetf1 · 2026-11-05T10:11:51Z

+| [`query_rewrite.py`](./query_rewrite.py) | Demonstrates rewriting queries for better retrieval. |
+| [`requirement_check.py`](./requirement_check.py) | Demonstrates validating requirements against model outputs. |
+| [`uncertainty.py`](./uncertainty.py) | Demonstrates assessing model certainty about its response. |
+| [`uncertainty_ollama.py`](./uncertainty_ollama.py) | `core.check_certainty()` on `OllamaModelBackend` using an Ollama model that bundles the uncertainty aLoRA. |


Related to my comment on uncertainty_ollama.py: this row presents the example as working. If the docstring gets a deprecation note, this row should say so too, e.g. "(deprecated: Ollama no longer supports building adapter models, see #1633)". I'd keep the row in the table rather than drop it, so the removal can be decided in #1633 and readers who find the file aren't left wondering why it isn't listed.

Added a deprecated line and pointed to #1633 here too.

Signed-off-by: Rafael Vasquez <rafvasq21@gmail.com> Assisted-by: IBM Bob

github-actions Bot added the documentation Improvements or additions to documentation label Oct 27, 2026

rafvasq force-pushed the docs/adapters-model-capabilities-standardize branch from 47f3c65 to f66eb4f Compare October 27, 2026 15:26

rafvasq marked this pull request as ready for review October 27, 2026 16:17

rafvasq requested a review from a team as a code owner October 27, 2026 16:17

rafvasq requested review from ajbozarth, jakelorocco and markstur October 27, 2026 16:17

rafvasq mentioned this pull request Oct 27, 2026

docs(examples): Standardize structure and content across docs/examples/ #1746

Open

docs(examples): remove inline comment from ollama pull prerequisite i…

6eb6f07

…n example_readme_generator Signed-off-by: Rafael Vasquez <rafvasq21@gmail.com> Assisted-by: IBM Bob

rafvasq force-pushed the docs/adapters-model-capabilities-standardize branch from 584f779 to 6eb6f07 Compare October 29, 2026 13:51

ajbozarth requested a review from planetf1 October 30, 2026 22:59

This was referenced Nov 5, 2026

docs(examples): aLora/102_example.py fails with AloraActivationError (stembolts io.yaml has no instruction) #1790

Open

fix(cli): m alora upload and add-readme fail with an ImportError on huggingface_hub 1.x (HfFolder removed) #1791

Open

planetf1 requested changes Nov 5, 2026

View reviewed changes

Address review comments

a897f61

Signed-off-by: Rafael Vasquez <rafvasq21@gmail.com> Assisted-by: IBM Bob

rafvasq requested a review from planetf1 November 5, 2026 18:51

		Uploading requires a Hugging Face account; run `huggingface-cli login` first, or
		`m alora upload` and `m alora add-readme` fail with "Hugging Face token not found".

Conversation

rafvasq commented Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request

Issue

Description

Testing

Attribution

Adding a new component, requirement, sampling strategy, or tool?

Uh oh!

ajbozarth commented Oct 30, 2026

Uh oh!

planetf1 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rafvasq commented Oct 27, 2026 •

edited

Loading