docs: complete developer documentation rewrite (#480)#601
Merged
Conversation
Merge ProtectionsYour pull request matches the following merge protections and will not be merged until they are valid. 🟢 Enforce conventional commitWonderful, this rule succeeded.Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/
|
Contributor
|
The PR description has been updated. Please fill out the template for your PR to be reviewed. |
Contributor
Author
|
Notes for reviewers:
On Monday I plan to
|
…ext automatically
- Fix how-to/build-a-rag-pipeline: ## See also H2 → **See also:** bold footer - Add RAG how-to card to index.mdx (How-To section, 7 of 8 cards) - Add paired explanation/how-to cross-links: - concepts/requirements-system ↔ how-to/write-custom-verifiers - concepts/mobjects-and-mify ↔ tutorials/05-mifying-legacy-code - Add **See also:** footers to 12 pages missing them: guide/act-and-aact, guide/backends-and-configuration, guide/generative-functions, guide/m-decompose, guide/tools-and-agents, guide/working-with-data, how-to/use-async-and-streaming, tutorials/01, tutorials/03 (add --- separator), tutorials/04, examples/data-extraction-pipeline, examples/legacy-code-integration - Convert ## Next steps / ## What to try next H2 headings to **See also:** inline format (tutorials/01, tutorials/04) or bold text (examples) - Standardise import style in build-a-rag-pipeline to match example: import mellea → from mellea import generative, start_session
1. tutorials/03-using-generative-slots: add missing from typing import Literal to step 2 code block — FeedbackAnalysis uses Literal but the import was absent, causing a NameError if the block was run standalone. 2. tutorials/02-streaming-and-async: remove dead code from step 4 — FeedbackIssues class and extract_issues @Generative function were defined but never called; the pipeline used m.ainstruct() directly for extraction instead. 3. examples/resilient-rag-fallback: fix create_index() using global docs instead of parameter ds in the documentation page. Code worked by coincidence (always called with docs) but would silently ignore any other dataset passed in. Also removes spurious double --- separator from how-to/build-a-rag-pipeline footer. Note: the same bug exists in docs/examples/rag/simple_rag_with_filter.py (source file). That fix is tracked separately — committing the Python file here would trigger the mypy hook which currently fails on pre-existing optional-dependency import-not-found errors in mellea/backends/ that are unrelated to this change.
Address reviewer-reported issues from PR generative-computing#601 review: - Convert 22 relative ../../examples/ links to absolute GitHub URLs (Mintlify only serves docs/docs/, so relative paths 404 on the site) - Fix 5 other broken links (docs.json navbar, CONTRIBUTING placeholders, building-extensions API link, glossary docling URL, README escaping) - Quote all [extras] in pip/uv install commands for zsh compatibility (26 instances across 12+ files) - Fix simple_rag_with_filter.py: encode(docs) → encode(ds) parameter bug Add review tooling: - docs/scripts/check_docs.py: standalone validation script (stdlib only) checking links, Python code blocks, and shell quoting - docs/PR601-REVIEW.md: review comment tracker
- tutorials/03: add `from mellea import generative` to Steps 1-3 code blocks - tutorials/05: add `import mellea` and mify import to Steps 2-5 code blocks - concepts/generative-functions.md: "functions" → "Functions" in title Addresses reviewer comments M1-M4 and C3.
Two FAQ answers imported `generative` but used `start_session()` without importing it. Found by check_docs.py, not flagged by reviewers.
- E2: Remove unnecessary MelleaTool.from_callable() wrapping — @tool decorated functions are already MelleaTool objects - E4: Fix result.body → result.parsed_repr.body on ModelOutputThunk - E6: Fix langchain.tools → langchain_core.tools import path - E7: Fix mellea.stdlib.docs → mellea.stdlib.components.docs import path - E8: Replace broken Document example with working Message approach; filed generative-computing#636 for the underlying Document.parts() bug
Previously check_docs.py only validated the top-level package name (e.g. `mellea` exists), missing incorrect submodule paths like `mellea.stdlib.docs` (should be `mellea.stdlib.components.docs`). Now walks the filesystem to verify each dotted component resolves to a real package directory or .py file. Would have caught E7 from the PR review mechanically.
…tion, tutorial cleanup - C1: reword landing page intro per reviewer suggestion - C4: remove dead blog link in requirements-system - C5: document grounding_context arbitrary key convention - C6: add sample output to tutorial 01 Step 1 - C7: remove duplicate @Generative steps from tutorial 01 (covered in tutorial 03) - C9: clarify ChatContext deprecation warning in tutorial 02 - E3: add ddgs + langchain-community install note - E5: add smolagents install note - E9: add mkdir and model-size warnings to m-decompose - I2+I3: rewrite installation.md with pip/uv as equals, add mellea[all] note - I6: replace WatsonX backend section with deprecation notice - Add deprecation banner to integrations/watsonx.md - Update PR601-REVIEW.md tracker with root cause analysis Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Upstream merged generative-computing#603 (move off python 3.10), pyproject.toml now requires >=3.11. Update all doc references to match. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
Author
|
Thanks again for the comments. Most are actioned - but I moved some to new issues so that we can merge this PR asap. This will allow us to get the pipeline running and publishing asap. I suggest no more comments on this PR - let's raise new issues (or comment on existing ones). This will also make it easier to verify/consolidate with other code changes in the base since these docs were created over a week ago. I've only addressed the merge with the plugins (but not re-edited that content) |
7 tasks
psschwei
reviewed
Mar 13, 2026
Member
psschwei
left a comment
There was a problem hiding this comment.
Can we fix this one before merging?
Mintlify treats `<email@example.com>` as JSX/HTML tags, causing a parse error at line 88. Use markdown link syntax instead. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
psschwei
approved these changes
Mar 13, 2026
Merged
via the queue into
generative-computing:main
with commit Mar 13, 2026
ed01c87
5 checks passed
8 tasks
8 tasks
akihikokuroda
pushed a commit
to akihikokuroda/mellea
that referenced
this pull request
May 27, 2026
) (generative-computing#601) * docs: Phase 0 infrastructure + getting-started.md - CONTRIBUTING.md: writing conventions, PR checklist, code block runability rule, Backend note callout type - .markdownlint.json: fix MD025 front_matter_title so body H1 is allowed alongside YAML frontmatter title - getting-started.md: full tutorial page — install, hello world, user variables, requirements, core concepts, troubleshooting - glossary.md: skeleton in place * docs: Phase 1.2 — the-instruction-model.md Full how-to page covering instruct(), user variables, requirements, custom validation functions (req/check/simple_validate), sampling strategies + IVR loop, grounding context, images, ChatContext, and chat() vs instruct() comparison. Imports verified against source. One inline review note on icl_examples API pending verification. * docs: Phase 1.3 — backends-and-configuration.md Covers Ollama (default), OpenAI-compatible, LiteLLM, HuggingFace, and WatsonX backends. ModelOption constants table, system prompt pattern, direct backend construction. Backend note callouts on each provider. Imports verified against source. * docs: Phase 2.1 — generative-functions.md Covers @Generative decorator, Literal type constraints, Pydantic structured output, pre/post-conditions (PreconditionException), composing generative pipelines, and chain-of-thought pattern. Imports verified against source. * docs: Phase 2.2 — tools-and-agents.md Covers @tool decorator, MelleaTool.from_callable/from_langchain/ from_smolagents, ModelOption.TOOLS, uses_tool, tool_arg_validator, react() agentic loop with structured output, code_interpreter. Incorporates agent definition and ReACT context from old agents.mdx. Imports verified against source (react is async). * docs: Phase 2.3 — working-with-data.md Covers grounding context, RAG with FAISS + generative filtering, @mify / MObject pattern (query/transform, ad-hoc mify, custom stringify, funcs_include), and RichDocument with PDF parsing and table extraction. Incorporates content from mobjects.mdx and generative-slots.mdx. Imports verified against CI examples. * docs: Phase 2.4 — intrinsics.md Covers all RAG intrinsic operations: answerability, context relevance, hallucination detection, answer relevance rewriting, query rewriting, citations, and direct Intrinsic/GraniteCommonAdapter usage. Backend note callout on HF requirement. Imports verified against source. Note: adapters.mdx content (tool calling) already covered in tools-and-agents.md. * docs: Phase 2.5 — sampling-strategies.md Covers RejectionSamplingStrategy (with SamplingResult inspection), validation feedback via ValidationResult.reason, SOFAISamplingStrategy dual-model escalation with s2_solver_mode table, BudgetForcingSamplingStrategy, and MajorityVotingStrategyForMath. Review notes on budget forcing and majority voting exports/parameters. * docs: Phase 2.6 — async-and-streaming.md Covers async/sync method table, parallel generation with ModelOutputThunk, wait_for_all_mots, streaming with ModelOption.STREAM + astream(), and context warnings for concurrent ChatContext use. Imports verified. * docs: Phase 2.7 — act-and-aact.md Covers three abstraction levels (instruct/act/mfuncs), working with Message and Document, validation + sampling strategies via act(), structured output with format=, functional API (mfuncs.act/aact), and aact() async usage. Fixed stale numeric cross-references. * docs: Phase 4.1 — safety-and-validation.md Covers GuardianCheck + GuardianRisk (full enum table), custom criteria, groundedness detection, use as instruct() requirement, and input gate pattern. Backend note on Guardian model independence. Verified against CI example docs/examples/safety/guardian.py. * docs: Phase 4.2 — mcp-integration.md Covers FastMCP server creation, @mcp.tool decorator, mcp dev UI, ModelOption in tools, multiple tools in one server. Imports verified against mcp_example.ipynb CI notebook. * docs: Phase 4.3 — telemetry.md Covers two independent OTEL trace scopes (application + backend), all configuration env vars, start_session() as context manager for trace lifecycle, console debugging, Jaeger/OTLP export, programmatic status checks, and metrics API (create_counter/create_histogram). Verified against mellea/telemetry/__init__.py and telemetry_example.py. Includes Gen-AI semantic convention attribute tables. * docs: Phase 4.4 — custom-sessions.md Covers SimpleContext vs ChatContext, ctx introspection helpers (last_output/last_turn), session.clone() for context branching, session.reset(), and extending MelleaSession with a ChatCheckingSession example. Absorbs content from core-concept/context-management.mdx. Verified against session.py and creating_a_new_type_of_session.py. * docs: Phase 5.1 — generative-programming.md Conceptual page explaining what generative programs are, the deterministic/stochastic interleaving challenge, requirements as the core reliability mechanism, failure handling, uncertainty compounding, context management, and Mellea's position as execution layer (not orchestrator). Absorbs content from overview/generative-programming.mdx and overview/mellea-welcome.mdx. * docs: Phase 5.2 — mellea-core-internals.md Covers the three core data structures (CBlock, Component, ModelOutputThunk), six abstraction layers from MelleaSession down to direct backend.generate_from_context() with lazy thunks, composition via SimpleComponent, and template/prompt engineering (TemplateFormatter, TemplateRepresentation, Jinja2 template resolution, model-specific paths). Verified imports against session_deepdive step files. Absorbs content from prompt-engineering.mdx. * docs: Phase 5.3 — troubleshooting.md Covers installation errors (outlines/Rust, Intel Mac, missing extras), Ollama connectivity, requirements/sampling diagnosis with return_sampling_results=True, PreconditionException, react() loop exhaustion, tool selection debugging, async/event-loop errors, Jupyter nest_asyncio, and Guardian setup issues. * docs: Phase B — restructure guide/ into target hierarchy Reorganises the 18 flat guide/ pages written in Phase A into the target Diataxis-aligned directory structure: - getting-started/ installation.md + quickstart.md (split from getting-started.md) - concepts/ generative-programming.md, instruct-validate-repair.md - how-to/ use-async-and-streaming.md, use-context-and-sessions.md - integrations/ mcp-and-m-serve.md - evaluation-and-observability/ metrics-and-telemetry.md - advanced/ intrinsics.md, inference-time-scaling.md, security-and-taint-tracking.md, mellea-core-internals.md - troubleshooting/ common-errors.md - guide/ generative-functions, tools-and-agents, working-with-data, backends-and-configuration, act-and-aact, glossary (in place) Updates: - docs.json: replaces old MDX nav with new hierarchy (9 groups) - All cross-links updated to new relative paths - Nav footers updated to match new linear order - Navbar "Contribution Guide" link updated to /guide/CONTRIBUTING Old MDX pages (overview/, core-concept/) removed from nav; files kept on disk until Phase C content is verified complete. * docs: Phase C.1 — concepts/requirements-system.md Adds depth page on the Requirements system: Requirement class, ValidationResult, simple_validate(), req()/check(), check_only/purple-elephant effect, precondition_requirements + PreconditionException, SamplingResult inspection, and LLM-as-judge vs custom validator trade-offs. Updates instruct-validate-repair.md footer and docs.json nav. * docs: Phase C.2 — concepts/architecture-vs-agents.md Adds positioning page explaining Mellea as execution layer vs. orchestration frameworks (LangChain, smolagents). Covers the three adoption paths (greenfield, leaf-node injection, tool enrichment) with concrete code examples showing how Mellea functions compose inside smolagents and LangChain. Updates requirements-system.md footer and docs.json nav. * docs: Phase C.3 — how-to/enforce-structured-output.md Adds task-oriented guide for structured output covering @Generative with Literal/Pydantic return types, instruct(format=...) for dynamic prompts, content validation on structured output (at_least_n pattern), and guidance on choosing between the two approaches. Updates docs.json nav. * docs: Phase C.4 — how-to/write-custom-verifiers.md Adds practical guide for writing custom validation functions: full validation_fn signature, simple_validate shortcut, common patterns (JSON, Pydantic schema, regex, external API), ValidationResult.score, composing verifiers, and debugging with SamplingResult.sample_validations. Updates docs.json nav. * docs: Phase C.5 — integrations/ollama.md Adds Ollama integration page covering installation, default setup (granite4:micro), recommended models table, custom host configuration, ModelOption usage, vision models, OpenAI-compatible endpoint, and troubleshooting section. Updates docs.json nav. * docs: Phase C.6 — integrations/openai.md Adds OpenAI integration page covering OpenAI API setup, OpenAI-compatible local servers (LM Studio, Ollama endpoint, vLLM), vision/multimodal input, structured output with format=, ModelOption usage, and troubleshooting. Updates docs.json nav. * docs: Phase C.7 — tutorials/01-your-first-generative-program.md Adds the first tutorial: an 8-step walkthrough building a document analysis pipeline from a single instruct() call through requirements, rejection sampling, @Generative with Literal and Pydantic, and composition. Uses a consistent customer feedback example throughout. Adds Tutorials group to docs.json nav. * docs: Phase C.8 — concepts/context-and-sessions.md Adds architecture explanation page covering the Component/Backend/Context/ Session four-layer architecture, SimpleContext vs ChatContext trade-offs, context window management, session cloning, context inspection, and why explicit context management matters. Updates docs.json nav. * docs: Phase C.9 — evaluation-and-observability/handling-exceptions.md Adds error handling page covering SamplingResult.success=False patterns, PreconditionException inspection, ComponentParseError, backend connection errors, fallback patterns (simpler call, stronger model / SOFAI), and logging failures. Updates docs.json nav. * docs: Phase C.10 — integrations/bedrock-and-watsonx.md Adds cloud backends page: AWS Bedrock via create_bedrock_mantle_backend and LiteLLM, IBM WatsonX with WatsonxAIBackend. Covers credentials, region selection, available models, direct and environment-variable auth, and troubleshooting for both providers. Updates docs.json nav. * docs: Phase C-review fixes — nav footers, code corrections, linting Fix 9 nav footer mismatches caused by incremental page insertions not updating adjacent pages: quickstart, generative-programming, architecture-vs-agents, use-context-and-sessions, write-custom-verifiers, ollama, openai, metrics-and-telemetry, tutorials/01. Code fixes: - requirements-system.md: add missing RejectionSamplingStrategy import in precondition example - bedrock-and-watsonx.md: str(result) for consistency - instruct-validate-repair.md: correct diataxis to explanation - tutorials/01: fix stale Full example pointer, remove broken Next link to unwritten page 02 - use-context-and-sessions.md: add sidebarTitle to disambiguate from concepts page; fix over-heavy prerequisite Linting: - Add .markdownlint.json at docs/docs/ level so config covers all subdirectories (concepts/, how-to/, integrations/, etc.), not just guide/ * docs: fix README and add reader-facing index.md README.md had a broken fenced code block (mismatched backticks), a duplicate Getting Started section, emoji, and a wrong URL pointing to mellea.ai instead of docs.mellea.ai. Rewritten as a clean contributor setup guide. index.md is a new reader-facing landing page for GitHub and non-Mintlify browsing. Mintlify ignores it (root redirects to getting-started/installation via docs.json) but GitHub renders it as the directory index. * docs: expand index.md to show full section structure * docs: port 4 missing pages from Hendrik's MDX — generative-functions, mobjects-and-mify, configure-model-options, template-formatting * docs: fix convention violations in 4 new pages (US English, missing import, table spacing) * docs: update index.md with 4 new pages * docs: add Core Reference to index.md; cross-link tools-and-agents from generative-functions * docs: add advanced/lora-and-alora-adapters.md — train and use custom adapters * docs: fix import errors, deprecated model IDs, nav link, and add Mintlify redirects - configure-model-options.md: fix ModelOption import path (backends.types → backends); replace deprecated IBM_GRANITE_3_2_8B/IBM_GRANITE_4_MICRO_3B with current models - mobjects-and-mify.md: fix mify/MifiedProtocol import path (stdlib.mify → stdlib.components); fix ModelOption import path - docs.json: fix CONTRIBUTING navbar href to GitHub URL (was unreachable /guide/CONTRIBUTING); add feedback.thumbsRating; add redirects for all removed MDX pages to new paths - CONTRIBUTING.md: add docs writing guide link in Additional Resources * docs: fix docs badge URL in README (mellea.ai → docs.mellea.ai) * docs: add m serve section, fix landing page, add GitHub nav index - mcp-and-m-serve.md: retitle to "MCP and m serve"; add m serve section (serve() signature, starting the server, calling the endpoint); fix deprecated model IDs; fix nav footer (Previous was wrong page); fix MD028/MD024 lint warnings - index.mdx: new Mintlify landing page with CardGroup layout covering core concepts, integrations, and quick-start paths; replaces the plain list that was being served at / - docs/index.md: move GitHub-only nav index out of Mintlify root (to docs/ parent) so it no longer overrides the landing page * docs: revise landing page — closer to original style with updated content * docs: align landing page with mellea.ai messaging and voice * docs: fix landing page links — remove non-existent HuggingFace page, add How-To section * docs: remove oversized logo from landing page — navbar logo is sufficient * docs: split MCP page, add HuggingFace/vLLM integration, update landing page Split integrations/mcp-and-m-serve.md into two focused pages: - integrations/mcp.md — FastMCP tool wrapping for MCP clients - integrations/m-serve.md — OpenAI-compatible serving with m serve Add integrations/huggingface-and-vllm.md covering LocalHFBackend (experimental features: aLoRA, constrained decoding; cuda/mps/cpu auto) and LocalVLLMBackend (high-throughput batched inference; Linux only). Update index.mdx: add HuggingFace/vLLM card to Backends section, fix MCP card link, add subtle Mellea logo. Update docs.json: nav uses new page slugs, redirect /integrations/mcp-and-m-serve → /integrations/mcp. * docs: remove redundant logo from landing page body (navbar logo sufficient) * docs: fix logo CSS classes — dark/light were inverted * docs: remove page-body logo (wordmark-only SVG; navbar already shows it) * docs: add Mellea mushroom mascot to landing page * docs: fix and expand glossary — correct 5 wrong definitions, add 7 missing terms * docs: add m decompose guide page; expand glossary with 5 missing terms * docs: add glossary links on first use; strengthen CONTRIBUTING standard - Link Mellea-specific terms to glossary on first use across 8 pages: quickstart, tutorial/01, concepts/generative-programming, concepts/generative-functions, concepts/instruct-validate-repair, concepts/requirements-system, concepts/context-and-sessions - Add external links for Jinja2 and Pydantic on first use - Expand Requirement glossary entry to document req(), check(), and simple_validate() including the prompt-inclusion distinction - Fix metrics-and-telemetry.md Previous footer (was mcp-and-m-serve, now m-serve) - CONTRIBUTING.md: formalise glossary link rule with required-terms table and add checklist item for glossary links * docs: add integrations/langchain-and-smolagents.md Covers two integration patterns: - MelleaTool.from_langchain() — wrap any LangChain BaseTool for use in Mellea - MelleaTool.from_smolagents() — wrap smolagents tools (pip install 'mellea[smolagents]') - Seeding ChatContext from LangChain message history via convert_to_openai_messages Add to docs.json nav after m-serve; update m-serve and metrics-and-telemetry nav footers to reflect new page position. * docs: split bedrock-and-watsonx into separate bedrock.md and watsonx.md AWS Bedrock and IBM WatsonX are distinct platforms with different auth, packages, and model IDs. Each now has its own page. Nav chain: openai → bedrock → watsonx → huggingface-and-vllm Redirect: /integrations/bedrock-and-watsonx → /integrations/bedrock * docs: add how-to/use-images-and-vision.md; fix nav footer chain Covers PIL image input via instruct()/chat(), ImageBlock for OpenAI backend, multi-turn vision with ChatContext, and backend support matrix. Sources verified against vision_ollama_chat.py and vision_openai_examples.py examples. Also fix pre-existing nav bug: ollama.md Previous was pointing to write-custom-verifiers, skipping configure-model-options entirely. Nav chain: configure-model-options → use-images-and-vision → ollama * docs: fix landing page card, add ImageBlock to glossary, improve backend pages - index.mdx: split single "Bedrock / watsonx" card into separate AWS Bedrock and IBM WatsonX cards pointing to the correct split pages - glossary.md: add ImageBlock entry (used by use-images-and-vision.md) - bedrock.md: add glossary links for Backend/MelleaSession on first prose use; add Vision support section noting image input works via OpenAI-compatible path - watsonx.md: add glossary links for start_session/Backend on first prose use; add Vision support section noting WatsonxAIBackend does not support images * docs: split huggingface-and-vllm into separate huggingface.md and vllm.md - Create integrations/huggingface.md (LocalHFBackend, device selection, KV cache, aLoRA, vision, troubleshooting) - Create integrations/vllm.md (LocalVLLMBackend, batched inference, vision, troubleshooting) - Delete integrations/huggingface-and-vllm.md - docs.json: replace combined entry with huggingface + vllm; add redirect for old URL - index.mdx: split single card into separate HuggingFace and vLLM cards - Update nav footers: watsonx.md Next, mcp.md Previous * docs: split langchain-and-smolagents into separate langchain.md and smolagents.md - Create integrations/langchain.md (tool bridging, message history bridge, comparison table) - Create integrations/smolagents.md (tool bridging, comparison table) - Delete integrations/langchain-and-smolagents.md - docs.json: replace combined entry with langchain + smolagents; add redirect for old URL - Update nav footers: m-serve.md Next, metrics-and-telemetry.md Previous * docs: reorganise nav — rename Core Reference to Guides, co-locate m-serve, fix section assignments - Rename "Core Reference" → "Guides" (all 6 pages were diataxis how-to, not reference) - Move m-serve from Integrations → Guides alongside m-decompose (both first-party CLI tools) - Move handling-exceptions from Evaluation and Observability → How-To (it's a coding how-to, not observability) - Reorder Integrations: local (ollama, huggingface, vllm) → cloud (openai, bedrock, watsonx) → protocol/frameworks (mcp, langchain, smolagents) All 102 nav pages verified to exist on disk. * docs: float mascot logo left so intro paragraph wraps alongside it * docs: remove redundant Previous/Next footer nav (Mintlify handles this) * docs: remove Discord link from landing page * docs: expand ModelOutputThunk glossary entry with value, async, and streaming details * docs: remove .md extensions from internal links so Mintlify renders pages correctly * chore: trigger Mintlify rebuild * fix: use jsx styles on index.mdx Signed-off-by: Paul S. Schweigert <paul@paulschweigert.com> * docs: remove duplicate H1 headings — Mintlify renders frontmatter title automatically * docs: add 10 new glossary entries and first-use cross-links * docs: add prefix-caching-and-kv-blocks page, KV smashing + SimpleLRUCache glossary entries * docs: add tutorials 02-03, LLM-as-a-judge how-to, and new glossary entries Add three new content pages: - tutorials/02-mifying-legacy-code: five-step tutorial on @mify — query and transform existing Python objects with m.query() and m.transform(), stringify_func, fields_include, funcs_include, and ad-hoc mify(obj) - tutorials/03-using-generative-slots: five-step tutorial on @Generative — Literal/Pydantic returns, pipeline composition, ChatContext injection, m.reset(), and pre/postcondition validation patterns - evaluation-and-observability/evaluate-with-llm-as-a-judge: how-to covering default LLMaJ behavior, standalone m.validate(), GenerateLog capture, purple elephant effect with check(), simple_validate bypass, combined checks, and SamplingResult metadata Also: - Add all three pages to docs.json nav - Add GenerateLog, LLM-as-a-judge, and Purple elephant effect to glossary - Add first-use glossary cross-links and full example pointers in each page * docs: add 14 new pages, fix nav, update AGENTS.md writing guide New pages: - tutorials/04-making-agents-reliable (ReACT, requirements, GuardianCheck) - how-to/refactor-prompts-with-cli (m decompose workflow) - how-to/unit-test-generative-code (pytest markers, TestBasedEval) - integrations/vertex-ai (LiteLLMBackend, vertex_ai/ model strings) - advanced/custom-components (Component protocol, TemplateRepresentation) - evaluation-and-observability/opentelemetry-tracing (spans, OTLP, Jaeger) - examples/index + 4 example pages (data-extraction, legacy-code, rag, telemetry) - community/contributing-guide, building-extensions, code-of-conduct - troubleshooting/faq (10 Q&A) Fixes: - tutorials/01: broken Next steps links; model-config review note added - docs.json: handling-exceptions moved to Eval & Observability (was How-To) - docs.json nav: all new pages registered - glossary: ComponentParseError, GuardianRisk, GuardianCheck expanded - AGENTS.md: Section 10 "Writing Docs" added with key conventions * docs: fix lint, complete review items, add missing strategy docs - Fix MD012 multiple-blank-lines in 20 files (trailing double blank lines) - Fix MD028 blank-line-inside-blockquote in smolagents.md - vertex-ai.md: replace "Hendrik please confirm" review note with verified LiteLLM docs — vertex_project/vertex_location keys are correct and override env vars at call time - inference-time-scaling.md: remove two "review needed" notes on BudgetForcingSamplingStrategy and MajorityVotingStrategyForMath; add source-verified parameter docs for both - inference-time-scaling.md: add sections for RepairTemplateStrategy, MultiTurnStrategy, and BaseSamplingStrategy (all in __all__ but previously undocumented) * docs: add missing glossary entries for new sampling strategies and PythonExecutionReq - Sampling strategy table: add RepairTemplateStrategy, MultiTurnStrategy, MBRDRougeLStrategy, BaseSamplingStrategy, correct MajorityVoting name to MajorityVotingStrategyForMath - Requirement entry: document PythonExecutionReq (code execution validator) with import path and key parameters * chore: delete legacy MDX files — replaced by new docs structure * ci: add markdownlint docs-lint job to CI * ci: add markdownlint pre-commit hook for docs/ * docs: refresh landing page cards; add index.mdx reminder to CONTRIBUTING checklist - Key patterns: swap MCP card for Tools and agents (@tool, MelleaTool, react()) - How-to guides: swap Handling exceptions for Use images and vision - Backends: add LiteLLM / Vertex AI card - CONTRIBUTING.md checklist: add item to review landing page cards when adding a major page * docs: separate contributor vs user content; fix internal references unit-test-generative-code.md: - Add single top-of-page callout directing Mellea contributors to contributing-guide#testing; remove all other contributor callouts - Rewrite session fixture using plain OllamaModelBackend (no gh_run) - Rewrite module markers section as generic user guidance with pyproject.toml snippet - Rewrite CI strategy section with a user-owned conftest.py pattern (CI=true) instead of Mellea's internal CICD=1 convention traced-generation-loop.md: - Replace dead internal reference docs/dev/telemetry.md (deleted file) with link to user-facing OpenTelemetry Tracing page mellea-core-internals.md: - mfuncs async row: "Mellea contributors" → "Advanced users building async pipelines" template-formatting.md: - "contributors and advanced users" → "advanced users and library authors" * docs: improve landing page key patterns and backends grid - Key patterns: remove 'Generative slots' (concept already in How it works section) replace 'Intrinsics and adapters' (too advanced/niche) with: - Async and streaming (use-async-and-streaming) - Safety checks (GuardianCheck via tutorial 04) - Backends: add LangChain as 8th card — makes even 4+4 grid * docs: add streaming/async tutorial; promote to T02, demote mify to T05 Add 02-streaming-and-async.md covering ainstruct(), streaming with ModelOption.STREAM/astream(), concurrent batch processing with wait_for_all_mots, mixed parallel/sequential pipelines, and context behaviour with async. Rename 02-mifying-legacy-code.md → 05-mifying-legacy-code.md so the main onboarding path (01 → 02 → 03 → 04) builds from universal async patterns to agents before introducing the Mellea-specific @mify feature. Update Tutorial 04 prerequisites to include Tutorial 02, since Step 7 introduces asyncio and react(). Update docs.json nav. * docs: add RAG how-to; expand examples index to all categories Add how-to/build-a-rag-pipeline.md covering the full RAG pattern: embedding and indexing, vector search, @Generative bool relevance filter, grounding_context for grounded generation, IVR requirements on the answer, and optional GuardianCheck groundedness verification. Includes a tuning table and a complete worked example. Expand examples/index.md from 4 documented examples to a comprehensive catalogue of all example categories, grouped by area (core concepts, data, agents, safety, integrations, performance, multimodal, observability, experimental). Preserves the existing 4 walkthrough pages at the top. Register build-a-rag-pipeline in docs.json How-To nav group. * docs: add cross-linking guideline for paired explanation/how-to pages When a feature has both a concepts/ explanation and a guide/ or how-to/ page, contributors should add a brief cross-link near the top of each so readers who land on either page can find the other. Adds the guideline under Diataxis classification and a PR checklist item. * docs: merge Guides into How-To; rename Advanced to Deep Dives Removes the Guides nav section — all 6 pages were how-to content and are now merged into a single How-To section (15 pages total). Core feature how-tos lead; task-specific how-tos follow. Moves integrations/m-serve from Guides to the Integrations section where its path already placed it logically. Renames Advanced to Deep Dives to signal optional/technical depth rather than implying a content type distinct from How-To. * docs: revert Advanced rename — keep as Advanced pending discussion * docs: add cross-links between paired explanation and how-to pages Add concept overview / practical usage callouts to the two clear paired page sets: - concepts/generative-functions ↔ guide/generative-functions - concepts/context-and-sessions ↔ how-to/use-context-and-sessions * docs: nav reorder, glossary additions, and CONTRIBUTING fixes Move Examples section to position 5 (after How-To, before Integrations) so runnable code follows concept and how-to content in the learning path. Glossary: add grounding_context and wait_for_all_mots entries. Fix CONTRIBUTING guide violations in new pages: - tutorials/02: add --- footer separator; link ModelOutputThunk, start_session()/SimpleContext/ChatContext on first use - how-to/build-a-rag-pipeline: link @Generative, GuardianCheck, grounding_context on first use; change Note to Backend note for the Ollama-specific GuardianCheck requirement - examples/resilient-rag-fallback: link @Generative and grounding_context on first use; add missing navigation footer * docs: correct Navigation footer guideline — Mintlify generates prev/next automatically * docs: fix footers, add cross-links, and standardise imports - Fix how-to/build-a-rag-pipeline: ## See also H2 → **See also:** bold footer - Add RAG how-to card to index.mdx (How-To section, 7 of 8 cards) - Add paired explanation/how-to cross-links: - concepts/requirements-system ↔ how-to/write-custom-verifiers - concepts/mobjects-and-mify ↔ tutorials/05-mifying-legacy-code - Add **See also:** footers to 12 pages missing them: guide/act-and-aact, guide/backends-and-configuration, guide/generative-functions, guide/m-decompose, guide/tools-and-agents, guide/working-with-data, how-to/use-async-and-streaming, tutorials/01, tutorials/03 (add --- separator), tutorials/04, examples/data-extraction-pipeline, examples/legacy-code-integration - Convert ## Next steps / ## What to try next H2 headings to **See also:** inline format (tutorials/01, tutorials/04) or bold text (examples) - Standardise import style in build-a-rag-pipeline to match example: import mellea → from mellea import generative, start_session * docs: fix three code correctness issues found in review 1. tutorials/03-using-generative-slots: add missing from typing import Literal to step 2 code block — FeedbackAnalysis uses Literal but the import was absent, causing a NameError if the block was run standalone. 2. tutorials/02-streaming-and-async: remove dead code from step 4 — FeedbackIssues class and extract_issues @Generative function were defined but never called; the pipeline used m.ainstruct() directly for extraction instead. 3. examples/resilient-rag-fallback: fix create_index() using global docs instead of parameter ds in the documentation page. Code worked by coincidence (always called with docs) but would silently ignore any other dataset passed in. Also removes spurious double --- separator from how-to/build-a-rag-pipeline footer. Note: the same bug exists in docs/examples/rag/simple_rag_with_filter.py (source file). That fix is tracked separately — committing the Python file here would trigger the mypy hook which currently fails on pre-existing optional-dependency import-not-found errors in mellea/backends/ that are unrelated to this change. * docs: fix broken links, shell quoting, and add validation tooling Address reviewer-reported issues from PR generative-computing#601 review: - Convert 22 relative ../../examples/ links to absolute GitHub URLs (Mintlify only serves docs/docs/, so relative paths 404 on the site) - Fix 5 other broken links (docs.json navbar, CONTRIBUTING placeholders, building-extensions API link, glossary docling URL, README escaping) - Quote all [extras] in pip/uv install commands for zsh compatibility (26 instances across 12+ files) - Fix simple_rag_with_filter.py: encode(docs) → encode(ds) parameter bug Add review tooling: - docs/scripts/check_docs.py: standalone validation script (stdlib only) checking links, Python code blocks, and shell quoting - docs/PR601-REVIEW.md: review comment tracker * docs: add missing imports to tutorial snippets and fix title casing - tutorials/03: add `from mellea import generative` to Steps 1-3 code blocks - tutorials/05: add `import mellea` and mify import to Steps 2-5 code blocks - concepts/generative-functions.md: "functions" → "Functions" in title Addresses reviewer comments M1-M4 and C3. * docs: fix missing start_session import in FAQ code blocks Two FAQ answers imported `generative` but used `start_session()` without importing it. Found by check_docs.py, not flagged by reviewers. * docs: fix 5 runtime errors found in PR review (E2, E4, E6, E7, E8) - E2: Remove unnecessary MelleaTool.from_callable() wrapping — @tool decorated functions are already MelleaTool objects - E4: Fix result.body → result.parsed_repr.body on ModelOutputThunk - E6: Fix langchain.tools → langchain_core.tools import path - E7: Fix mellea.stdlib.docs → mellea.stdlib.components.docs import path - E8: Replace broken Document example with working Message approach; filed generative-computing#636 for the underlying Document.parts() bug * docs: enhance import validation to check full mellea module paths Previously check_docs.py only validated the top-level package name (e.g. `mellea` exists), missing incorrect submodule paths like `mellea.stdlib.docs` (should be `mellea.stdlib.components.docs`). Now walks the filesystem to verify each dotted component resolves to a real package directory or .py file. Would have caught E7 from the PR review mechanically. * docs: address review comments — installation rewrite, WatsonX deprecation, tutorial cleanup - C1: reword landing page intro per reviewer suggestion - C4: remove dead blog link in requirements-system - C5: document grounding_context arbitrary key convention - C6: add sample output to tutorial 01 Step 1 - C7: remove duplicate @Generative steps from tutorial 01 (covered in tutorial 03) - C9: clarify ChatContext deprecation warning in tutorial 02 - E3: add ddgs + langchain-community install note - E5: add smolagents install note - E9: add mkdir and model-size warnings to m-decompose - I2+I3: rewrite installation.md with pip/uv as equals, add mellea[all] note - I6: replace WatsonX backend section with deprecation notice - Add deprecation banner to integrations/watsonx.md - Update PR601-REVIEW.md tracker with root cause analysis Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: bump Python version references from 3.10+ to 3.11+ Upstream merged generative-computing#603 (move off python 3.10), pyproject.toml now requires >=3.11. Update all doc references to match. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: fix angle-bracket email parsing error in code-of-conduct Mintlify treats `<email@example.com>` as JSX/HTML tags, causing a parse error at line 88. Use markdown link syntax instead. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Signed-off-by: Paul S. Schweigert <paul@paulschweigert.com> Co-authored-by: Paul S. Schweigert <paul@paulschweigert.com> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #480
Complete rewrite of the Mellea developer documentation, published via Mintlify at https://docs.mellea.ai.
Preview branch: https://ibm-llm-runtime-aaf3a78b.mintlify.app/
Type of PR
What's included
Content — full Diataxis-structured developer docs
All code examples verified against the current codebase. No TODO comments or "review needed" notes remain.
Standards
markdownlintpasses clean (zero errors) — enforced in pre-commit and CI.mdextensions in internal linksdocs/CONTRIBUTING.md)CI
docs-lintjob inci.yml— runsmarkdownlint-clion every PRmarkdownlintpre-commit hook — runs on staged.mdfiles at commit timeCleanup
.mdxfiles removed (overview/,core-concept/,dev/) — all content superseded by the new structureThanks
Thanks to @HendrikStrobelt for the original source content that anchored the concepts and advanced sections.