diff --git a/.github/workflows/docs-publish.yml b/.github/workflows/docs-publish.yml index 1062985ef..6f20a9d72 100644 --- a/.github/workflows/docs-publish.yml +++ b/.github/workflows/docs-publish.yml @@ -1,9 +1,8 @@ name: Docs -# Builds, validates, and deploys documentation to orphan deployment branches. -# Mintlify reads from these branches — main stays clean of generated artifacts. -# -# See docs/PUBLISHING.md for the full architecture and strategy. +# Builds, validates, and deploys Docusaurus documentation to GitHub Pages. +# Fork (planetf1/mellea) → https://planetf1.github.io/mellea/ (baseUrl: /mellea/) +# Upstream (generative-computing/mellea) → https://docs.mellea.ai (baseUrl: /) on: push: @@ -33,18 +32,9 @@ on: description: "Deploy even from a non-main context (for testing)" type: boolean default: false - target_branch: - description: "Override deploy target branch (default: docs/preview)" - type: string - default: "docs/preview" - strict_validation: - description: "Fail the build if validation checks fail" - type: boolean - default: false release_tag: description: >- - Set to a release tag (e.g. `v0.6.0`) to run the - deploy-on-release flow. Used by release.sh. + Set to a release tag (e.g. v0.6.0) to run the deploy-on-release flow. type: string default: "" @@ -57,6 +47,9 @@ concurrency: env: UV_FROZEN: "1" FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true" + # baseUrl: /mellea/ on fork, / on upstream + DOCS_BASE_URL: ${{ github.repository == 'generative-computing/mellea' && '/' || '/mellea/' }} + DOCS_SITE_URL: ${{ github.repository == 'generative-computing/mellea' && 'https://docs.mellea.ai' || 'https://planetf1.github.io' }} jobs: # --------------------------------------------------------------------------- @@ -81,9 +74,20 @@ jobs: enable-cache: true cache-dependency-glob: "uv.lock" - - name: Install dependencies + - name: Set up Node.js + uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + with: + node-version: "20" + cache: "npm" + cache-dependency-path: "docs/package-lock.json" + + - name: Install Python dependencies run: uv sync --frozen --all-extras --group dev + - name: Install Node dependencies + run: npm ci + working-directory: docs + # -- Generate API documentation ------------------------------------------ - name: Generate API documentation @@ -102,25 +106,17 @@ jobs: set -o pipefail npx --yes markdownlint-cli "docs/docs/**/*.md" --config docs/docs/.markdownlint.json 2>&1 \ | tee /tmp/markdownlint.log - continue-on-error: ${{ inputs.strict_validation != true }} + continue-on-error: true # -- Validate generated API docs ----------------------------------------- - - name: Validate MDX syntax and links - id: validate_mdx - run: | - set -o pipefail - uv run python tooling/docs-autogen/validate.py docs/docs/api --skip-coverage --docs-root docs 2>&1 \ - | tee /tmp/validate_mdx.log - continue-on-error: ${{ inputs.strict_validation != true }} - - name: Audit API coverage id: audit_coverage run: | set -o pipefail uv run python tooling/docs-autogen/audit_coverage.py --docs-dir docs/docs/api --threshold 80 2>&1 \ | tee /tmp/audit_coverage.log - continue-on-error: ${{ inputs.strict_validation != true }} + continue-on-error: true - name: Docstring quality gate id: quality_gate @@ -133,7 +129,15 @@ jobs: --output /tmp/quality_report.json 2>&1 \ | tee /tmp/quality_gate.log - # -- Upload artifact for deploy job -------------------------------------- + # -- Build Docusaurus site ----------------------------------------------- + + - name: Build Docusaurus site + run: npm run build + working-directory: docs + env: + DOCS_BASE_URL: ${{ env.DOCS_BASE_URL }} + + # -- Upload artifacts ---------------------------------------------------- - name: Upload quality report if: always() @@ -143,12 +147,12 @@ jobs: path: /tmp/quality_report.json retention-days: 30 - - name: Upload docs artifact - if: success() || (inputs.strict_validation != true) + - name: Upload built site artifact + if: success() uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 with: name: docs-site - path: docs/docs/ + path: docs/build/ retention-days: 7 # -- Write job summary --------------------------------------------------- @@ -156,163 +160,17 @@ jobs: - name: Write job summary if: always() run: | - python3 - <<'PYEOF' - import os, re - - def icon(outcome): - return "✅" if outcome == "success" else ("❌" if outcome == "failure" else "⏭️") - - def read_log(path): - try: - raw = open(path).read().strip() - # Strip ANSI escape codes (colour output from uv/pytest etc.) - return re.sub(r'\x1b\[[0-9;]*[mK]', '', raw) - except FileNotFoundError: - return "" - - markdownlint_outcome = os.environ.get("STEPS_MARKDOWNLINT_OUTCOME", "") - validate_outcome = os.environ.get("STEPS_VALIDATE_MDX_OUTCOME", "") - coverage_outcome = os.environ.get("STEPS_AUDIT_COVERAGE_OUTCOME", "") - quality_gate_outcome = os.environ.get("STEPS_QUALITY_GATE_OUTCOME", "") - lint_log = read_log("/tmp/markdownlint.log") - validate_log = read_log("/tmp/validate_mdx.log") - coverage_log = read_log("/tmp/audit_coverage.log") - quality_gate_log = read_log("/tmp/quality_gate.log") - - # Count markdownlint issues (lines matching file:line:col format) - lint_issues = len([l for l in lint_log.splitlines() if re.match(r'.+:\d+:\d+ ', l)]) - lint_detail = f"{lint_issues} issue(s)" if lint_issues else "no issues" - - # Extract coverage stats from audit_coverage output - cov_pct = re.search(r"Coverage:\s+(\S+%)", coverage_log) - cov_sym = re.search(r"Documented:\s+(\d+)", coverage_log) - cov_tot = re.search(r"Total classes \+ functions:\s+(\d+)", coverage_log) - cov_detail = ( - f"{cov_pct.group(1)} ({cov_sym.group(1)}/{cov_tot.group(1)} symbols)" - if cov_pct and cov_sym and cov_tot else "" - ) - - # Parse per-check error counts from validate output. - # Each check prints "N errors found" on the next line when it fails. - def parse_validate_detail(log): - counts = {} - for label, key in [ - ("Source links", "source"), ("MDX syntax", "syntax"), - ("Internal links", "links"), ("Anchor collisions", "anchors"), - ("Stale files", "stale"), - ]: - m = re.search(rf"{label}: (?:PASS|FAIL)(?:\s+(\d+) errors found)?", log, re.DOTALL) - if m: - counts[key] = int(m.group(1)) if m.group(1) else 0 - total = sum(counts.values()) - if not total: - return "no issues" - parts = [] - if counts.get("syntax"): parts.append(f"{counts['syntax']} syntax error(s)") - if counts.get("links"): parts.append(f"{counts['links']} broken link(s)") - if counts.get("anchors"): parts.append(f"{counts['anchors']} anchor collision(s)") - if counts.get("source"): parts.append(f"{counts['source']} source link error(s)") - if counts.get("stale"): parts.append(f"{counts['stale']} stale file(s)") - return ", ".join(parts) - - mdx_detail = parse_validate_detail(validate_log) - - # Parse per-kind counts from the quality gate log. - # _print_quality_report emits section headers like: - # " Missing docstrings (12)" - # " Missing Args section (5)" - # Capture label -> count from those lines, then build a compact - # per-kind breakdown for the summary table cell. - kind_short = { - "Missing docstrings": "missing", - "Short docstrings": "short", - "Missing Args section": "no_args", - "Missing Returns section": "no_returns", - "Missing Yields section (generator)": "no_yields", - "Missing Raises section": "no_raises", - "Missing class Args section": "no_class_args", - "Duplicate Args: in class + __init__ (Option C violation)": "dup_init_args", - "Param name mismatches (documented but not in signature)": "param_mismatch", - "TypedDict phantom fields (documented but not declared)": "td_phantom", - "TypedDict undocumented fields (declared but missing from Attributes:)": "td_undoc", - "Missing parameter type annotations (type absent from API docs)": "missing_param_type", - "Missing return type annotations (type absent from API docs)": "missing_return_type", - "Param type mismatch (docstring vs annotation)": "param_type_mismatch", - "Return type mismatch (docstring vs annotation)": "return_type_mismatch", - } - section_re = re.compile(r"^\s{2}(.+?)\s+\((\d+)\)\s*$", re.MULTILINE) - kind_counts = {} - for m in section_re.finditer(quality_gate_log): - label, count = m.group(1), int(m.group(2)) - short = kind_short.get(label) - if short: - kind_counts[short] = count - - if kind_counts: - parts = [f"{v} {k}" for k, v in kind_counts.items()] - quality_gate_detail = ", ".join(parts) - else: - # Fall back to the summary annotation message - qm = re.search(r"::(notice|warning|error) title=Docstring quality::(.+)", quality_gate_log) - quality_gate_detail = re.sub(r"\s*—\s*see job summary.*$", "", qm.group(2)) if qm else "" - - CONTRIB_URL = ( - "https://github.com/generative-computing/mellea/blob/main" - "/docs/CONTRIBUTING_DOCS.md" - ) - REPO = os.environ.get("GITHUB_REPOSITORY", "") - RUN_ID = os.environ.get("GITHUB_RUN_ID", "") - ARTIFACT_URL = f"https://github.com/{REPO}/actions/runs/{RUN_ID}#artifacts" - - lines = [ - "## Docs Build — Validation Summary\n", - "| Check | Result | Details |", - "|-------|--------|---------|", - f"| Markdownlint | {icon(markdownlint_outcome)} {markdownlint_outcome} | {lint_detail} |", - f"| MDX Validation | {icon(validate_outcome)} {validate_outcome} | {mdx_detail} |", - f"| API Coverage | {icon(coverage_outcome)} {coverage_outcome} | {cov_detail} |", - f"| Docstring Quality | {icon(quality_gate_outcome)} {quality_gate_outcome} | {quality_gate_detail} |", - ] - lines.append("") - - # When the quality gate fails, surface a direct link to the fix reference. - # Per-kind Ref: URLs in the log output are inside a ```text``` block and - # don't render as links there. - if quality_gate_outcome == "failure": - lines += [ - "> ❌ **Docstring quality gate failed.** " - f"See the [CI docstring checks reference]({CONTRIB_URL}#ci-docstring-checks-reference) " - "for per-kind fix instructions, or expand **Docstring quality details** below for the full list. \n" - f"> The full machine-readable report is available as the [`docstring-quality-report` artifact]({ARTIFACT_URL}).", - "", - ] - - for title, log, limit in [ - ("Markdownlint output", lint_log, 5_000), - ("MDX validation output", validate_log, 5_000), - ("API coverage output", coverage_log, 5_000), - ("Docstring quality details", quality_gate_log, 1_000_000), - ]: - if log: - lines += [ - f"
{title}\n", - "```text", - log[:limit] + (" [truncated]" if len(log) > limit else ""), - "```", - "
\n", - ] - - with open(os.environ["GITHUB_STEP_SUMMARY"], "a") as f: - f.write("\n".join(lines)) - PYEOF - env: - STEPS_MARKDOWNLINT_OUTCOME: ${{ steps.markdownlint.outcome }} - STEPS_VALIDATE_MDX_OUTCOME: ${{ steps.validate_mdx.outcome }} - STEPS_AUDIT_COVERAGE_OUTCOME: ${{ steps.audit_coverage.outcome }} - STEPS_QUALITY_GATE_OUTCOME: ${{ steps.quality_gate.outcome }} + echo "## Docs Build Summary" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "| Check | Result |" >> $GITHUB_STEP_SUMMARY + echo "|-------|--------|" >> $GITHUB_STEP_SUMMARY + echo "| Markdownlint | ${{ steps.markdownlint.outcome }} |" >> $GITHUB_STEP_SUMMARY + echo "| API Coverage | ${{ steps.audit_coverage.outcome }} |" >> $GITHUB_STEP_SUMMARY + echo "| Docstring Quality | ${{ steps.quality_gate.outcome }} |" >> $GITHUB_STEP_SUMMARY + echo "| Docusaurus Build | ${{ steps.build_site.outcome }} |" >> $GITHUB_STEP_SUMMARY # --------------------------------------------------------------------------- - # Deploy to orphan branch + # Deploy to GitHub Pages # --------------------------------------------------------------------------- deploy: needs: build-and-validate @@ -321,31 +179,22 @@ jobs: contents: write timeout-minutes: 10 - # Deploy on: push to main, release event, force_publish or release_tag - # via dispatch, or PRs labelled "docs-preview" (→ docs/preview branch). - # The runtime latest-final-by-semver check below prevents older-branch - # patches from overwriting production docs. + # Deploy on: push to main, release event, force_publish via dispatch if: >- github.event_name == 'push' || github.event_name == 'release' || - (github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'docs-preview')) || (github.event_name == 'workflow_dispatch' && (inputs.force_publish || inputs.release_tag != '')) steps: - - name: Download docs artifact + - name: Download site artifact uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 with: name: docs-site path: docs-site/ - # For release events, confirm the published tag is the latest final by - # semver across all release branches. Without this, publishing v0.6.1 - # after v0.7.0 already exists would incorrectly downgrade docs/production - # to the older minor's docs. + # For release events, confirm the published tag is the latest final by semver. - name: Check release is latest final id: latest_check - # Fail open: deploy if the check succeeded (true) or a transient API - # error left the output empty. Only skip on an explicit 'false'. continue-on-error: true if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && inputs.release_tag != '') env: @@ -380,8 +229,6 @@ jobs: print(f"error: current tag {current} is not a valid version") sys.exit(1) - # include the current release itself (the API may not include it - # yet if eventing races with the release event) candidates.append((current_version, current)) latest_version, latest_tag = max(candidates) is_latest = (latest_tag == current or latest_version == current_version) @@ -392,53 +239,14 @@ jobs: print(f"current={current} latest={latest_tag} is_latest={is_latest}") PY - - name: Determine target branch - id: target - run: | - if [ "$EVENT_NAME" = "release" ] || [ -n "${INPUTS_RELEASE_TAG}" ]; then - echo "branch=docs/production" >> "$GITHUB_OUTPUT" - elif [ "$EVENT_NAME" = "pull_request" ]; then - echo "branch=docs/preview" >> "$GITHUB_OUTPUT" - elif [ "$EVENT_NAME" = "workflow_dispatch" ] && [ -n "${INPUTS_TARGET_BRANCH}" ]; then - echo "branch=${INPUTS_TARGET_BRANCH}" >> "$GITHUB_OUTPUT" - else - echo "branch=docs/staging" >> "$GITHUB_OUTPUT" - fi - env: - EVENT_NAME: ${{ github.event_name }} - INPUTS_TARGET_BRANCH: ${{ inputs.target_branch }} - INPUTS_RELEASE_TAG: ${{ inputs.release_tag }} - - - name: Add DO NOT EDIT warning - run: | - cat > docs-site/_DO_NOT_EDIT.md << 'EOF' - # DO NOT EDIT THIS BRANCH - - This branch is **fully automated**. Every file here is generated by - the `docs-publish` GitHub Actions workflow and force-pushed on each run. - - **Any manual edits will be overwritten without warning.** - - To change documentation: - - Static guides: edit files under `docs/docs/` on `main` - - API reference: improve docstrings in Python source (`mellea/`, `cli/`) - - Pipeline config: see `tooling/docs-autogen/` on `main` - - For details, see `docs/PUBLISHING.md` on `main`. - EOF - - - name: Deploy to ${{ steps.target.outputs.branch }} - # Skip production deploy when a release is not the latest final by - # semver (e.g. a patch on an older release branch). The latest_check - # step runs for both `release` events and workflow_dispatch with - # release_tag set; either path can request the skip. + - name: Deploy to GitHub Pages (gh-pages branch) if: >- steps.latest_check.conclusion == 'skipped' || steps.latest_check.outputs.is_latest_final != 'false' uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4 with: github_token: ${{ secrets.GITHUB_TOKEN }} - publish_branch: ${{ steps.target.outputs.branch }} + publish_branch: gh-pages publish_dir: docs-site/ force_orphan: true user_name: "github-actions[bot]" @@ -447,35 +255,21 @@ jobs: docs: publish from ${{ github.sha }} Branch: ${{ github.ref_name }} - Trigger: ${{ github.event_name }}${{ github.event.pull_request.number && format(' (PR #{0})', github.event.pull_request.number) }} + Trigger: ${{ github.event_name }} Run: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }} - name: Write deploy summary if: always() run: | - TARGET="${STEPS_TARGET_OUTPUTS_BRANCH}" REPO="${GITHUB_REPOSITORY}" SHA="${GITHUB_SHA}" - if [ "${JOB_STATUS}" = "success" ]; then - STATUS="✅ Deployed" - DETAIL="Published to [\`${TARGET}\`](https://github.com/${REPO}/tree/${TARGET})" - else - STATUS="❌ Failed" - DETAIL="Attempted deploy to \`${TARGET}\`" - fi - cat >> "$GITHUB_STEP_SUMMARY" << EOF - ## Docs Deploy — ${STATUS} - - | | | - |-|-| - | Branch | \`${TARGET}\` | - | Source | \`${SHA:0:7}\` | - | Trigger | ${EVENT_NAME}${PR_SUFFIX} | - - ${DETAIL} - EOF + BASE="${DOCS_BASE_URL}" + echo "## Docs Deploy" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "| | |" >> $GITHUB_STEP_SUMMARY + echo "|-|-|" >> $GITHUB_STEP_SUMMARY + echo "| Branch | \`gh-pages\` |" >> $GITHUB_STEP_SUMMARY + echo "| Source | \`${SHA:0:7}\` |" >> $GITHUB_STEP_SUMMARY + echo "| Base URL | \`${BASE}\` |" >> $GITHUB_STEP_SUMMARY env: - STEPS_TARGET_OUTPUTS_BRANCH: ${{ steps.target.outputs.branch }} - JOB_STATUS: ${{ job.status }} - EVENT_NAME: ${{ github.event_name }} - PR_SUFFIX: "${{ github.event.pull_request.number && format(' (PR #{0})', github.event.pull_request.number) }}" + DOCS_BASE_URL: ${{ env.DOCS_BASE_URL }} diff --git a/.gitignore b/.gitignore index 86a08bc82..4680107d8 100644 --- a/.gitignore +++ b/.gitignore @@ -457,6 +457,14 @@ pyrightconfig.json # Generated documentation (built by tooling/docs-autogen/) docs/docs/api/ +!docs/docs/api/index.md docs/docs/api-reference.mdx docs/docs/reference/cli.md .venv-docs-autogen/ + +# Docusaurus build artifacts +docs/node_modules/ +docs/build/ +docs/.docusaurus/ +docs/sidebars.api.generated.ts +docs/sidebars.api.generated.json diff --git a/docs/docs/README.md b/docs/docs/README.md deleted file mode 100644 index 90c7bb48d..000000000 --- a/docs/docs/README.md +++ /dev/null @@ -1,30 +0,0 @@ -# Mellea documentation - -This directory contains the source for the [Mellea documentation site](https://docs.mellea.ai). - -## About Mellea - -Mellea is a library for writing generative programs. Generative programming replaces flaky agents -and brittle prompts with structured, maintainable, robust, and efficient AI workflows. - -## Running the docs locally - -### 1. Install Mintlify CLI - -```bash -npm install -g mintlify -``` - -### 2. Start the dev server - -```bash -cd docs/docs -mintlify dev -``` - -The site is available at . - -## Contributing - -See [CONTRIBUTING.md](https://github.com/generative-computing/mellea/blob/main/CONTRIBUTING.md) for the general contribution guide and -[CONTRIBUTING_DOCS.md](https://github.com/generative-computing/mellea/blob/main/docs/CONTRIBUTING_DOCS.md) for documentation writing conventions. diff --git a/docs/docs/advanced/_category_.json b/docs/docs/advanced/_category_.json new file mode 100644 index 000000000..08e5e2fa7 --- /dev/null +++ b/docs/docs/advanced/_category_.json @@ -0,0 +1 @@ +{"label": "Advanced", "position": 8} diff --git a/docs/docs/advanced/custom-components.md b/docs/docs/advanced/custom-components.md index caacc5051..e4fe5dc2c 100644 --- a/docs/docs/advanced/custom-components.md +++ b/docs/docs/advanced/custom-components.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/advanced/custom-components" title: "Building Custom Components" description: "Implement the Component Protocol to create reusable, testable generative building blocks." # diataxis: how-to diff --git a/docs/docs/advanced/inference-time-scaling.md b/docs/docs/advanced/inference-time-scaling.md index 0d2c64a50..c14dde8b7 100644 --- a/docs/docs/advanced/inference-time-scaling.md +++ b/docs/docs/advanced/inference-time-scaling.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/advanced/inference-time-scaling" title: "Inference-Time Scaling" description: "Control how Mellea generates and validates outputs: rejection sampling, SOFAI, budget forcing, and majority voting." # diataxis: how-to diff --git a/docs/docs/advanced/intrinsics.md b/docs/docs/advanced/intrinsics.md index e513b8f0a..509f10f57 100644 --- a/docs/docs/advanced/intrinsics.md +++ b/docs/docs/advanced/intrinsics.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/advanced/intrinsics" title: "Intrinsics" description: "Adapter-accelerated RAG quality checks using LoRA/aLoRA adapters with Granite models." # diataxis: how-to @@ -7,7 +6,7 @@ description: "Adapter-accelerated RAG quality checks using LoRA/aLoRA adapters w **Prerequisites:** `pip install "mellea[hf]"` for LocalHFBackend (GPU or Apple Silicon Mac recommended), or `pip install mellea` for OpenAIBackend with a -[Granite Switch](../guide/glossary#granite-switch) model served via vLLM. +[Granite Switch](/reference/glossary#granite-switch) model served via vLLM. Intrinsics are adapter-accelerated operations for RAG quality checks. They use LoRA/aLoRA adapters loaded directly into the HuggingFace backend — faster and more diff --git a/docs/docs/advanced/lora-and-alora-adapters.md b/docs/docs/advanced/lora-and-alora-adapters.md index 4bfb0c646..fa0aad481 100644 --- a/docs/docs/advanced/lora-and-alora-adapters.md +++ b/docs/docs/advanced/lora-and-alora-adapters.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/advanced/lora-and-alora-adapters" title: "LoRA and aLoRA adapters" description: "Train lightweight adapters on your own labeled data and use them as requirement validators in Mellea programs." # diataxis: how-to diff --git a/docs/docs/advanced/mellea-core-internals.md b/docs/docs/advanced/mellea-core-internals.md index 612f2e366..ebef2fad2 100644 --- a/docs/docs/advanced/mellea-core-internals.md +++ b/docs/docs/advanced/mellea-core-internals.md @@ -1,8 +1,7 @@ --- -canonical: "https://docs.mellea.ai/advanced/mellea-core-internals" title: "Mellea Core Internals" description: "The three core data structures and abstraction layers underlying every Mellea program." -sidebarTitle: "Core Internals" +sidebar_label: "Core Internals" # diataxis: explanation --- diff --git a/docs/docs/advanced/prefix-caching-and-kv-blocks.md b/docs/docs/advanced/prefix-caching-and-kv-blocks.md index a69e53e44..04e7fc7d0 100644 --- a/docs/docs/advanced/prefix-caching-and-kv-blocks.md +++ b/docs/docs/advanced/prefix-caching-and-kv-blocks.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/advanced/prefix-caching-and-kv-blocks" title: "Prefix Caching and KV Blocks" description: "Reuse KV cache state across calls to eliminate redundant prefill work on LocalHFBackend." # diataxis: how-to diff --git a/docs/docs/advanced/template-formatting.md b/docs/docs/advanced/template-formatting.md index cbe493798..550f3db2f 100644 --- a/docs/docs/advanced/template-formatting.md +++ b/docs/docs/advanced/template-formatting.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/advanced/template-formatting" title: "Template formatting" description: "How Mellea's TemplateFormatter converts Python objects into model-ready text using Jinja2 templates." # diataxis: explanation diff --git a/docs/docs/api/index.md b/docs/docs/api/index.md new file mode 100644 index 000000000..a48242a49 --- /dev/null +++ b/docs/docs/api/index.md @@ -0,0 +1,20 @@ +--- +title: API Reference +description: Auto-generated API reference for the Mellea Python library. +sidebar_label: Overview +sidebar_position: 0 +--- + +This section is generated automatically from Python source docstrings. + +Run the autogen pipeline to populate it: + +```bash +uv run poe apidocs +``` + +Then rebuild the docs: + +```bash +uv run poe docs-build +``` diff --git a/docs/docs/community/_category_.json b/docs/docs/community/_category_.json new file mode 100644 index 000000000..4bb906735 --- /dev/null +++ b/docs/docs/community/_category_.json @@ -0,0 +1 @@ +{"label": "Community", "position": 9} diff --git a/docs/docs/community/building-extensions.md b/docs/docs/community/building-extensions.md index 899e97f54..ea7af1357 100644 --- a/docs/docs/community/building-extensions.md +++ b/docs/docs/community/building-extensions.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/community/building-extensions" title: "Building Extensions" description: "Create custom components, backends, sampling strategies, and requirements to extend Mellea." # diataxis: how-to diff --git a/docs/docs/community/code-of-conduct.md b/docs/docs/community/code-of-conduct.md index 375ff37fc..9f989e939 100644 --- a/docs/docs/community/code-of-conduct.md +++ b/docs/docs/community/code-of-conduct.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/community/code-of-conduct" title: "Code of Conduct" description: "Standards and enforcement for the Mellea community." # diataxis: reference diff --git a/docs/docs/community/contributing-guide.md b/docs/docs/community/contributing-guide.md index fc56ed531..911cfaccc 100644 --- a/docs/docs/community/contributing-guide.md +++ b/docs/docs/community/contributing-guide.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/community/contributing-guide" title: "Contributing to Mellea" description: "Development setup, coding standards, and PR process for Mellea contributors." # diataxis: how-to diff --git a/docs/docs/concepts/_category_.json b/docs/docs/concepts/_category_.json new file mode 100644 index 000000000..996d10e2d --- /dev/null +++ b/docs/docs/concepts/_category_.json @@ -0,0 +1 @@ +{"label": "Concepts", "position": 3} diff --git a/docs/docs/concepts/architecture-vs-agents.md b/docs/docs/concepts/architecture-vs-agents.md index e465b8e18..2eb434ce7 100644 --- a/docs/docs/concepts/architecture-vs-agents.md +++ b/docs/docs/concepts/architecture-vs-agents.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/concepts/architecture-vs-agents" title: "Mellea vs Orchestration Frameworks" description: "What makes Mellea different from LangChain, smolagents, and other agent frameworks — and how they work together." # diataxis: explanation diff --git a/docs/docs/concepts/context-and-sessions.md b/docs/docs/concepts/context-and-sessions.md index 5fd727185..b4f65895a 100644 --- a/docs/docs/concepts/context-and-sessions.md +++ b/docs/docs/concepts/context-and-sessions.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/concepts/context-and-sessions" title: "Context and Sessions" description: "How Component, Backend, Context, and Session fit together in Mellea's architecture." # diataxis: explanation diff --git a/docs/docs/concepts/generative-functions.md b/docs/docs/concepts/generative-functions.md index fc95afa27..87e602269 100644 --- a/docs/docs/concepts/generative-functions.md +++ b/docs/docs/concepts/generative-functions.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/concepts/generative-functions" title: "Generative Functions" description: "How the @generative decorator turns a Python function signature into an LLM-backed implementation." # diataxis: explanation diff --git a/docs/docs/concepts/generative-programming.md b/docs/docs/concepts/generative-programming.md index ff66e409a..be2970ad8 100644 --- a/docs/docs/concepts/generative-programming.md +++ b/docs/docs/concepts/generative-programming.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/concepts/generative-programming" title: "Generative Programming" description: "The ideas behind Mellea — what generative programs are, why they're hard, and how Mellea addresses those challenges." # diataxis: explanation diff --git a/docs/docs/concepts/instruct-validate-repair.md b/docs/docs/concepts/instruct-validate-repair.md index a0edf7a23..33f9749a0 100644 --- a/docs/docs/concepts/instruct-validate-repair.md +++ b/docs/docs/concepts/instruct-validate-repair.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/concepts/instruct-validate-repair" title: "The Instruction Model" description: "How instruct(), requirements, and the IVR loop work in Mellea." # diataxis: explanation diff --git a/docs/docs/concepts/mobjects-and-mify.md b/docs/docs/concepts/mobjects-and-mify.md index b7774be84..719926939 100644 --- a/docs/docs/concepts/mobjects-and-mify.md +++ b/docs/docs/concepts/mobjects-and-mify.md @@ -1,11 +1,10 @@ --- -canonical: "https://docs.mellea.ai/concepts/mobjects-and-mify" title: "MObjects and mify" description: "How the @mify decorator turns any Python class into an LLM-queryable object with controlled field and method exposure." # diataxis: explanation --- -> **Looking to use this in code?** See [Tutorial 05: MIFYing Legacy Code](../tutorials/05-mifying-legacy-code) for a practical walkthrough. +> **Looking to use this in code?** See [Tutorial 05: MIFYing Legacy Code](../tutorials/mifying-legacy-code) for a practical walkthrough. Object-oriented programming organizes related data and the methods that operate on it into classes. Mellea applies the same principle to LLM interactions: an **MObject** is a Python diff --git a/docs/docs/concepts/plugins.mdx b/docs/docs/concepts/plugins.mdx index b81492dc1..85c6bd882 100644 --- a/docs/docs/concepts/plugins.mdx +++ b/docs/docs/concepts/plugins.mdx @@ -1,8 +1,7 @@ --- -canonical: "https://docs.mellea.ai/concepts/plugins" title: "Plugins & Hooks" description: "Intercept and customize Mellea's execution pipeline with plugins — enforce policies, add observability, and transform payloads at well-defined hook points." -sidebarTitle: "Plugins & Hooks" +sidebar_label: "Plugins & Hooks" # diataxis: explanation --- @@ -25,9 +24,9 @@ Plugins are organized into six hook categories: - **Sampling Pipeline** — sampling loop events (`sampling_loop_start`, `sampling_iteration`, `sampling_repair`, `sampling_loop_end`) - **Tool Execution** — before and after tool invocations (`tool_pre_invoke`, `tool_post_invoke`) - +:::note Plugins require the hooks extra: `pip install 'mellea[hooks]'` - +::: --- @@ -675,9 +674,9 @@ async def enforce_tool_allowlist(payload, ctx): return block(f"Tool '{payload.model_tool_call.name}' not permitted", code="TOOL_NOT_ALLOWED") ``` - +:::note The payload includes an `is_control_flow` field that is `True` for framework control-flow tools (e.g. the ReAct loop's `final_answer`). Allowlist plugins should check this field to avoid blocking internal tools. See [Control-flow tools](#control-flow-tools) for the recommended pattern. - +::: #### `tool_post_invoke` @@ -720,9 +719,9 @@ This table summarizes which fields are writable for each hook type. Changes to n | `tool_pre_invoke` | `model_tool_call` | | `tool_post_invoke` | `tool_output` | - +:::warning Only `SEQUENTIAL` and `TRANSFORM` modes can modify payloads. `AUDIT`, `CONCURRENT`, and `FIRE_AND_FORGET` modes have their modifications silently discarded regardless of the policy table. - +::: --- @@ -788,9 +787,9 @@ async def send_telemetry(payload, ctx): await telemetry_client.send({"component": payload.component_type}) ``` - +:::note The FIRE_AND_FORGET log output may appear after the main result is printed. This is expected behavior, as these hooks run in the background. - +::: ### Chaining diff --git a/docs/docs/concepts/requirements-system.md b/docs/docs/concepts/requirements-system.md index 494f709da..cfbc039c9 100644 --- a/docs/docs/concepts/requirements-system.md +++ b/docs/docs/concepts/requirements-system.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/concepts/requirements-system" title: "The Requirements System" description: "How Requirement, ValidationResult, and the IVR loop work together to enforce constraints on generative output." # diataxis: explanation diff --git a/docs/docs/docs.json b/docs/docs/docs.json deleted file mode 100644 index 4469fcc40..000000000 --- a/docs/docs/docs.json +++ /dev/null @@ -1,636 +0,0 @@ -{ - "$schema": "https://leaves.mintlify.com/schema/docs.json", - "theme": "maple", - "name": "Mellea", - "colors": { - "primary": "#000000", - "light": "#c5c5c5", - "dark": "#000000" - }, - "fonts": { - "heading": { - "family": "IBM Plex Sans" - }, - "body": { - "family": "IBM Plex Sans" - } - }, - "favicon": "/images/favicon.svg", - "navigation": { - "tabs": [ - { - "tab": "Docs", - "groups": [ - { - "group": "Getting Started", - "pages": [ - "getting-started/installation", - "getting-started/quickstart" - ] - }, - { - "group": "Tutorials", - "pages": [ - "tutorials/01-your-first-generative-program", - "tutorials/02-streaming-and-async", - "tutorials/03-using-generative-stubs", - "tutorials/04-making-agents-reliable", - "tutorials/05-mifying-legacy-code", - "tutorials/06-streaming-validation" - ] - }, - { - "group": "Concepts", - "pages": [ - "concepts/generative-programming", - "concepts/generative-functions", - "concepts/instruct-validate-repair", - "concepts/requirements-system", - "concepts/architecture-vs-agents", - "concepts/context-and-sessions", - "concepts/mobjects-and-mify", - "concepts/plugins" - ] - }, - { - "group": "How-To", - "pages": [ - "how-to/generative-functions", - "how-to/tools-and-agents", - "how-to/working-with-data", - "how-to/backends-and-configuration", - "how-to/act-and-aact", - "how-to/m-decompose", - "how-to/use-async-and-streaming", - "how-to/use-context-and-sessions", - "how-to/enforce-structured-output", - "how-to/write-custom-verifiers", - "how-to/evaluate-with-llm-as-a-judge", - "how-to/configure-model-options", - "how-to/use-images-and-vision", - "how-to/build-a-rag-pipeline", - "how-to/safety-guardrails", - "how-to/refactor-prompts-with-cli", - "how-to/unit-test-generative-code", - "how-to/handling-exceptions" - ] - }, - { - "group": "Examples", - "pages": [ - "examples/index", - "examples/data-extraction-pipeline", - "examples/legacy-code-integration", - "examples/resilient-rag-fallback", - "examples/traced-generation-loop" - ] - }, - { - "group": "Integrations", - "pages": [ - "integrations/ollama", - "integrations/huggingface", - "integrations/openai", - "integrations/vertex-ai", - "integrations/bedrock", - "integrations/watsonx", - "integrations/mcp", - "integrations/langchain", - "integrations/smolagents", - "integrations/m-serve" - ] - }, - { - "group": "Observability", - "pages": [ - "observability/telemetry", - "observability/tracing", - "observability/metrics", - "observability/logging" - ] - }, - { - "group": "Advanced", - "pages": [ - "advanced/intrinsics", - "advanced/lora-and-alora-adapters", - "advanced/prefix-caching-and-kv-blocks", - "advanced/inference-time-scaling", - "advanced/mellea-core-internals", - "advanced/template-formatting", - "advanced/custom-components" - ] - }, - { - "group": "Community", - "pages": [ - "community/contributing-guide", - "community/building-extensions", - "community/code-of-conduct" - ] - }, - { - "group": "Reference", - "pages": [ - "reference/glossary", - "reference/cli" - ] - }, - { - "group": "Troubleshooting", - "pages": [ - "troubleshooting/common-errors", - "troubleshooting/faq" - ] - } - ] - }, - { - "tab": "API Reference", - "pages": [ - "api-reference", - { - "group": "mellea", - "pages": [ - { - "group": "backends", - "pages": [ - "api/mellea/backends/backend", - "api/mellea/backends/backends", - "api/mellea/backends/cache", - "api/mellea/backends/model_ids", - "api/mellea/backends/model_options", - "api/mellea/backends/tools", - { - "group": "adapters", - "pages": [ - "api/mellea/backends/adapters/adapter" - ] - } - ] - }, - { - "group": "core", - "pages": [ - "api/mellea/core/backend", - "api/mellea/core/base", - "api/mellea/core/core", - "api/mellea/core/formatter", - "api/mellea/core/requirement", - "api/mellea/core/sampling", - "api/mellea/core/utils" - ] - }, - { - "group": "formatters", - "pages": [ - "api/mellea/formatters/chat_formatter", - "api/mellea/formatters/formatters", - "api/mellea/formatters/template_formatter", - { - "group": "granite", - "pages": [ - { - "group": "base", - "pages": [ - "api/mellea/formatters/granite/base/base", - "api/mellea/formatters/granite/base/io", - "api/mellea/formatters/granite/base/optional", - "api/mellea/formatters/granite/base/types", - "api/mellea/formatters/granite/base/util" - ] - }, - { - "group": "granite3", - "pages": [ - "api/mellea/formatters/granite/granite3/types", - { - "group": "granite32", - "pages": [ - "api/mellea/formatters/granite/granite3/granite32/input", - "api/mellea/formatters/granite/granite3/granite32/output", - "api/mellea/formatters/granite/granite3/granite32/types" - ] - }, - { - "group": "granite33", - "pages": [ - "api/mellea/formatters/granite/granite3/granite33/input", - "api/mellea/formatters/granite/granite3/granite33/output", - "api/mellea/formatters/granite/granite3/granite33/types" - ] - } - ] - }, - { - "group": "intrinsics", - "pages": [ - "api/mellea/formatters/granite/intrinsics/input", - "api/mellea/formatters/granite/intrinsics/output", - "api/mellea/formatters/granite/intrinsics/util" - ] - } - ] - } - ] - }, - { - "group": "helpers", - "pages": [ - "api/mellea/helpers/async_helpers", - "api/mellea/helpers/helpers", - "api/mellea/helpers/openai_compatible_helpers", - "api/mellea/helpers/server_type" - ] - }, - { - "group": "plugins", - "pages": [ - "api/mellea/plugins/base", - "api/mellea/plugins/decorators", - "api/mellea/plugins/plugins", - "api/mellea/plugins/pluginset", - "api/mellea/plugins/registry", - "api/mellea/plugins/types", - { - "group": "hooks", - "pages": [ - "api/mellea/plugins/hooks/component", - "api/mellea/plugins/hooks/generation", - "api/mellea/plugins/hooks/sampling", - "api/mellea/plugins/hooks/session", - "api/mellea/plugins/hooks/tool", - "api/mellea/plugins/hooks/validation" - ] - } - ] - }, - { - "group": "stdlib", - "pages": [ - "api/mellea/stdlib/context", - "api/mellea/stdlib/functional", - "api/mellea/stdlib/session", - "api/mellea/stdlib/stdlib", - { - "group": "components", - "pages": [ - "api/mellea/stdlib/components/chat", - "api/mellea/stdlib/components/instruction", - "api/mellea/stdlib/components/mify", - "api/mellea/stdlib/components/mobject", - "api/mellea/stdlib/components/simple", - { - "group": "docs", - "pages": [ - "api/mellea/stdlib/components/docs/document" - ] - }, - { - "group": "intrinsic", - "pages": [ - "api/mellea/stdlib/components/intrinsic/intrinsic" - ] - } - ] - }, - { - "group": "frameworks", - "pages": [ - "api/mellea/stdlib/frameworks/react" - ] - }, - { - "group": "requirements", - "pages": [ - "api/mellea/stdlib/requirements/md", - "api/mellea/stdlib/requirements/python_reqs", - "api/mellea/stdlib/requirements/requirement", - "api/mellea/stdlib/requirements/tool_reqs", - { - "group": "safety", - "pages": [ - "api/mellea/stdlib/requirements/safety/guardian" - ] - } - ] - }, - { - "group": "sampling", - "pages": [ - "api/mellea/stdlib/sampling/base", - "api/mellea/stdlib/sampling/sofai", - { - "group": "sampling_algos", - "pages": [ - "api/mellea/stdlib/sampling/sampling_algos/budget_forcing_alg" - ] - } - ] - }, - { - "group": "tools", - "pages": [ - "api/mellea/stdlib/tools/interpreter" - ] - } - ] - }, - { - "group": "telemetry", - "pages": [ - "api/mellea/telemetry/context", - "api/mellea/telemetry/logging", - "api/mellea/telemetry/metrics", - "api/mellea/telemetry/telemetry", - "api/mellea/telemetry/tracing" - ] - } - ] - } - ] - } - ] - }, - "logo": { - "light": "/logo/logo-light.svg", - "dark": "/logo/logo-dark.svg" - }, - "navbar": { - "primary": { - "type": "button", - "label": "GitHub", - "href": "https://github.com/generative-computing/mellea" - }, - "links": [ - { - "label": "Blog", - "href": "https://generative-computing.github.io/blog/" - }, - { - "label": "Community", - "href": "https://github.com/generative-computing/mellea/discussions" - }, - { - "label": "Contribution Guide", - "href": "https://github.com/generative-computing/mellea/blob/main/CONTRIBUTING.md" - }, - { - "label": "Support", - "href": "https://github.com/generative-computing/mellea/issues" - } - ] - }, - "search": { - "prompt": "Search documentation..." - }, - "feedback": { - "thumbsRating": true - }, - "redirects": [ - { - "source": "/guide/glossary", - "destination": "/reference/glossary" - }, - { - "source": "/overview/overview", - "destination": "/getting-started/quickstart" - }, - { - "source": "/overview/mellea-welcome", - "destination": "/" - }, - { - "source": "/overview/quick-start", - "destination": "/getting-started/quickstart" - }, - { - "source": "/overview/project-mellea", - "destination": "/concepts/generative-programming" - }, - { - "source": "/overview/generative-programming", - "destination": "/concepts/generative-programming" - }, - { - "source": "/overview/architecture", - "destination": "/how-to/backends-and-configuration" - }, - { - "source": "/core-concept/instruct-validate-repair", - "destination": "/concepts/instruct-validate-repair" - }, - { - "source": "/core-concept/requirements", - "destination": "/concepts/requirements-system" - }, - { - "source": "/core-concept/generative-slots", - "destination": "/how-to/generative-functions" - }, - { - "source": "/core-concept/mobjects", - "destination": "/concepts/mobjects-and-mify" - }, - { - "source": "/core-concept/agents", - "destination": "/how-to/tools-and-agents" - }, - { - "source": "/core-concept/context-management", - "destination": "/how-to/use-context-and-sessions" - }, - { - "source": "/core-concept/alora", - "destination": "/advanced/lora-and-alora-adapters" - }, - { - "source": "/core-concept/tuning", - "destination": "/advanced/lora-and-alora-adapters" - }, - { - "source": "/core-concept/modeloptions", - "destination": "/how-to/configure-model-options" - }, - { - "source": "/core-concept/interoperability", - "destination": "/integrations/mcp" - }, - { - "source": "/integrations/mcp-and-m-serve", - "destination": "/integrations/mcp" - }, - { - "source": "/core-concept/adapters", - "destination": "/how-to/tools-and-agents" - }, - { - "source": "/core-concept/contribution-guide", - "destination": "/community/contributing-guide" - }, - { - "source": "/core-concept/prompt-engineering", - "destination": "/advanced/mellea-core-internals" - }, - { - "source": "/integrations/bedrock-and-watsonx", - "destination": "/integrations/bedrock" - }, - { - "source": "/integrations/huggingface-and-vllm", - "destination": "/integrations/huggingface" - }, - { - "source": "/integrations/langchain-and-smolagents", - "destination": "/integrations/langchain" - }, - { - "source": "/dev/constrained-decoding", - "destination": "/advanced/mellea-core-internals" - }, - { - "source": "/dev/generate-ctx-signature", - "destination": "/advanced/mellea-core-internals" - }, - { - "source": "/dev/intrinsics-and-adapters", - "destination": "/advanced/intrinsics" - }, - { - "source": "/dev/mellea-library", - "destination": "/concepts/generative-programming" - }, - { - "source": "/dev/mify", - "destination": "/concepts/mobjects-and-mify" - }, - { - "source": "/dev/requirement-alora-rerouting", - "destination": "/advanced/lora-and-alora-adapters" - }, - { - "source": "/dev/spans", - "destination": "/observability/tracing" - }, - { - "source": "/dev/tool-calling", - "destination": "/how-to/tools-and-agents" - }, - { - "source": "/api/cli/m", - "destination": "/reference/cli" - }, - { - "source": "/api/cli/alora/commands", - "destination": "/reference/cli" - }, - { - "source": "/api/cli/alora/intrinsic_uploader", - "destination": "/reference/cli" - }, - { - "source": "/api/cli/alora/readme_generator", - "destination": "/reference/cli" - }, - { - "source": "/api/cli/alora/train", - "destination": "/reference/cli" - }, - { - "source": "/api/cli/alora/upload", - "destination": "/reference/cli" - }, - { - "source": "/api/cli/decompose/decompose", - "destination": "/reference/cli" - }, - { - "source": "/api/cli/decompose/pipeline", - "destination": "/reference/cli" - }, - { - "source": "/api/cli/decompose/utils", - "destination": "/reference/cli" - }, - { - "source": "/api/cli/eval/commands", - "destination": "/reference/cli" - }, - { - "source": "/api/cli/eval/eval", - "destination": "/reference/cli" - }, - { - "source": "/api/cli/eval/runner", - "destination": "/reference/cli" - }, - { - "source": "/api/cli/serve/app", - "destination": "/reference/cli" - }, - { - "source": "/api/cli/serve/models", - "destination": "/reference/cli" - }, - { - "source": "/api/cli/fix/commands", - "destination": "/reference/cli" - }, - { - "source": "/api/cli/fix/async_fixer", - "destination": "/reference/cli" - }, - { - "source": "/api/cli/fix/genstub_fixer", - "destination": "/reference/cli" - }, - { - "source": "/guide/generative-functions", - "destination": "/how-to/generative-functions" - }, - { - "source": "/guide/tools-and-agents", - "destination": "/how-to/tools-and-agents" - }, - { - "source": "/guide/working-with-data", - "destination": "/how-to/working-with-data" - }, - { - "source": "/guide/backends-and-configuration", - "destination": "/how-to/backends-and-configuration" - }, - { - "source": "/evaluation-and-observability/evaluate-with-llm-as-a-judge", - "destination": "/how-to/evaluate-with-llm-as-a-judge" - }, - { - "source": "/evaluation-and-observability/telemetry", - "destination": "/observability/telemetry" - }, - { - "source": "/evaluation-and-observability/tracing", - "destination": "/observability/tracing" - }, - { - "source": "/evaluation-and-observability/metrics", - "destination": "/observability/metrics" - }, - { - "source": "/evaluation-and-observability/logging", - "destination": "/observability/logging" - }, - { - "source": "/guide/act-and-aact", - "destination": "/how-to/act-and-aact" - }, - { - "source": "/guide/m-decompose", - "destination": "/how-to/m-decompose" - }, - { - "source": "/advanced/security-and-taint-tracking", - "destination": "/how-to/safety-guardrails" - } - ] -} diff --git a/docs/docs/examples/_category_.json b/docs/docs/examples/_category_.json new file mode 100644 index 000000000..ed73bac4d --- /dev/null +++ b/docs/docs/examples/_category_.json @@ -0,0 +1 @@ +{"label": "Examples", "position": 5} diff --git a/docs/docs/examples/data-extraction-pipeline.md b/docs/docs/examples/data-extraction-pipeline.md index 86cee67cd..dd1070cd2 100644 --- a/docs/docs/examples/data-extraction-pipeline.md +++ b/docs/docs/examples/data-extraction-pipeline.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/examples/data-extraction-pipeline" title: "Data Extraction Pipeline" description: "Use the @generative decorator with a typed return value to extract structured data from unstructured text in a single declarative function." # diataxis: reference @@ -131,4 +130,4 @@ the function definition. --- -**See also:** [Enforce Structured Output](../how-to/enforce-structured-output) | [The Requirements System](../concepts/requirements-system) | [Examples Index](./index) +**See also:** [Enforce Structured Output](../how-to/enforce-structured-output) | [The Requirements System](../concepts/requirements-system) | [Examples Index](../examples) diff --git a/docs/docs/examples/index.md b/docs/docs/examples/index.md index 45b06d985..a24ec0f5f 100644 --- a/docs/docs/examples/index.md +++ b/docs/docs/examples/index.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/examples/index" title: "Examples" description: "Complete working programs demonstrating Mellea patterns in production-like scenarios." # diataxis: reference @@ -13,10 +12,10 @@ together. Copy any example as a starting point for your own project. | Example | What it shows | | ------- | ------------- | -| [Data extraction pipeline](./data-extraction-pipeline) | Use `@generative` with a typed return to pull structured data from unstructured text | -| [Legacy code integration](./legacy-code-integration) | Apply `@mify` to existing Python classes so the model can act on them | -| [Resilient RAG with fallback](./resilient-rag-fallback) | Build a FAISS retrieval pipeline with an LLM relevance filter before generation | -| [Traced generation loop](./traced-generation-loop) | Enable OpenTelemetry application and backend traces with two environment variables | +| [Data extraction pipeline](/examples/data-extraction-pipeline) | Use `@generative` with a typed return to pull structured data from unstructured text | +| [Legacy code integration](/examples/legacy-code-integration) | Apply `@mify` to existing Python classes so the model can act on them | +| [Resilient RAG with fallback](/examples/resilient-rag-fallback) | Build a FAISS retrieval pipeline with an LLM relevance filter before generation | +| [Traced generation loop](/examples/traced-generation-loop) | Enable OpenTelemetry application and backend traces with two environment variables | ## All example categories diff --git a/docs/docs/examples/legacy-code-integration.md b/docs/docs/examples/legacy-code-integration.md index 9ecde6c6a..8fb3c6ada 100644 --- a/docs/docs/examples/legacy-code-integration.md +++ b/docs/docs/examples/legacy-code-integration.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/examples/legacy-code-integration" title: "Legacy Code Integration with @mify" description: "Apply the @mify decorator to existing Python classes so a Mellea session can act on, query, and transform your objects without rewriting them." # diataxis: reference @@ -334,4 +333,4 @@ explicit. --- -**See also:** [MObjects and mify](../concepts/mobjects-and-mify) | [Tutorial 05: MIFYing Legacy Code](../tutorials/05-mifying-legacy-code) | [Examples Index](./index) +**See also:** [MObjects and mify](../concepts/mobjects-and-mify) | [Tutorial 05: MIFYing Legacy Code](../tutorials/mifying-legacy-code) | [Examples Index](../examples) diff --git a/docs/docs/examples/resilient-rag-fallback.md b/docs/docs/examples/resilient-rag-fallback.md index eecd10b48..7baff5ff3 100644 --- a/docs/docs/examples/resilient-rag-fallback.md +++ b/docs/docs/examples/resilient-rag-fallback.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/examples/resilient-rag-fallback" title: "Resilient RAG with Fallback Filtering" description: "Build a retrieval-augmented generation pipeline that uses FAISS for vector search and a @generative relevance filter to remove noise before generation." # diataxis: reference @@ -358,4 +357,4 @@ generate from the model's parametric knowledge. Passing documents through --- -**See also:** [Build a RAG Pipeline](../how-to/build-a-rag-pipeline) — step-by-step how-to guide | [Examples Index](./index) +**See also:** [Build a RAG Pipeline](../how-to/build-a-rag-pipeline) — step-by-step how-to guide | [Examples Index](../examples) diff --git a/docs/docs/examples/traced-generation-loop.md b/docs/docs/examples/traced-generation-loop.md index 5df2216fd..d2d9c1970 100644 --- a/docs/docs/examples/traced-generation-loop.md +++ b/docs/docs/examples/traced-generation-loop.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/examples/traced-generation-loop" title: "Traced Generation Loop" description: "Enable OpenTelemetry tracing for a multi-operation Mellea session using environment variables, and export spans to Jaeger or any OTLP backend." # diataxis: reference diff --git a/docs/docs/getting-started/_category_.json b/docs/docs/getting-started/_category_.json new file mode 100644 index 000000000..16e59f110 --- /dev/null +++ b/docs/docs/getting-started/_category_.json @@ -0,0 +1 @@ +{"label": "Getting Started", "position": 1} diff --git a/docs/docs/getting-started/installation.md b/docs/docs/getting-started/installation.md index d4a00be36..8166c47c4 100644 --- a/docs/docs/getting-started/installation.md +++ b/docs/docs/getting-started/installation.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/getting-started/installation" title: "Installation" description: "Install Mellea and set up your Python environment." # diataxis: tutorial diff --git a/docs/docs/getting-started/quickstart.md b/docs/docs/getting-started/quickstart.md index 60d5a4643..1e9f3dbd7 100644 --- a/docs/docs/getting-started/quickstart.md +++ b/docs/docs/getting-started/quickstart.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/getting-started/quickstart" title: "Quick Start" description: "Run your first generative program in minutes." # diataxis: tutorial diff --git a/docs/docs/how-to/_category_.json b/docs/docs/how-to/_category_.json new file mode 100644 index 000000000..eb0e9bdaa --- /dev/null +++ b/docs/docs/how-to/_category_.json @@ -0,0 +1 @@ +{"label": "How-To", "position": 4} diff --git a/docs/docs/how-to/act-and-aact.md b/docs/docs/how-to/act-and-aact.md index e76a67c34..568f2a270 100644 --- a/docs/docs/how-to/act-and-aact.md +++ b/docs/docs/how-to/act-and-aact.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/how-to/act-and-aact" title: "act() and aact()" description: "Work directly with Components using act(), aact(), and the functional API." # diataxis: how-to diff --git a/docs/docs/how-to/backends-and-configuration.md b/docs/docs/how-to/backends-and-configuration.md index 491b6c9a7..8113d3e02 100644 --- a/docs/docs/how-to/backends-and-configuration.md +++ b/docs/docs/how-to/backends-and-configuration.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/how-to/backends-and-configuration" title: "Backends and Configuration" description: "Configure Mellea to use Ollama, OpenAI, LiteLLM, HuggingFace, or WatsonX backends." # diataxis: how-to diff --git a/docs/docs/how-to/build-a-rag-pipeline.md b/docs/docs/how-to/build-a-rag-pipeline.md index 0d59c2a91..eb359be0e 100644 --- a/docs/docs/how-to/build-a-rag-pipeline.md +++ b/docs/docs/how-to/build-a-rag-pipeline.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/how-to/build-a-rag-pipeline" title: "Build a RAG Pipeline" description: "Combine vector retrieval with Mellea's generative filtering and grounded generation to build a reliable retrieval-augmented generation system." # diataxis: how-to @@ -303,4 +302,4 @@ def rag(docs: list[str], query: str, *, check_groundedness: bool = True) -> str --- -**See also:** [Resilient RAG with Fallback Filtering](../examples/resilient-rag-fallback) | [Making Agents Reliable](../tutorials/04-making-agents-reliable) | [The Requirements System](../concepts/requirements-system) +**See also:** [Resilient RAG with Fallback Filtering](../examples/resilient-rag-fallback) | [Making Agents Reliable](../tutorials/making-agents-reliable) | [The Requirements System](../concepts/requirements-system) diff --git a/docs/docs/how-to/configure-model-options.md b/docs/docs/how-to/configure-model-options.md index c1648729a..6caa4f16d 100644 --- a/docs/docs/how-to/configure-model-options.md +++ b/docs/docs/how-to/configure-model-options.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/how-to/configure-model-options" title: "Configure model options" description: "Set temperature, seed, max tokens, system prompts, and other backend parameters at session level or per call." # diataxis: how-to diff --git a/docs/docs/how-to/enforce-structured-output.md b/docs/docs/how-to/enforce-structured-output.md index 3a637a854..683d11d6d 100644 --- a/docs/docs/how-to/enforce-structured-output.md +++ b/docs/docs/how-to/enforce-structured-output.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/how-to/enforce-structured-output" title: "Enforce Structured Output" description: "Get JSON, Pydantic models, and typed values from LLM calls using @generative and instruct(format=...)." # diataxis: how-to diff --git a/docs/docs/how-to/evaluate-with-llm-as-a-judge.md b/docs/docs/how-to/evaluate-with-llm-as-a-judge.md index e64c47f84..f7bb56123 100644 --- a/docs/docs/how-to/evaluate-with-llm-as-a-judge.md +++ b/docs/docs/how-to/evaluate-with-llm-as-a-judge.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/how-to/evaluate-with-llm-as-a-judge" title: "Evaluate with LLM-as-a-Judge" description: "Use the LLM itself to evaluate output quality — inline as a requirement, or as a standalone validation pass." # diataxis: how-to diff --git a/docs/docs/how-to/generative-functions.md b/docs/docs/how-to/generative-functions.md index 5a3e9cbe1..7dba12814 100644 --- a/docs/docs/how-to/generative-functions.md +++ b/docs/docs/how-to/generative-functions.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/how-to/generative-functions" title: "Generative Functions" description: "Define type-safe LLM functions with @generative and Pydantic structured output." # diataxis: how-to diff --git a/docs/docs/how-to/handling-exceptions.md b/docs/docs/how-to/handling-exceptions.md index d61669349..813d1470a 100644 --- a/docs/docs/how-to/handling-exceptions.md +++ b/docs/docs/how-to/handling-exceptions.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/how-to/handling-exceptions" title: "Handling Exceptions and Failures" description: "Handle SamplingResult failures, PreconditionException, and parse errors gracefully in Mellea programs." # diataxis: how-to diff --git a/docs/docs/how-to/m-decompose.md b/docs/docs/how-to/m-decompose.md index 5892de44a..3074145ae 100644 --- a/docs/docs/how-to/m-decompose.md +++ b/docs/docs/how-to/m-decompose.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/how-to/m-decompose" title: "m decompose" description: "Break complex tasks into ordered, executable subtasks with the m decompose CLI." # diataxis: how-to diff --git a/docs/docs/how-to/refactor-prompts-with-cli.md b/docs/docs/how-to/refactor-prompts-with-cli.md index 460ceb3e1..fbd029082 100644 --- a/docs/docs/how-to/refactor-prompts-with-cli.md +++ b/docs/docs/how-to/refactor-prompts-with-cli.md @@ -1,7 +1,6 @@ --- -canonical: "https://docs.mellea.ai/how-to/refactor-prompts-with-cli" title: "Refactor Prompts with the CLI" -sidebarTitle: "Refactor with m decompose" +sidebar_label: "Refactor with m decompose" description: "Use m decompose to break a complex prompt into typed, validated generative functions." # diataxis: how-to --- diff --git a/docs/docs/how-to/safety-guardrails.md b/docs/docs/how-to/safety-guardrails.md index f68517e09..2577adeb8 100644 --- a/docs/docs/how-to/safety-guardrails.md +++ b/docs/docs/how-to/safety-guardrails.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/how-to/safety-guardrails" title: "Safety Guardrails" description: "Use Guardian Intrinsics to detect harmful, biased, ungrounded, or policy-violating content in LLM outputs." # diataxis: how-to @@ -340,4 +339,4 @@ Guardian functions also do not emit `mellea.requirement` metrics — see > [`factuality_correction.py`](https://github.com/generative-computing/mellea/blob/main/docs/examples/intrinsics/factuality_correction.py), > and [`policy_guardrails.py`](https://github.com/generative-computing/mellea/blob/main/docs/examples/intrinsics/policy_guardrails.py). -**See also:** [Intrinsics](../advanced/intrinsics) | [LoRA and aLoRA Adapters](../advanced/lora-and-alora-adapters) | [Tutorial: Making Agents Reliable](../tutorials/04-making-agents-reliable) +**See also:** [Intrinsics](../advanced/intrinsics) | [LoRA and aLoRA Adapters](../advanced/lora-and-alora-adapters) | [Tutorial: Making Agents Reliable](../tutorials/making-agents-reliable) diff --git a/docs/docs/how-to/tools-and-agents.md b/docs/docs/how-to/tools-and-agents.md index d836db297..2c6a41bbf 100644 --- a/docs/docs/how-to/tools-and-agents.md +++ b/docs/docs/how-to/tools-and-agents.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/how-to/tools-and-agents" title: "Tools and Agents" description: "Give LLMs access to tools, build ReACT agents, and validate tool call arguments." # diataxis: how-to @@ -317,4 +316,4 @@ for a complete example against the hosted GitHub MCP server. --- -**See also:** [Tutorial 04: Making Agents Reliable](../tutorials/04-making-agents-reliable) | [Instruct, Validate, Repair](../concepts/instruct-validate-repair) +**See also:** [Tutorial 04: Making Agents Reliable](../tutorials/making-agents-reliable) | [Instruct, Validate, Repair](../concepts/instruct-validate-repair) diff --git a/docs/docs/how-to/unit-test-generative-code.md b/docs/docs/how-to/unit-test-generative-code.md index a08355edb..da561c55a 100644 --- a/docs/docs/how-to/unit-test-generative-code.md +++ b/docs/docs/how-to/unit-test-generative-code.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/how-to/unit-test-generative-code" title: "Unit Test Generative Code" description: "Write reliable tests for @generative functions using pytest markers and output validation." # diataxis: how-to @@ -436,5 +435,5 @@ pytest -m qualitative `Requirement`, `simple_validate`, and `check` interact with the IVR loop - [Handling Exceptions](../how-to/handling-exceptions) — catch and diagnose errors that occur during generation -- [Evaluate with LLM-as-a-Judge](../evaluation-and-observability/evaluate-with-llm-as-a-judge) — +- [Evaluate with LLM-as-a-Judge](/how-to/evaluate-with-llm-as-a-judge) — the `Requirement`-based approach for inline judge evaluation diff --git a/docs/docs/how-to/use-async-and-streaming.md b/docs/docs/how-to/use-async-and-streaming.md index 853e99f65..ab7f00e2e 100644 --- a/docs/docs/how-to/use-async-and-streaming.md +++ b/docs/docs/how-to/use-async-and-streaming.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/how-to/use-async-and-streaming" title: "Async and Streaming" description: "Use async methods, parallel generation, and streaming output with Mellea." # diataxis: how-to @@ -299,4 +298,4 @@ requirement (both `"pass"` and `"unknown"`). This means `"pass"` from --- -**See also:** [Tutorial 02: Streaming and Async](../tutorials/02-streaming-and-async) | [act() and aact()](../how-to/act-and-aact) +**See also:** [Tutorial 02: Streaming and Async](../tutorials/streaming-and-async) | [act() and aact()](../how-to/act-and-aact) diff --git a/docs/docs/how-to/use-context-and-sessions.md b/docs/docs/how-to/use-context-and-sessions.md index a8f4aeec7..2b1039b9e 100644 --- a/docs/docs/how-to/use-context-and-sessions.md +++ b/docs/docs/how-to/use-context-and-sessions.md @@ -1,7 +1,6 @@ --- -canonical: "https://docs.mellea.ai/how-to/use-context-and-sessions" title: "Context and Sessions" -sidebarTitle: "Extending Sessions" +sidebar_label: "Extending Sessions" description: "Extend MelleaSession to add custom validation, logging, and filtering behavior." # diataxis: how-to --- diff --git a/docs/docs/how-to/use-images-and-vision.md b/docs/docs/how-to/use-images-and-vision.md index ba3f006c9..00697bad2 100644 --- a/docs/docs/how-to/use-images-and-vision.md +++ b/docs/docs/how-to/use-images-and-vision.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/how-to/use-images-and-vision" title: "Use Images and Vision Models" description: "Pass images to instruct() and chat() calls, and configure vision-capable backends." # diataxis: how-to diff --git a/docs/docs/how-to/working-with-data.md b/docs/docs/how-to/working-with-data.md index 659616b7c..94a993d8b 100644 --- a/docs/docs/how-to/working-with-data.md +++ b/docs/docs/how-to/working-with-data.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/how-to/working-with-data" title: "Working with Data" description: "Ground instructions with documents, build RAG pipelines, and use MObjects and RichDocument." # diataxis: how-to diff --git a/docs/docs/how-to/write-custom-verifiers.md b/docs/docs/how-to/write-custom-verifiers.md index ea1dee2eb..62456e79b 100644 --- a/docs/docs/how-to/write-custom-verifiers.md +++ b/docs/docs/how-to/write-custom-verifiers.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/how-to/write-custom-verifiers" title: "Write Custom Verifiers" description: "Write validation functions that inspect LLM output and return pass/fail results with repair guidance." # diataxis: how-to diff --git a/docs/docs/index.mdx b/docs/docs/index.mdx index 5314d83c3..fcbe02141 100644 --- a/docs/docs/index.mdx +++ b/docs/docs/index.mdx @@ -1,16 +1,14 @@ --- -canonical: "https://docs.mellea.ai/" title: "Mellea — build predictable AI without guesswork" description: "A Python library for writing reliable generative programs." --- -
- Mellea mascot -

