docs: add metadata to code block (#917)

* add metadata to code block

Signed-off-by: Akihiko Kuroda <akihikokuroda2020@gmail.com>

* review comments

Signed-off-by: Akihiko Kuroda <akihikokuroda2020@gmail.com>

---------

Signed-off-by: Akihiko Kuroda <akihikokuroda2020@gmail.com>

Author: akihikokuroda

docs/docs/advanced/intrinsics.md

@@ -19,6 +19,8 @@ reliable than prompting a general-purpose model for these specialized micro-task
 Set up the backend once and reuse it across intrinsic calls:
 
 ```python
+# Requires: mellea[hf]
+# Returns: LocalHFBackend
 from mellea.backends.huggingface import LocalHFBackend
 
 backend = LocalHFBackend(model_id="ibm-granite/granite-4.0-micro")
@@ -29,6 +31,8 @@ backend = LocalHFBackend(model_id="ibm-granite/granite-4.0-micro")
 Check whether a set of retrieved documents can answer a given question:
 
 ```python
+# Requires: mellea[hf]
+# Returns: bool
 from mellea.backends.huggingface import LocalHFBackend
 from mellea.stdlib.components import Document, Message
 from mellea.stdlib.components.intrinsic import rag
@@ -50,6 +54,8 @@ print(rag.check_answerability(question, docs_not_answerable, context, backend))
 Assess whether a document is relevant to a question:
 
 ```python
+# Requires: mellea[hf]
+# Returns: float
 from mellea.backends.huggingface import LocalHFBackend
 from mellea.stdlib.components import Document
 from mellea.stdlib.components.intrinsic import rag
@@ -72,6 +78,8 @@ print(result)  # False — the document does not mention the CEO
 Flag sentences in an assistant response that are not grounded in the source documents:
 
 ```python
+# Requires: mellea[hf]
+# Returns: list[str]
 from mellea.backends.huggingface import LocalHFBackend
 from mellea.stdlib.components import Document, Message
 from mellea.stdlib.components.intrinsic import rag
@@ -99,6 +107,8 @@ print(result)
 Rewrite a vague or incomplete answer to be more grounded in the source documents:
 
 ```python
+# Requires: mellea[hf]
+# Returns: str
 from mellea.backends.huggingface import LocalHFBackend
 from mellea.stdlib.components import Document, Message
 from mellea.stdlib.components.intrinsic import rag
@@ -122,6 +132,8 @@ print(result)
 Rewrite an ambiguous user query using conversation history to improve retrieval:
 
 ```python
+# Requires: mellea[hf]
+# Returns: str
 from mellea.backends.huggingface import LocalHFBackend
 from mellea.stdlib.components import Message
 from mellea.stdlib.components.intrinsic import rag
@@ -147,6 +159,8 @@ print(result)
 Find supporting sentences in source documents for a given assistant response:
 
 ```python
+# Requires: mellea[hf]
+# Returns: dict
 from mellea.backends.huggingface import LocalHFBackend
 from mellea.stdlib.components import Document, Message
 from mellea.stdlib.components.intrinsic import rag
@@ -177,6 +191,8 @@ print(result)
 > `CustomIntrinsicAdapter` directly.
 
 ```python
+# Requires: mellea[hf]
+# Returns: dict
 import mellea.stdlib.functional as mfuncs
 from mellea.backends.adapters.adapter import CustomIntrinsicAdapter
 from mellea.backends.huggingface import LocalHFBackend

docs/docs/concepts/generative-functions.md

@@ -18,6 +18,8 @@ is replaced by the LLM at call time — the signature and docstring guide the mo
 the output.
 
 ```python
+# Requires: mellea
+# Returns: str
 from typing import Literal
 from mellea import generative, start_session
 
@@ -40,6 +42,8 @@ return anything else.
 Generative functions can also return Pydantic models for structured multi-field output:
 
 ```python
+# Requires: mellea, pydantic
+# Returns: FeedbackSummary
 from typing import Literal
 from pydantic import BaseModel
 from mellea import generative, start_session
@@ -70,6 +74,8 @@ Consider two independent libraries: one that summarizes documents, and one that
 decisions or risks from summaries.
 
 ```python
+# Requires: mellea
+# Returns: str
 from mellea import generative
 
 # Summarizer library
@@ -105,6 +111,8 @@ To compose libraries safely without coupling them, use generative functions as c
 classifiers that gate whether a composition makes sense:
 
 ```python
+# Requires: mellea
+# Returns: str
 from typing import Literal
 from mellea import generative
 
@@ -122,6 +130,8 @@ def has_structured_conclusion(summary: str) -> Literal["yes", "no"]:
 These contracts let you write dynamic composition logic in ordinary Python:
 
 ```python
+# Requires: mellea
+# Returns: None
 from mellea import start_session
 
 m = start_session()

docs/docs/concepts/instruct-validate-repair.md

@@ -15,6 +15,8 @@ grounding context, few-shot examples, and images. The instruction is rendered th
 ## Basic `instruct()`
 
 ```python
+# Requires: mellea
+# Returns: str
 import mellea
 
 m = mellea.start_session()
@@ -32,6 +34,8 @@ Embed dynamic values in your description using `{{double_braces}}`. The descript
 is a Jinja2 template; values are injected at generation time via `user_variables`:
 
 ```python
+# Requires: mellea
+# Returns: str
 import mellea
 
 def write_email(m: mellea.MelleaSession, name: str, notes: str) -> str:
@@ -60,6 +64,8 @@ Requirements are declarative constraints. They serve two purposes:
 Pass plain strings for LLM-checked requirements:
 
 ```python
+# Requires: mellea
+# Returns: str
 import mellea
 
 m = mellea.start_session()
@@ -79,6 +85,8 @@ print(str(email))
 For deterministic checks, attach a `validation_fn` to a [`Requirement`](../reference/glossary#requirement):
 
 ```python
+# Requires: mellea
+# Returns: str
 from mellea import start_session
 from mellea.core import Requirement
 from mellea.stdlib.requirements import simple_validate
@@ -104,6 +112,8 @@ with a failure reason) into a validation function.
 `req()` and `check()` are concise constructors for `Requirement`:
 
 ```python
+# Requires: mellea
+# Returns: str
 from mellea import start_session
 from mellea.stdlib.requirements import check, req, simple_validate
 
@@ -135,6 +145,8 @@ generates once, validates all requirements, and retries up to two times if any f
 Configure the loop explicitly with `strategy`:
 
 ```python
+# Requires: mellea
+# Returns: SamplingResult
 from mellea import start_session
 from mellea.stdlib.requirements import req, simple_validate
 from mellea.stdlib.sampling import RejectionSamplingStrategy

docs/docs/concepts/requirements-system.md

@@ -26,6 +26,8 @@ optional validation function. During the [instruct–validate–repair (IVR)](..
 4. The loop retries up to `loop_budget` times (default: 2).
 
 ```python
+# Requires: mellea
+# Returns: Requirement
 from mellea.core import Requirement
 
 # Simplest form: natural-language string.
@@ -37,6 +39,8 @@ Passing plain strings directly to `instruct()` is equivalent — they are
 converted to `Requirement` objects internally:
 
 ```python
+# Requires: mellea
+# Returns: str
 import mellea
 
 m = mellea.start_session()
@@ -51,6 +55,8 @@ email = m.instruct(
 `req()` and `check()` are concise constructors from `mellea.stdlib.requirements`:
 
 ```python
+# Requires: mellea
+# Returns: Requirement
 from mellea.stdlib.requirements import check, req
 
 # req() creates a standard Requirement (description included in the prompt)
@@ -75,6 +81,8 @@ For deterministic checks, attach a `validation_fn`. Mellea skips LLM-as-a-judge
 runs your function directly:
 
 ```python
+# Requires: mellea
+# Returns: str
 from mellea import start_session
 from mellea.core import Requirement
 from mellea.stdlib.requirements import simple_validate
@@ -100,6 +108,8 @@ most recent model output as a string and returns either:
   repair request
 
 ```python
+# Requires: mellea
+# Returns: ValidationResult
 from mellea.stdlib.requirements import simple_validate
 
 # Boolean return
@@ -117,6 +127,8 @@ within_limit = simple_validate(
 a full validation function directly, you construct `ValidationResult` yourself:
 
 ```python
+# Requires: mellea
+# Returns: ValidationResult
 from mellea.core import Context, ValidationResult
 
 

docs/docs/examples/resilient-rag-fallback.md

@@ -58,6 +58,8 @@ Final answer
 ### Inline script dependencies
 
 ```python
+# Requires: faiss-cpu, sentence-transformers, mellea
+# Returns: N/A
 # pytest: skip_always
 # /// script
 # requires-python = ">=3.12"
@@ -77,6 +79,8 @@ execution. No manual `pip install` is needed.
 ### Imports and document corpus
 
 ```python
+# Requires: faiss-cpu, sentence-transformers, mellea
+# Returns: list[str]
 from faiss import IndexFlatIP
 from sentence_transformers import SentenceTransformer
 
@@ -110,6 +114,8 @@ are L2-normalised, as `sentence-transformers` produces by default.
 ### Index creation and querying
 
 ```python
+# Requires: faiss-cpu, sentence-transformers
+# Returns: IndexFlatIP
 def create_index(model, ds: list[str]) -> IndexFlatIP:
     print("running encoding... ")
     embeddings = model.encode(ds)
@@ -135,6 +141,8 @@ overwhelming the context window.
 ### The relevance filter
 
 ```python
+# Requires: mellea
+# Returns: bool
 @generative
 def is_answer_relevant_to_question(answer: str, question: str) -> bool:
     """For the given question, determine whether the answer is relevant or not."""
@@ -213,6 +221,8 @@ prompt correctly and trace each component independently.
 ### Full file
 
 ```python
+# Requires: faiss-cpu, sentence-transformers, mellea
+# Returns: N/A
 # pytest: skip_always
 # /// script
 # requires-python = ">=3.12"

docs/docs/how-to/act-and-aact.md

@@ -22,6 +22,8 @@ fine-grained control, or building your own inference loops.
 These three snippets all produce the same result:
 
 ```python
+# Requires: mellea
+# Returns: str
 import mellea
 from mellea import start_session
 from mellea.stdlib import functional as mfuncs
@@ -49,6 +51,8 @@ result, new_ctx = mfuncs.act(instruction, context=ctx, backend=backend)
 Pass any `Component` to `act()`. It returns a `ModelOutputThunk`:
 
 ```python
+# Requires: mellea
+# Returns: str
 from mellea import start_session
 from mellea.stdlib.components import Instruction
 
@@ -68,6 +72,8 @@ print(str(result))
 skip the IVR loop — this is what `chat()` does internally:
 
 ```python
+# Requires: mellea
+# Returns: str
 from mellea import start_session
 from mellea.stdlib.components import Message
 
@@ -82,6 +88,8 @@ print(str(result))
 Pass document content directly in a `Message`:
 
 ```python
+# Requires: mellea
+# Returns: str
 from mellea import start_session
 from mellea.stdlib.components import Message
 
@@ -106,6 +114,8 @@ For rich document processing (PDFs, tables), see
 The default is `RejectionSamplingStrategy(loop_budget=2)`:
 
 ```python
+# Requires: mellea
+# Returns: SamplingResult
 from mellea import start_session
 from mellea.core import Requirement
 from mellea.stdlib.components import Instruction
@@ -136,6 +146,8 @@ and validation.
 Pass a Pydantic `BaseModel` as the `format` parameter for constrained decoding:
 
 ```python
+# Requires: mellea, pydantic
+# Returns: Planet
 from pydantic import BaseModel
 from mellea import start_session
 from mellea.stdlib.components import Instruction
@@ -159,6 +171,8 @@ print(result.value)  # A Planet instance
 > relying on a session to thread them.
 
 ```python
+# Requires: mellea
+# Returns: str
 from mellea.backends.ollama import OllamaModelBackend
 from mellea.stdlib import functional as mfuncs
 from mellea.stdlib.components import Instruction
@@ -185,6 +199,8 @@ simpler.
 `aact()` is the async counterpart. Same signature, same return types:
 
 ```python
+# Requires: mellea
+# Returns: None
 import asyncio
 from mellea import start_session
 from mellea.stdlib.components import Instruction
@@ -202,6 +218,8 @@ asyncio.run(main())
 The functional async version is `mfuncs.aact()`:
 
 ```python
+# Requires: mellea
+# Returns: tuple
 result, new_ctx = await mfuncs.aact(instruction, context=ctx, backend=backend)
 ```