Mellea helps you manage the unreliable part of every AI-powered pipeline: the LLM call itself. - It replaces ad-hoc prompt chains and brittle agents with structured - generative programs — Python code where LLM calls are first-class operations - governed by type annotations, requirement verifiers, and principled repair loops.

-
+![Mellea mascot](/images/mellea_draft_logo_300.png) + +Mellea helps you manage the unreliable part of every AI-powered pipeline: the LLM call itself. +It replaces ad-hoc prompt chains and brittle agents with structured +*generative programs* — Python code where LLM calls are first-class operations +governed by type annotations, requirement verifiers, and principled repair loops. ```bash uv pip install mellea diff --git a/docs/docs/integrations/_category_.json b/docs/docs/integrations/_category_.json new file mode 100644 index 000000000..9c5bbe5e6 --- /dev/null +++ b/docs/docs/integrations/_category_.json @@ -0,0 +1 @@ +{"label": "Integrations", "position": 6} diff --git a/docs/docs/integrations/bedrock.md b/docs/docs/integrations/bedrock.md index c3ee206f4..65b62bcbf 100644 --- a/docs/docs/integrations/bedrock.md +++ b/docs/docs/integrations/bedrock.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/integrations/bedrock" title: "AWS Bedrock" description: "Run Mellea with AWS Bedrock models using the Bedrock Mantle backend or LiteLLM." # diataxis: how-to diff --git a/docs/docs/integrations/huggingface.md b/docs/docs/integrations/huggingface.md index bfb4b3de3..a46bfeed9 100644 --- a/docs/docs/integrations/huggingface.md +++ b/docs/docs/integrations/huggingface.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/integrations/huggingface" title: "HuggingFace Transformers" description: "Run Mellea on local hardware with LocalHFBackend and HuggingFace Transformers." # diataxis: how-to diff --git a/docs/docs/integrations/langchain.md b/docs/docs/integrations/langchain.md index c4d893b18..d1617499c 100644 --- a/docs/docs/integrations/langchain.md +++ b/docs/docs/integrations/langchain.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/integrations/langchain" title: "LangChain" description: "Use LangChain tools inside Mellea and seed a Mellea session with LangChain message history." # diataxis: how-to diff --git a/docs/docs/integrations/m-serve.md b/docs/docs/integrations/m-serve.md index 0096ff3e8..99643ffef 100644 --- a/docs/docs/integrations/m-serve.md +++ b/docs/docs/integrations/m-serve.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/integrations/m-serve" title: "m serve" description: "Run a Mellea program as an OpenAI-compatible chat endpoint with m serve." # diataxis: how-to diff --git a/docs/docs/integrations/mcp.md b/docs/docs/integrations/mcp.md index 58f33a68e..8523fb850 100644 --- a/docs/docs/integrations/mcp.md +++ b/docs/docs/integrations/mcp.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/integrations/mcp" title: "MCP Integration" description: "Expose Mellea functions as Model Context Protocol tools, callable from Claude Desktop, Cursor, and any MCP-compatible client." # diataxis: how-to diff --git a/docs/docs/integrations/ollama.md b/docs/docs/integrations/ollama.md index 4a8b70a09..af34af099 100644 --- a/docs/docs/integrations/ollama.md +++ b/docs/docs/integrations/ollama.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/integrations/ollama" title: "Ollama" description: "Run Mellea with local models via Ollama — the default backend." # diataxis: how-to diff --git a/docs/docs/integrations/openai.md b/docs/docs/integrations/openai.md index 317c32974..fba32f261 100644 --- a/docs/docs/integrations/openai.md +++ b/docs/docs/integrations/openai.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/integrations/openai" title: "OpenAI and OpenAI-Compatible APIs" description: "Use Mellea with OpenAI's API and any OpenAI-compatible endpoint — LM Studio, vLLM, Anthropic, and more." # diataxis: how-to diff --git a/docs/docs/integrations/smolagents.md b/docs/docs/integrations/smolagents.md index 5cf4daeb8..54e5f75a7 100644 --- a/docs/docs/integrations/smolagents.md +++ b/docs/docs/integrations/smolagents.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/integrations/smolagents" title: "smolagents" description: "Use HuggingFace smolagents tools inside a Mellea session." # diataxis: how-to diff --git a/docs/docs/integrations/vertex-ai.md b/docs/docs/integrations/vertex-ai.md index a620e41e4..c52b7f447 100644 --- a/docs/docs/integrations/vertex-ai.md +++ b/docs/docs/integrations/vertex-ai.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/integrations/vertex-ai" title: "Vertex AI" description: "Connect Mellea to Google Vertex AI models via LiteLLM." # diataxis: how-to diff --git a/docs/docs/integrations/watsonx.md b/docs/docs/integrations/watsonx.md index b65a79bcb..4bdb91569 100644 --- a/docs/docs/integrations/watsonx.md +++ b/docs/docs/integrations/watsonx.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/integrations/watsonx" title: "IBM WatsonX" description: "Run Mellea with IBM WatsonX AI using the WatsonxAIBackend." # diataxis: how-to diff --git a/docs/docs/observability/_category_.json b/docs/docs/observability/_category_.json new file mode 100644 index 000000000..cca9d522b --- /dev/null +++ b/docs/docs/observability/_category_.json @@ -0,0 +1 @@ +{"label": "Observability", "position": 7} diff --git a/docs/docs/observability/logging.md b/docs/docs/observability/logging.md index 9910b3108..0a69720c6 100644 --- a/docs/docs/observability/logging.md +++ b/docs/docs/observability/logging.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/observability/logging" title: "Logging" description: "Configure Mellea's console logging and export logs to OTLP collectors." # diataxis: how-to diff --git a/docs/docs/observability/metrics.md b/docs/docs/observability/metrics.md index 70e751618..1f3363ca9 100644 --- a/docs/docs/observability/metrics.md +++ b/docs/docs/observability/metrics.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/observability/metrics" title: "Metrics" description: "Automatically collect LLM metrics and instrument your own code with OpenTelemetry counters, histograms, and up-down counters." # diataxis: how-to diff --git a/docs/docs/observability/telemetry.md b/docs/docs/observability/telemetry.md index ce9e46e98..bd461e556 100644 --- a/docs/docs/observability/telemetry.md +++ b/docs/docs/observability/telemetry.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/observability/telemetry" title: "Telemetry" description: "Add OpenTelemetry tracing, metrics, and logging to Mellea programs." # diataxis: how-to diff --git a/docs/docs/observability/tracing.md b/docs/docs/observability/tracing.md index eadaf7d0a..96fba56c8 100644 --- a/docs/docs/observability/tracing.md +++ b/docs/docs/observability/tracing.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/observability/tracing" title: "Tracing" description: "Export distributed traces from Mellea using OpenTelemetry semantic conventions." # diataxis: how-to diff --git a/docs/docs/reference/_category_.json b/docs/docs/reference/_category_.json new file mode 100644 index 000000000..1d47a2e6e --- /dev/null +++ b/docs/docs/reference/_category_.json @@ -0,0 +1 @@ +{"label": "Reference", "position": 10} diff --git a/docs/docs/reference/glossary.md b/docs/docs/reference/glossary.md index 3ee9604b6..fb9903086 100644 --- a/docs/docs/reference/glossary.md +++ b/docs/docs/reference/glossary.md @@ -1,5 +1,4 @@ --- -canonical: "https://docs.mellea.ai/reference/glossary" title: "Glossary" description: "Definitions of Mellea-specific terms and concepts." # diataxis: reference @@ -19,7 +18,7 @@ when working with custom components or building your own inference loops. `aact()` is the async counterpart — same signature, same return types. -See: [act() and aact()](./act-and-aact) +See: [act() and aact()](/how-to/act-and-aact) --- @@ -53,7 +52,7 @@ m = start_session() lang = classify_language(m, code="print('hello')") ``` -See: [Generative Functions](./generative-functions) +See: [Generative Functions](/how-to/generative-functions) --- @@ -63,7 +62,7 @@ A backend is an inference engine that Mellea uses to run LLM calls. Examples: `OllamaModelBackend`, `OpenAIBackend`, `LocalHFBackend`, `WatsonxAIBackend`. Backends are configured via `MelleaSession` or `start_session()`. -See: [Backends and Configuration](./backends-and-configuration) +See: [Backends and Configuration](/how-to/backends-and-configuration) --- @@ -171,7 +170,7 @@ annotation as the output schema and its docstring as the prompt. Generative functions are called with a `MelleaSession` as the first argument and return the annotated type. -See: [Generative Functions](./generative-functions) +See: [Generative Functions](/how-to/generative-functions) --- @@ -437,7 +436,7 @@ m = mellea.start_session( ) ``` -See: [Backends and Configuration](./backends-and-configuration) +See: [Backends and Configuration](/how-to/backends-and-configuration) --- @@ -668,7 +667,7 @@ from mellea.stdlib.frameworks.react import react result, _ = await react(goal="...", context=ChatContext(), backend=m.backend, tools=[...]) ``` -See: [Tools and Agents](./tools-and-agents) +See: [Tools and Agents](/how-to/tools-and-agents) --- @@ -705,7 +704,7 @@ to make PDFs, tables, and structured files queryable by the LLM. Extract tables pip install 'mellea[docling]' ``` -See: [Working with Data](./working-with-data) +See: [Working with Data](/how-to/working-with-data) --- @@ -787,7 +786,7 @@ tables = rich_doc.get_tables() summary = m.query(tables[0], "What is the total in the last row?") ``` -See: [Working with Data](./working-with-data) +See: [Working with Data](/how-to/working-with-data) --- @@ -847,7 +846,7 @@ A Python function decorated with `@tool` (or registered via `MelleaSession`) tha Mellea exposes to an LLM for function calling. Tools have typed inputs and outputs so the LLM can call them reliably without free-form parsing. -See: [Tools and Agents](./tools-and-agents) +See: [Tools and Agents](/how-to/tools-and-agents) --- @@ -893,4 +892,4 @@ Total wall-clock time is roughly the latency of the slowest single call rather than the sum of all calls. Use `SimpleContext` (the default) when calling `wait_for_all_mots`; concurrent writes to `ChatContext` can corrupt state. -See: [Tutorial 02: Streaming and Async](../tutorials/02-streaming-and-async) +See: [Tutorial 02: Streaming and Async](/tutorials/streaming-and-async) diff --git a/docs/docs/snippets/Divider.mdx b/docs/docs/snippets/Divider.mdx deleted file mode 100644 index f2e6a5a08..000000000 --- a/docs/docs/snippets/Divider.mdx +++ /dev/null @@ -1,3 +0,0 @@ -export const Divider = () => ( -
-); diff --git a/docs/docs/snippets/SidebarFix.mdx b/docs/docs/snippets/SidebarFix.mdx deleted file mode 100644 index ddb73710c..000000000 --- a/docs/docs/snippets/SidebarFix.mdx +++ /dev/null @@ -1,89 +0,0 @@ -export const SidebarFix = () => ( -