From 5b46802cdfe19935b1d0d8cea512b6e2d10a27c9 Mon Sep 17 00:00:00 2001 From: Will Killian Date: Sun, 17 May 2026 22:15:39 -0400 Subject: [PATCH 1/6] docs: switch over to fern Signed-off-by: Will Killian --- .github/ISSUE_TEMPLATE/03-documentation.yml | 2 +- .github/ci-path-filters.yml | 7 +- .github/workflows/ci.yaml | 34 +- .github/workflows/ci_docs.yml | 60 +- .gitignore | 8 +- .pre-commit-config.yaml | 26 +- AGENTS.md | 8 +- ATTRIBUTIONS-Node.md | 741 ++++- ATTRIBUTIONS-Python.md | 2935 +---------------- CONTRIBUTING.md | 12 +- RELEASING.md | 42 +- docs/_static/extra.css | 1336 -------- docs/_static/version-switcher.js | 51 - docs/_templates/version-switcher.html | 125 - .../{architecture.md => architecture.mdx} | 27 +- docs/about/concepts/{events.md => events.mdx} | 13 +- ...grations.md => framework-integrations.mdx} | 17 +- docs/about/concepts/index.md | 67 - docs/about/concepts/index.mdx | 43 + .../{middleware.md => middleware.mdx} | 17 +- .../concepts/{plugins.md => plugins.mdx} | 25 +- docs/about/concepts/{scopes.md => scopes.mdx} | 13 +- .../{subscribers.md => subscribers.mdx} | 21 +- docs/about/{ecosystem.md => ecosystem.mdx} | 27 +- docs/about/overview.mdx | 127 + .../{highlights.md => highlights.mdx} | 13 +- .../release-notes/{index.md => index.mdx} | 21 +- .../{known-issues.md => known-issues.mdx} | 14 +- docs/about/release-notes/related-topics.md | 11 - docs/about/release-notes/related-topics.mdx | 12 + docs/build-plugins/{about.md => about.mdx} | 27 +- ...guration.md => advanced-configuration.mdx} | 21 +- .../{basic-guide.md => basic-guide.mdx} | 28 +- .../{code-examples.md => code-examples.mdx} | 53 +- .../{nemoguardrails.md => nemoguardrails.mdx} | 19 +- ...iles.md => plugin-configuration-files.mdx} | 26 +- ...ster-behavior.md => register-behavior.mdx} | 71 +- ...guration.md => validate-configuration.mdx} | 65 +- docs/conf.py | 710 ---- docs/contribute/{about.md => about.mdx} | 29 +- ...lopment-setup.md => development-setup.mdx} | 15 +- ...sting-and-docs.md => testing-and-docs.mdx} | 17 +- ...nd-reviews.md => workflow-and-reviews.mdx} | 17 +- .../{configuration.md => configuration.mdx} | 24 +- .../{installation.md => installation.mdx} | 19 +- .../{prerequisites.md => prerequisites.mdx} | 23 +- docs/getting-started/quick-start.md | 16 - docs/getting-started/quick-start/index.mdx | 9 + .../{nodejs.md => quick-start/nodejs.mdx} | 23 +- .../index.md => quick-start/python.mdx} | 30 +- .../{rust.md => quick-start/rust.mdx} | 15 +- docs/index.md | 282 -- docs/index.yml | 52 + .../{about.md => about.mdx} | 25 +- ...d-marks.md => adding-scopes-and-marks.mdx} | 50 +- .../{advanced-guide.md => advanced-guide.mdx} | 48 +- .../{code-examples.md => code-examples.mdx} | 137 +- ...nt-llm-call.md => instrument-llm-call.mdx} | 59 +- ...-tool-call.md => instrument-tool-call.mdx} | 60 +- .../{about.md => about.mdx} | 35 +- .../{adding-scopes.md => adding-scopes.mdx} | 44 +- .../{code-examples.md => code-examples.mdx} | 127 +- ...able-data.md => non-serializable-data.mdx} | 50 +- ...provider-codecs.md => provider-codecs.mdx} | 70 +- ...codecs.md => provider-response-codecs.mdx} | 66 +- .../{using-codecs.md => using-codecs.mdx} | 63 +- .../{wrap-llm-calls.md => wrap-llm-calls.mdx} | 48 +- ...wrap-tool-calls.md => wrap-tool-calls.mdx} | 49 +- docs/integrations/{about.md => about.mdx} | 23 +- .../{deepagents.md => deepagents.mdx} | 52 +- .../{langchain.md => langchain.mdx} | 54 +- .../{langgraph.md => langgraph.mdx} | 56 +- ...openclaw-plugin.md => openclaw-plugin.mdx} | 20 +- docs/nemo-flow-cli/{about.md => about.mdx} | 29 +- .../{basic-usage.md => basic-usage.mdx} | 21 +- .../{claude-code.md => claude-code.mdx} | 13 +- docs/nemo-flow-cli/{codex.md => codex.mdx} | 18 +- docs/nemo-flow-cli/{cursor.md => cursor.mdx} | 18 +- docs/nemo-flow-cli/{hermes.md => hermes.mdx} | 13 +- docs/plugins/adaptive/{about.md => about.mdx} | 26 +- docs/plugins/adaptive/{acg.md => acg.mdx} | 63 +- .../{adaptive-hints.md => adaptive-hints.mdx} | 65 +- .../{configuration.md => configuration.mdx} | 74 +- .../observability/{about.md => about.mdx} | 34 +- .../observability/{atif.md => atif.mdx} | 65 +- .../observability/{atof.md => atof.mdx} | 67 +- .../{configuration.md => configuration.mdx} | 47 +- .../{openinference.md => openinference.mdx} | 67 +- .../{opentelemetry.md => opentelemetry.mdx} | 65 +- docs/reference/api/index.md | 17 - docs/reference/api/index.mdx | 13 + docs/reference/api/nodejs/index.md | 74 - docs/reference/api/python/index.md | 75 - docs/reference/api/rust/index.md | 82 - .../{performance.md => performance.mdx} | 21 +- docs/resources/community.md | 21 - docs/resources/community.mdx | 22 + docs/resources/glossary.md | 426 --- docs/resources/glossary.mdx | 301 ++ docs/resources/legal/index.md | 15 - docs/resources/legal/index.mdx | 9 + ...nse-agreement.md => license-agreement.mdx} | 13 +- docs/resources/legal/oss.md | 16 - docs/resources/legal/oss.mdx | 18 + ...pport-and-faqs.md => support-and-faqs.mdx} | 148 +- .../troubleshooting/index.mdx} | 59 +- docs/typedoc.node.json | 8 - docs/typedoc.node.tsconfig.json | 10 - examples/nemoguardrails/README.md | 2 +- fern/assets/NVIDIA_dark.svg | 37 + fern/assets/NVIDIA_light.svg | 36 + fern/assets/NVIDIA_symbol.svg | 24 + fern/components/Authors.tsx | 56 + fern/components/BadgeLinks.tsx | 37 + fern/components/CustomFooter.tsx | 96 + fern/components/MetricsTable.tsx | 106 + fern/components/NotebookViewer.tsx | 399 +++ fern/components/TrajectoryViewer.tsx | 144 + fern/docs.yml | 49 + fern/fern.config.json | 4 + fern/main.css | 1658 ++++++++++ justfile | 50 +- package-lock.json | 198 ++ package.json | 1 + pyproject.toml | 16 +- scripts/README.md | 4 +- scripts/build-docs.sh | 11 +- scripts/docs/build_node_docs_artifacts.mjs | 521 --- scripts/docs/fern_cleanup.py | 419 +++ .../docs/generate_node_library_reference.py | 465 +++ .../docs/generate_python_library_reference.py | 429 +++ .../docs/generate_rust_library_reference.py | 558 ++++ .../docs/postprocess_sphinx_multiversion.py | 180 - scripts/docs/reference_common.py | 71 + uv.lock | 570 +--- 135 files changed, 7350 insertions(+), 9406 deletions(-) delete mode 100644 docs/_static/extra.css delete mode 100644 docs/_static/version-switcher.js delete mode 100644 docs/_templates/version-switcher.html rename docs/about/{architecture.md => architecture.mdx} (91%) rename docs/about/concepts/{events.md => events.mdx} (93%) rename docs/about/concepts/{framework-integrations.md => framework-integrations.mdx} (93%) delete mode 100644 docs/about/concepts/index.md create mode 100644 docs/about/concepts/index.mdx rename docs/about/concepts/{middleware.md => middleware.mdx} (97%) rename docs/about/concepts/{plugins.md => plugins.mdx} (90%) rename docs/about/concepts/{scopes.md => scopes.mdx} (95%) rename docs/about/concepts/{subscribers.md => subscribers.mdx} (89%) rename docs/about/{ecosystem.md => ecosystem.mdx} (91%) create mode 100644 docs/about/overview.mdx rename docs/about/release-notes/{highlights.md => highlights.mdx} (60%) rename docs/about/release-notes/{index.md => index.mdx} (58%) rename docs/about/release-notes/{known-issues.md => known-issues.mdx} (77%) delete mode 100644 docs/about/release-notes/related-topics.md create mode 100644 docs/about/release-notes/related-topics.mdx rename docs/build-plugins/{about.md => about.mdx} (55%) rename docs/build-plugins/{advanced-configuration.md => advanced-configuration.mdx} (91%) rename docs/build-plugins/{basic-guide.md => basic-guide.mdx} (90%) rename docs/build-plugins/{code-examples.md => code-examples.mdx} (91%) rename docs/build-plugins/{nemoguardrails.md => nemoguardrails.mdx} (94%) rename docs/build-plugins/{plugin-configuration-files.md => plugin-configuration-files.mdx} (94%) rename docs/build-plugins/{register-behavior.md => register-behavior.mdx} (92%) rename docs/build-plugins/{validate-configuration.md => validate-configuration.mdx} (86%) delete mode 100644 docs/conf.py rename docs/contribute/{about.md => about.mdx} (52%) rename docs/contribute/{development-setup.md => development-setup.mdx} (87%) rename docs/contribute/{testing-and-docs.md => testing-and-docs.mdx} (84%) rename docs/contribute/{workflow-and-reviews.md => workflow-and-reviews.mdx} (84%) rename docs/getting-started/{configuration.md => configuration.mdx} (73%) rename docs/getting-started/{installation.md => installation.mdx} (84%) rename docs/getting-started/{prerequisites.md => prerequisites.mdx} (50%) delete mode 100644 docs/getting-started/quick-start.md create mode 100644 docs/getting-started/quick-start/index.mdx rename docs/getting-started/{nodejs.md => quick-start/nodejs.mdx} (83%) rename docs/getting-started/{python/index.md => quick-start/python.mdx} (84%) rename docs/getting-started/{rust.md => quick-start/rust.mdx} (86%) delete mode 100644 docs/index.md create mode 100644 docs/index.yml rename docs/instrument-applications/{about.md => about.mdx} (58%) rename docs/instrument-applications/{adding-scopes-and-marks.md => adding-scopes-and-marks.mdx} (86%) rename docs/instrument-applications/{advanced-guide.md => advanced-guide.mdx} (89%) rename docs/instrument-applications/{code-examples.md => code-examples.mdx} (89%) rename docs/instrument-applications/{instrument-llm-call.md => instrument-llm-call.mdx} (88%) rename docs/instrument-applications/{instrument-tool-call.md => instrument-tool-call.mdx} (84%) rename docs/integrate-frameworks/{about.md => about.mdx} (56%) rename docs/integrate-frameworks/{adding-scopes.md => adding-scopes.mdx} (90%) rename docs/integrate-frameworks/{code-examples.md => code-examples.mdx} (85%) rename docs/integrate-frameworks/{non-serializable-data.md => non-serializable-data.mdx} (86%) rename docs/integrate-frameworks/{provider-codecs.md => provider-codecs.mdx} (91%) rename docs/integrate-frameworks/{provider-response-codecs.md => provider-response-codecs.mdx} (92%) rename docs/integrate-frameworks/{using-codecs.md => using-codecs.mdx} (82%) rename docs/integrate-frameworks/{wrap-llm-calls.md => wrap-llm-calls.mdx} (86%) rename docs/integrate-frameworks/{wrap-tool-calls.md => wrap-tool-calls.mdx} (85%) rename docs/integrations/{about.md => about.mdx} (68%) rename docs/integrations/{deepagents.md => deepagents.mdx} (81%) rename docs/integrations/{langchain.md => langchain.mdx} (73%) rename docs/integrations/{langgraph.md => langgraph.mdx} (76%) rename docs/integrations/{openclaw-plugin.md => openclaw-plugin.mdx} (97%) rename docs/nemo-flow-cli/{about.md => about.mdx} (72%) rename docs/nemo-flow-cli/{basic-usage.md => basic-usage.mdx} (96%) rename docs/nemo-flow-cli/{claude-code.md => claude-code.mdx} (95%) rename docs/nemo-flow-cli/{codex.md => codex.mdx} (96%) rename docs/nemo-flow-cli/{cursor.md => cursor.mdx} (96%) rename docs/nemo-flow-cli/{hermes.md => hermes.mdx} (95%) rename docs/plugins/adaptive/{about.md => about.mdx} (69%) rename docs/plugins/adaptive/{acg.md => acg.mdx} (92%) rename docs/plugins/adaptive/{adaptive-hints.md => adaptive-hints.mdx} (92%) rename docs/plugins/adaptive/{configuration.md => configuration.mdx} (91%) rename docs/plugins/observability/{about.md => about.mdx} (67%) rename docs/plugins/observability/{atif.md => atif.mdx} (91%) rename docs/plugins/observability/{atof.md => atof.mdx} (88%) rename docs/plugins/observability/{configuration.md => configuration.mdx} (95%) rename docs/plugins/observability/{openinference.md => openinference.mdx} (92%) rename docs/plugins/observability/{opentelemetry.md => opentelemetry.mdx} (92%) delete mode 100644 docs/reference/api/index.md create mode 100644 docs/reference/api/index.mdx delete mode 100644 docs/reference/api/nodejs/index.md delete mode 100644 docs/reference/api/python/index.md delete mode 100644 docs/reference/api/rust/index.md rename docs/reference/{performance.md => performance.mdx} (73%) delete mode 100644 docs/resources/community.md create mode 100644 docs/resources/community.mdx delete mode 100644 docs/resources/glossary.md create mode 100644 docs/resources/glossary.mdx delete mode 100644 docs/resources/legal/index.md create mode 100644 docs/resources/legal/index.mdx rename docs/resources/legal/{license-agreement.md => license-agreement.mdx} (52%) delete mode 100644 docs/resources/legal/oss.md create mode 100644 docs/resources/legal/oss.mdx rename docs/resources/{support-and-faqs.md => support-and-faqs.mdx} (77%) rename docs/{troubleshooting/troubleshooting-guide.md => resources/troubleshooting/index.mdx} (63%) delete mode 100644 docs/typedoc.node.json delete mode 100644 docs/typedoc.node.tsconfig.json create mode 100644 fern/assets/NVIDIA_dark.svg create mode 100644 fern/assets/NVIDIA_light.svg create mode 100644 fern/assets/NVIDIA_symbol.svg create mode 100644 fern/components/Authors.tsx create mode 100644 fern/components/BadgeLinks.tsx create mode 100644 fern/components/CustomFooter.tsx create mode 100644 fern/components/MetricsTable.tsx create mode 100644 fern/components/NotebookViewer.tsx create mode 100644 fern/components/TrajectoryViewer.tsx create mode 100644 fern/docs.yml create mode 100644 fern/fern.config.json create mode 100644 fern/main.css delete mode 100644 scripts/docs/build_node_docs_artifacts.mjs create mode 100644 scripts/docs/fern_cleanup.py create mode 100644 scripts/docs/generate_node_library_reference.py create mode 100644 scripts/docs/generate_python_library_reference.py create mode 100644 scripts/docs/generate_rust_library_reference.py delete mode 100644 scripts/docs/postprocess_sphinx_multiversion.py create mode 100644 scripts/docs/reference_common.py diff --git a/.github/ISSUE_TEMPLATE/03-documentation.yml b/.github/ISSUE_TEMPLATE/03-documentation.yml index 8147f036..b0d94402 100644 --- a/.github/ISSUE_TEMPLATE/03-documentation.yml +++ b/.github/ISSUE_TEMPLATE/03-documentation.yml @@ -40,7 +40,7 @@ body: description: Link to pages or list file paths. Enter N/A if you are not sure. placeholder: | - https://... - - docs/... + - fern/... validations: {required: true} - type: textarea id: proposed_change diff --git a/.github/ci-path-filters.yml b/.github/ci-path-filters.yml index e6dcf43a..33f224a5 100644 --- a/.github/ci-path-filters.yml +++ b/.github/ci-path-filters.yml @@ -97,12 +97,17 @@ dependencies: docs: - 'CONTRIBUTING.md' - 'README.md' + - 'Cargo.lock' + - 'Cargo.toml' - 'crates/adaptive/src/**' - 'crates/core/src/**' + - 'crates/ffi/src/**' - 'crates/node/*.d.ts' - 'crates/node/*.js' + - 'crates/node/package.json' + - 'crates/*/Cargo.toml' - 'crates/**/*.md' - - 'docs/**' + - 'fern/**' - 'integrations/coding-agents/**' - 'python/nemo_flow/**' - 'scripts/build-docs.sh' diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 29890de1..5fc738c4 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -29,7 +29,6 @@ jobs: && !cancelled() && needs.prepare.result == 'success' && needs.ci_required.result == 'success' - && needs.prepare.outputs.publish_docs != 'true' }} permissions: contents: read @@ -74,22 +73,17 @@ jobs: run: | set -euo pipefail full_ci=false - publish_docs=false publish_packages=false if [[ "$REF_TYPE" == "tag" || "$REF_NAME" == "$DEFAULT_BRANCH" ]]; then full_ci=true fi - if [[ "$REF_TYPE" == "tag" ]]; then - publish_docs=true - fi if [[ "$REF_TYPE" == "tag" && ! "$REF_NAME" =~ -alpha\.[0-9]+$ ]]; then publish_packages=true fi { printf 'full_ci=%s\n' "$full_ci" - printf 'publish_docs=%s\n' "$publish_docs" printf 'publish_packages=%s\n' "$publish_packages" } >> "$GITHUB_OUTPUT" @@ -98,7 +92,6 @@ jobs: is_pr: ${{ startsWith(github.ref_name, 'pull-request/') }} is_main_branch: ${{ github.ref_name == 'main' }} has_skip_ci_label: ${{ steps.get-pr-info.outcome == 'success' && contains(fromJSON(steps.get-pr-info.outputs.pr-info).labels.*.name, 'skip-ci') || false }} - publish_docs: ${{ steps.policy.outputs.publish_docs }} publish_packages: ${{ steps.policy.outputs.publish_packages }} pr_info: ${{ steps.get-pr-info.outcome == 'success' && steps.get-pr-info.outputs.pr-info || '' }} @@ -157,10 +150,6 @@ jobs: }} permissions: contents: read - with: - ref_type: ${{ github.ref_type }} - ref_name: ${{ github.ref_name }} - publish_docs: ${{ needs.prepare.outputs.publish_docs == 'true' }} ci_rust: name: Rust @@ -254,7 +243,6 @@ jobs: NODE_RESULT: ${{ needs.ci_node.result }} PYTHON_RESULT: ${{ needs.ci_python.result }} WEBASSEMBLY_RESULT: ${{ needs.ci_wasm.result }} - publish_docs: ${{ needs.prepare.outputs.publish_docs }} publish_packages: ${{ needs.prepare.outputs.publish_packages }} run: | set -euo pipefail @@ -281,11 +269,7 @@ jobs: require_success "Changes" "$CHANGES_RESULT" require_success "Check" "$CHECK_RESULT" - if [[ "$publish_docs" == "true" ]]; then - require_success "Documentation" "$DOCS_RESULT" - else - allow_success_or_skipped "Documentation" "$DOCS_RESULT" - fi + allow_success_or_skipped "Documentation" "$DOCS_RESULT" if [[ "$publish_packages" == "true" ]]; then require_success "Rust" "$RUST_RESULT" @@ -305,22 +289,6 @@ jobs: exit 1 fi - deploy-docs: - name: Deploy Documentation - needs: [prepare, ci_required] - if: ${{ needs.prepare.outputs.publish_docs == 'true' && needs.ci_required.result == 'success' }} - runs-on: ubuntu-latest - permissions: - pages: write - id-token: write - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - steps: - - name: Deploy GitHub Pages Site - id: deployment - uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5 - publish-rust: name: Publish (crates.io) needs: [prepare, ci_required] diff --git a/.github/workflows/ci_docs.yml b/.github/workflows/ci_docs.yml index 10142f03..f153054a 100644 --- a/.github/workflows/ci_docs.yml +++ b/.github/workflows/ci_docs.yml @@ -4,30 +4,13 @@ name: Documentation on: - workflow_call: - inputs: - ref_type: - description: 'The ref type from the triggering workflow' - required: true - type: string - ref_name: - description: 'The ref name from the triggering workflow' - required: true - type: string - publish_docs: - description: 'Whether to upload a GitHub Pages artifact for deployment' - required: false - default: false - type: boolean + workflow_call: {} defaults: run: shell: bash env: - GH_TOKEN: "${{ github.token }}" - GIT_COMMIT: "${{ github.sha }}" NEMO_FLOW_CI_WORKSPACE: "${{ github.workspace }}" - NEMO_FLOW_CI_WORKSPACE_TMP: "${{ github.workspace }}/tmp" UV_PYTHON_DOWNLOADS: never jobs: @@ -41,8 +24,6 @@ jobs: steps: - name: Checkout uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 - with: - fetch-depth: 0 - name: Load CI tool versions id: ci-config @@ -66,7 +47,7 @@ jobs: - uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1 with: - shared-key: nemo-flow-rust-${{ runner.os }}-${{ runner.arch }}-${{ steps.ci-config.outputs.rust_version }} + shared-key: nemo-flow-rust-docs-${{ runner.os }}-${{ runner.arch }}-${{ steps.ci-config.outputs.rust_version }} workspaces: . -> target cache-all-crates: true cache-bin: false @@ -79,43 +60,16 @@ jobs: - uses: taiki-e/install-action@c070f87102a1c75b3183910f391c1cb887fe13c8 # v2.77.6 with: - tool: just@${{ steps.ci-config.outputs.just_version }},sphinx-rustdocgen@1.0.1 + tool: just@${{ steps.ci-config.outputs.just_version }} - name: Install Documentation Dependencies working-directory: ${{ env.NEMO_FLOW_CI_WORKSPACE }} - run: uv sync --no-default-groups --group docs --no-install-project - - - name: Install Node.js Documentation Dependencies - working-directory: ${{ env.NEMO_FLOW_CI_WORKSPACE }} - run: npm ci --ignore-scripts - - - name: Materialize Main Branch For Versioned Docs - if: ${{ inputs.ref_type == 'tag' }} - working-directory: ${{ env.NEMO_FLOW_CI_WORKSPACE }} - run: git fetch --force origin +refs/heads/main:refs/heads/main - - - name: Check Documentation Links - working-directory: ${{ env.NEMO_FLOW_CI_WORKSPACE }} - env: - NEMO_FLOW_DOCS_DEPS_READY: "1" - run: just docs-linkcheck + run: | + uv sync --no-default-groups --group dev --no-install-project + npm ci --ignore-scripts - - name: Build Documentation Site - if: ${{ startsWith(inputs.ref_name, 'pull-request/') || inputs.ref_name == 'main' }} + - name: Check Documentation working-directory: ${{ env.NEMO_FLOW_CI_WORKSPACE }} env: NEMO_FLOW_DOCS_DEPS_READY: "1" run: just docs - - - name: Build Versioned Documentation Site - if: ${{ inputs.publish_docs }} - working-directory: ${{ env.NEMO_FLOW_CI_WORKSPACE }} - env: - NEMO_FLOW_DOCS_DEPS_READY: "1" - run: just docs-github-pages - - - name: Upload GitHub Pages Artifact - if: ${{ inputs.publish_docs }} - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5 - with: - path: ${{ env.NEMO_FLOW_CI_WORKSPACE }}/docs/_build/pages diff --git a/.gitignore b/.gitignore index 961eb328..859dd50b 100644 --- a/.gitignore +++ b/.gitignore @@ -84,10 +84,10 @@ third_party/hermes-agent/ third_party/openclaw/ third_party/opencode/ -# documentation -docs/_build/**/* -docs/reference/api/**/_generated/ -docs/reference/api/**/_source/ +# Documentation +docs/reference/api/nodejs-library-reference/ +docs/reference/api/python-library-reference/ +docs/reference/api/rust-library-reference/ **/release-notes.md CHANGELOG.md diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 5d33d551..d5a8d012 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -52,12 +52,22 @@ repos: hooks: - id: ty name: ty (type check) - entry: uv run ty check . --exclude docs/** --exclude third_party/** --exclude ./examples/** --exclude .cache/** --exclude .claude/** + entry: uv run ty check . --exclude docs/** --exclude fern/** --exclude third_party/** --exclude ./examples/** --exclude .cache/** --exclude .claude/** language: system types: [python] pass_filenames: false - # Documentation — link validation + # Documentation — Fern validation + - repo: local + hooks: + - id: fern-docs-linkcheck + name: fern docs linkcheck + entry: just docs-linkcheck + language: system + files: '^(fern/|docs/)' + pass_filenames: false + + # Documentation — external link validation - repo: https://github.com/lycheeverse/lychee.git rev: lychee-v0.23.0 hooks: @@ -66,11 +76,21 @@ repos: args: - --no-progress - --include-fragments + - --root-dir + - / + - --scheme + - http + - --scheme + - https + - --accept + - '200..=299,403,429' - --exclude - '^https://www\.npmjs\.com/package/nemo-flow-(node|wasm)$' + - --exclude + - '^https://nemo-flow\.docs\.buildwithfern\.com/dev/?$' - README.md - CONTRIBUTING.md - - docs/**/*.md + - docs/**/*.mdx always_run: true pass_filenames: false diff --git a/AGENTS.md b/AGENTS.md index 94fe1583..8ab966cd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -37,7 +37,7 @@ python/ tests/ # Python tests go/ nemo_flow/ # Experimental Go CGo binding and tests -docs/ # Sphinx documentation site +fern/ # Fern documentation site scripts/ # Stable wrappers and helper scripts; build/test/docs entry points live in justfile third_party/ # Pinned upstream checkouts for sample integration patches patches/ # NeMo Flow patch sets applied to third_party checkouts @@ -115,8 +115,8 @@ Documentation targets: ```bash just docs +just docs-api-reference just docs-linkcheck -just docs-github-pages ``` Package targets: @@ -155,7 +155,7 @@ Minimum guidance: - Node.js binding or wrapper changes: `just test-node`. - Go binding or raw FFI changes: `just test-go` and the relevant Rust/FFI checks. - WebAssembly binding changes: `just test-wasm`. -- Documentation site changes: `just docs`; use `just docs-linkcheck` for link or navigation changes. +- Documentation site changes: `just docs`; use `just docs-linkcheck` for link or navigation changes. `just docs` regenerates the ignored Fern API reference pages before validation. - Cross-language API changes: run the touched binding tests and update docs, package READMEs, and generated surfaces where applicable. Before review, prefer `uv run pre-commit run --all-files` when the change crosses languages or tooling. The hooks enforce SPDX headers, file hygiene, Ruff, `ty`, docs link checks, Cargo formatting/lints/audits, Go formatting/vet, Node formatting, and public docstring checks. @@ -238,7 +238,7 @@ Current public API-based integrations include: These workflow notes keep public documentation, examples, and PR preparation aligned with repository expectations. -- Update `README.md`, `docs/`, package READMEs, and binding-support notes when public behavior, package names, examples, or supported bindings change. +- Update `README.md`, `fern/`, package READMEs, and binding-support notes when public behavior, package names, examples, or supported bindings change. - Keep release-process details in maintainer docs such as `RELEASING.md`. Do not move release-history policy into user-facing docs or `CHANGELOG.md`. - Keep stable public wrappers at the `scripts/` root in docs and examples. Reference namespaced helper paths only when documenting internal maintenance work. - Use branch prefixes from the contributor docs: `feat/`, `fix/`, `docs/`, `test/`, or `refactor/`. diff --git a/ATTRIBUTIONS-Node.md b/ATTRIBUTIONS-Node.md index 101fc3e1..91453ec3 100644 --- a/ATTRIBUTIONS-Node.md +++ b/ATTRIBUTIONS-Node.md @@ -6530,6 +6530,277 @@ The above copyright notice and this permission notice shall be included in all c THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.``` +## @boundaryml/baml - 0.219.0 +**Repository URL**: https://www.npmjs.com/package/@boundaryml/baml +**License Type(s)**: MIT +### License: https://spdx.org/licenses/MIT.html +``` +Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License.``` + +## @boundaryml/baml-darwin-arm64 - 0.219.0 +**Repository URL**: https://www.npmjs.com/package/@boundaryml/baml-darwin-arm64 +**License Type(s)**: MIT +### License: https://spdx.org/licenses/MIT.html +``` +(No license file read from locked npm artifact for @boundaryml/baml-darwin-arm64; see npm metadata.) +``` + +## @boundaryml/baml-darwin-x64 - 0.219.0 +**Repository URL**: https://www.npmjs.com/package/@boundaryml/baml-darwin-x64 +**License Type(s)**: MIT +### License: https://spdx.org/licenses/MIT.html +``` +(No license file read from locked npm artifact for @boundaryml/baml-darwin-x64; see npm metadata.) +``` + +## @boundaryml/baml-linux-arm64-gnu - 0.219.0 +**Repository URL**: https://www.npmjs.com/package/@boundaryml/baml-linux-arm64-gnu +**License Type(s)**: MIT +### License: https://spdx.org/licenses/MIT.html +``` +(No license file read from locked npm artifact for @boundaryml/baml-linux-arm64-gnu; see npm metadata.) +``` + +## @boundaryml/baml-linux-arm64-musl - 0.219.0 +**Repository URL**: https://www.npmjs.com/package/@boundaryml/baml-linux-arm64-musl +**License Type(s)**: MIT +### License: https://spdx.org/licenses/MIT.html +``` +(No license file read from locked npm artifact for @boundaryml/baml-linux-arm64-musl; see npm metadata.) +``` + +## @boundaryml/baml-linux-x64-gnu - 0.219.0 +**Repository URL**: https://www.npmjs.com/package/@boundaryml/baml-linux-x64-gnu +**License Type(s)**: MIT +### License: https://spdx.org/licenses/MIT.html +``` +(No license file read from locked npm artifact for @boundaryml/baml-linux-x64-gnu; see npm metadata.) +``` + +## @boundaryml/baml-linux-x64-musl - 0.219.0 +**Repository URL**: https://www.npmjs.com/package/@boundaryml/baml-linux-x64-musl +**License Type(s)**: MIT +### License: https://spdx.org/licenses/MIT.html +``` +(No license file read from locked npm artifact for @boundaryml/baml-linux-x64-musl; see npm metadata.) +``` + +## @boundaryml/baml-win32-arm64-msvc - 0.219.0 +**Repository URL**: https://www.npmjs.com/package/@boundaryml/baml-win32-arm64-msvc +**License Type(s)**: MIT +### License: https://spdx.org/licenses/MIT.html +``` +(No license file read from locked npm artifact for @boundaryml/baml-win32-arm64-msvc; see npm metadata.) +``` + +## @boundaryml/baml-win32-x64-msvc - 0.219.0 +**Repository URL**: https://www.npmjs.com/package/@boundaryml/baml-win32-x64-msvc +**License Type(s)**: MIT +### License: https://spdx.org/licenses/MIT.html +``` +(No license file read from locked npm artifact for @boundaryml/baml-win32-x64-msvc; see npm metadata.) +``` + ## @clack/core - 1.3.0 **Repository URL**: https://github.com/bombshell-dev/clack **License Type(s)**: MIT @@ -11300,37 +11571,244 @@ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.``` -## @protobufjs/utf8 - 1.1.1 -**Repository URL**: https://github.com/dcodeIO/protobuf.js -**License Type(s)**: BSD-3-Clause -### License: https://spdx.org/licenses/BSD-3-Clause.html -``` -Copyright (c) 2016, Daniel Wirtz All rights reserved. +## @protobufjs/utf8 - 1.1.1 +**Repository URL**: https://github.com/dcodeIO/protobuf.js +**License Type(s)**: BSD-3-Clause +### License: https://spdx.org/licenses/BSD-3-Clause.html +``` +Copyright (c) 2016, Daniel Wirtz All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + +* Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. +* Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. +* Neither the name of its author, nor the names of its contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.``` + +## @scarf/scarf - 1.4.0 +**Repository URL**: https://www.npmjs.com/package/@scarf/scarf +**License Type(s)**: Apache-2.0 +### License: https://spdx.org/licenses/Apache-2.0.html +``` +Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: + APPENDIX: How to apply the Apache License to your work. -* Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. -* Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. -* Neither the name of its author, nor the names of its contributors - may be used to endorse or promote products derived from this software - without specific prior written permission. + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.``` + Copyright 2020 Scarf Systems, Inc. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License.``` ## @shikijs/engine-oniguruma - 3.23.0 **Repository URL**: https://github.com/shikijs/shiki @@ -17096,6 +17574,213 @@ ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.``` +## fern-api - 5.27.5 +**Repository URL**: https://github.com/fern-api/fern +**License Type(s)**: Apache* +### License: https://opensource.org/licenses/ +``` +Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License.``` + ## fetch-blob - 3.2.0 **Repository URL**: https://github.com/node-fetch/fetch-blob **License Type(s)**: MIT diff --git a/ATTRIBUTIONS-Python.md b/ATTRIBUTIONS-Python.md index c10c363b..de5e6442 100644 --- a/ATTRIBUTIONS-Python.md +++ b/ATTRIBUTIONS-Python.md @@ -11,44 +11,6 @@ Each package is open-source and licensed under the terms indicated below. This file is automatically generated from **uv.lock** Please do not edit it directly. Regenerate with `./scripts/generate_attributions.sh python` -## accessible-pygments (0.0.5) - -### Licenses -License: `BSD-3-Clause` - - - `LICENSE`: -``` -BSD 3-Clause License - -Copyright (c) 2022, Quansight Labs -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -1. Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -3. Neither the name of the copyright holder nor the names of its - contributors may be used to endorse or promote products derived from - this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -``` - ## aiohappyeyeballs (2.6.1) ### Licenses @@ -569,49 +531,6 @@ Apache License limitations under the License. ``` -## alabaster (1.0.0) - -### Licenses -License: `BSD License` - - - `LICENSE.rst`: -``` -Copyright (c) 2020 Jeff Forcier. - -Based on original work copyright (c) 2011 Kenneth Reitz and copyright (c) 2010 -Armin Ronacher. - -Some rights reserved. - -Redistribution and use in source and binary forms of the theme, with or -without modification, are permitted provided that the following conditions -are met: - -* Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following - disclaimer in the documentation and/or other materials provided - with the distribution. - -* The names of the contributors may not be used to endorse or - promote products derived from this software without specific - prior written permission. - -THIS THEME IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE -LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR -CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF -SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS -INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN -CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) -ARISING IN ANY WAY OUT OF THE USE OF THIS THEME, EVEN IF ADVISED OF THE -POSSIBILITY OF SUCH DAMAGE. -``` - ## annotated-types (0.7.0) ### Licenses @@ -687,522 +606,6 @@ IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ``` -## astroid (4.1.2) - -### Licenses -License: `LGPL-2.1-or-later` - - - `LICENSE`: -``` -GNU LESSER GENERAL PUBLIC LICENSE - Version 2.1, February 1999 - - Copyright (C) 1991, 1999 Free Software Foundation, Inc. - 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - -[This is the first released version of the Lesser GPL. It also counts - as the successor of the GNU Library Public License, version 2, hence - the version number 2.1.] - - Preamble - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -Licenses are intended to guarantee your freedom to share and change -free software--to make sure the software is free for all its users. - - This license, the Lesser General Public License, applies to some -specially designated software packages--typically libraries--of the -Free Software Foundation and other authors who decide to use it. You -can use it too, but we suggest you first think carefully about whether -this license or the ordinary General Public License is the better -strategy to use in any particular case, based on the explanations -below. - - When we speak of free software, we are referring to freedom of use, -not price. Our General Public Licenses are designed to make sure that -you have the freedom to distribute copies of free software (and charge -for this service if you wish); that you receive source code or can get -it if you want it; that you can change the software and use pieces of -it in new free programs; and that you are informed that you can do -these things. - - To protect your rights, we need to make restrictions that forbid -distributors to deny you these rights or to ask you to surrender these -rights. These restrictions translate to certain responsibilities for -you if you distribute copies of the library or if you modify it. - - For example, if you distribute copies of the library, whether gratis -or for a fee, you must give the recipients all the rights that we gave -you. You must make sure that they, too, receive or can get the source -code. If you link other code with the library, you must provide -complete object files to the recipients, so that they can relink them -with the library after making changes to the library and recompiling -it. And you must show them these terms so they know their rights. - - We protect your rights with a two-step method: (1) we copyright the -library, and (2) we offer you this license, which gives you legal -permission to copy, distribute and/or modify the library. - - To protect each distributor, we want to make it very clear that -there is no warranty for the free library. Also, if the library is -modified by someone else and passed on, the recipients should know -that what they have is not the original version, so that the original -author's reputation will not be affected by problems that might be -introduced by others. - - Finally, software patents pose a constant threat to the existence of -any free program. We wish to make sure that a company cannot -effectively restrict the users of a free program by obtaining a -restrictive license from a patent holder. Therefore, we insist that -any patent license obtained for a version of the library must be -consistent with the full freedom of use specified in this license. - - Most GNU software, including some libraries, is covered by the -ordinary GNU General Public License. This license, the GNU Lesser -General Public License, applies to certain designated libraries, and -is quite different from the ordinary General Public License. We use -this license for certain libraries in order to permit linking those -libraries into non-free programs. - - When a program is linked with a library, whether statically or using -a shared library, the combination of the two is legally speaking a -combined work, a derivative of the original library. The ordinary -General Public License therefore permits such linking only if the -entire combination fits its criteria of freedom. The Lesser General -Public License permits more lax criteria for linking other code with -the library. - - We call this license the "Lesser" General Public License because it -does Less to protect the user's freedom than the ordinary General -Public License. It also provides other free software developers Less -of an advantage over competing non-free programs. These disadvantages -are the reason we use the ordinary General Public License for many -libraries. However, the Lesser license provides advantages in certain -special circumstances. - - For example, on rare occasions, there may be a special need to -encourage the widest possible use of a certain library, so that it -becomes a de-facto standard. To achieve this, non-free programs must -be allowed to use the library. A more frequent case is that a free -library does the same job as widely used non-free libraries. In this -case, there is little to gain by limiting the free library to free -software only, so we use the Lesser General Public License. - - In other cases, permission to use a particular library in non-free -programs enables a greater number of people to use a large body of -free software. For example, permission to use the GNU C Library in -non-free programs enables many more people to use the whole GNU -operating system, as well as its variant, the GNU/Linux operating -system. - - Although the Lesser General Public License is Less protective of the -users' freedom, it does ensure that the user of a program that is -linked with the Library has the freedom and the wherewithal to run -that program using a modified version of the Library. - - The precise terms and conditions for copying, distribution and -modification follow. Pay close attention to the difference between a -"work based on the library" and a "work that uses the library". The -former contains code derived from the library, whereas the latter must -be combined with the library in order to run. - - GNU LESSER GENERAL PUBLIC LICENSE - TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - - 0. This License Agreement applies to any software library or other -program which contains a notice placed by the copyright holder or -other authorized party saying it may be distributed under the terms of -this Lesser General Public License (also called "this License"). -Each licensee is addressed as "you". - - A "library" means a collection of software functions and/or data -prepared so as to be conveniently linked with application programs -(which use some of those functions and data) to form executables. - - The "Library", below, refers to any such software library or work -which has been distributed under these terms. A "work based on the -Library" means either the Library or any derivative work under -copyright law: that is to say, a work containing the Library or a -portion of it, either verbatim or with modifications and/or translated -straightforwardly into another language. (Hereinafter, translation is -included without limitation in the term "modification".) - - "Source code" for a work means the preferred form of the work for -making modifications to it. For a library, complete source code means -all the source code for all modules it contains, plus any associated -interface definition files, plus the scripts used to control -compilation and installation of the library. - - Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of -running a program using the Library is not restricted, and output from -such a program is covered only if its contents constitute a work based -on the Library (independent of the use of the Library in a tool for -writing it). Whether that is true depends on what the Library does -and what the program that uses the Library does. - - 1. You may copy and distribute verbatim copies of the Library's -complete source code as you receive it, in any medium, provided that -you conspicuously and appropriately publish on each copy an -appropriate copyright notice and disclaimer of warranty; keep intact -all the notices that refer to this License and to the absence of any -warranty; and distribute a copy of this License along with the -Library. - - You may charge a fee for the physical act of transferring a copy, -and you may at your option offer warranty protection in exchange for a -fee. - - 2. You may modify your copy or copies of the Library or any portion -of it, thus forming a work based on the Library, and copy and -distribute such modifications or work under the terms of Section 1 -above, provided that you also meet all of these conditions: - - a) The modified work must itself be a software library. - - b) You must cause the files modified to carry prominent notices - stating that you changed the files and the date of any change. - - c) You must cause the whole of the work to be licensed at no - charge to all third parties under the terms of this License. - - d) If a facility in the modified Library refers to a function or a - table of data to be supplied by an application program that uses - the facility, other than as an argument passed when the facility - is invoked, then you must make a good faith effort to ensure that, - in the event an application does not supply such function or - table, the facility still operates, and performs whatever part of - its purpose remains meaningful. - - (For example, a function in a library to compute square roots has - a purpose that is entirely well-defined independent of the - application. Therefore, Subsection 2d requires that any - application-supplied function or table used by this function must - be optional: if the application does not supply it, the square - root function must still compute square roots.) - -These requirements apply to the modified work as a whole. If -identifiable sections of that work are not derived from the Library, -and can be reasonably considered independent and separate works in -themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you -distribute the same sections as part of a whole which is a work based -on the Library, the distribution of the whole must be on the terms of -this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote -it. - -Thus, it is not the intent of this section to claim rights or contest -your rights to work written entirely by you; rather, the intent is to -exercise the right to control the distribution of derivative or -collective works based on the Library. - -In addition, mere aggregation of another work not based on the Library -with the Library (or with a work based on the Library) on a volume of -a storage or distribution medium does not bring the other work under -the scope of this License. - - 3. You may opt to apply the terms of the ordinary GNU General Public -License instead of this License to a given copy of the Library. To do -this, you must alter all the notices that refer to this License, so -that they refer to the ordinary GNU General Public License, version 2, -instead of to this License. (If a newer version than version 2 of the -ordinary GNU General Public License has appeared, then you can specify -that version instead if you wish.) Do not make any other change in -these notices. - - Once this change is made in a given copy, it is irreversible for -that copy, so the ordinary GNU General Public License applies to all -subsequent copies and derivative works made from that copy. - - This option is useful when you wish to copy part of the code of -the Library into a program that is not a library. - - 4. You may copy and distribute the Library (or a portion or -derivative of it, under Section 2) in object code or executable form -under the terms of Sections 1 and 2 above provided that you accompany -it with the complete corresponding machine-readable source code, which -must be distributed under the terms of Sections 1 and 2 above on a -medium customarily used for software interchange. - - If distribution of object code is made by offering access to copy -from a designated place, then offering equivalent access to copy the -source code from the same place satisfies the requirement to -distribute the source code, even though third parties are not -compelled to copy the source along with the object code. - - 5. A program that contains no derivative of any portion of the -Library, but is designed to work with the Library by being compiled or -linked with it, is called a "work that uses the Library". Such a -work, in isolation, is not a derivative work of the Library, and -therefore falls outside the scope of this License. - - However, linking a "work that uses the Library" with the Library -creates an executable that is a derivative of the Library (because it -contains portions of the Library), rather than a "work that uses the -library". The executable is therefore covered by this License. -Section 6 states terms for distribution of such executables. - - When a "work that uses the Library" uses material from a header file -that is part of the Library, the object code for the work may be a -derivative work of the Library even though the source code is not. -Whether this is true is especially significant if the work can be -linked without the Library, or if the work is itself a library. The -threshold for this to be true is not precisely defined by law. - - If such an object file uses only numerical parameters, data -structure layouts and accessors, and small macros and small inline -functions (ten lines or less in length), then the use of the object -file is unrestricted, regardless of whether it is legally a derivative -work. (Executables containing this object code plus portions of the -Library will still fall under Section 6.) - - Otherwise, if the work is a derivative of the Library, you may -distribute the object code for the work under the terms of Section 6. -Any executables containing that work also fall under Section 6, -whether or not they are linked directly with the Library itself. - - 6. As an exception to the Sections above, you may also combine or -link a "work that uses the Library" with the Library to produce a -work containing portions of the Library, and distribute that work -under terms of your choice, provided that the terms permit -modification of the work for the customer's own use and reverse -engineering for debugging such modifications. - - You must give prominent notice with each copy of the work that the -Library is used in it and that the Library and its use are covered by -this License. You must supply a copy of this License. If the work -during execution displays copyright notices, you must include the -copyright notice for the Library among them, as well as a reference -directing the user to the copy of this License. Also, you must do one -of these things: - - a) Accompany the work with the complete corresponding - machine-readable source code for the Library including whatever - changes were used in the work (which must be distributed under - Sections 1 and 2 above); and, if the work is an executable linked - with the Library, with the complete machine-readable "work that - uses the Library", as object code and/or source code, so that the - user can modify the Library and then relink to produce a modified - executable containing the modified Library. (It is understood - that the user who changes the contents of definitions files in the - Library will not necessarily be able to recompile the application - to use the modified definitions.) - - b) Use a suitable shared library mechanism for linking with the - Library. A suitable mechanism is one that (1) uses at run time a - copy of the library already present on the user's computer system, - rather than copying library functions into the executable, and (2) - will operate properly with a modified version of the library, if - the user installs one, as long as the modified version is - interface-compatible with the version that the work was made with. - - c) Accompany the work with a written offer, valid for at least - three years, to give the same user the materials specified in - Subsection 6a, above, for a charge no more than the cost of - performing this distribution. - - d) If distribution of the work is made by offering access to copy - from a designated place, offer equivalent access to copy the above - specified materials from the same place. - - e) Verify that the user has already received a copy of these - materials or that you have already sent this user a copy. - - For an executable, the required form of the "work that uses the -Library" must include any data and utility programs needed for -reproducing the executable from it. However, as a special exception, -the materials to be distributed need not include anything that is -normally distributed (in either source or binary form) with the major -components (compiler, kernel, and so on) of the operating system on -which the executable runs, unless that component itself accompanies -the executable. - - It may happen that this requirement contradicts the license -restrictions of other proprietary libraries that do not normally -accompany the operating system. Such a contradiction means you cannot -use both them and the Library together in an executable that you -distribute. - - 7. You may place library facilities that are a work based on the -Library side-by-side in a single library together with other library -facilities not covered by this License, and distribute such a combined -library, provided that the separate distribution of the work based on -the Library and of the other library facilities is otherwise -permitted, and provided that you do these two things: - - a) Accompany the combined library with a copy of the same work - based on the Library, uncombined with any other library - facilities. This must be distributed under the terms of the - Sections above. - - b) Give prominent notice with the combined library of the fact - that part of it is a work based on the Library, and explaining - where to find the accompanying uncombined form of the same work. - - 8. You may not copy, modify, sublicense, link with, or distribute -the Library except as expressly provided under this License. Any -attempt otherwise to copy, modify, sublicense, link with, or -distribute the Library is void, and will automatically terminate your -rights under this License. However, parties who have received copies, -or rights, from you under this License will not have their licenses -terminated so long as such parties remain in full compliance. - - 9. You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Library or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by -modifying or distributing the Library (or any work based on the -Library), you indicate your acceptance of this License to do so, and -all its terms and conditions for copying, distributing or modifying -the Library or works based on it. - - 10. Each time you redistribute the Library (or any work based on the -Library), the recipient automatically receives a license from the -original licensor to copy, distribute, link with or modify the Library -subject to these terms and conditions. You may not impose any further -restrictions on the recipients' exercise of the rights granted herein. -You are not responsible for enforcing compliance by third parties with -this License. - - 11. If, as a consequence of a court judgment or allegation of patent -infringement or for any other reason (not limited to patent issues), -conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot -distribute so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you -may not distribute the Library at all. For example, if a patent -license would not permit royalty-free redistribution of the Library by -all those who receive copies directly or indirectly through you, then -the only way you could satisfy both it and this License would be to -refrain entirely from distribution of the Library. - -If any portion of this section is held invalid or unenforceable under -any particular circumstance, the balance of the section is intended to -apply, and the section as a whole is intended to apply in other -circumstances. - -It is not the purpose of this section to induce you to infringe any -patents or other property right claims or to contest validity of any -such claims; this section has the sole purpose of protecting the -integrity of the free software distribution system which is -implemented by public license practices. Many people have made -generous contributions to the wide range of software distributed -through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing -to distribute software through any other system and a licensee cannot -impose that choice. - -This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - - 12. If the distribution and/or use of the Library is restricted in -certain countries either by patents or by copyrighted interfaces, the -original copyright holder who places the Library under this License -may add an explicit geographical distribution limitation excluding those -countries, so that distribution is permitted only in or among -countries not thus excluded. In such case, this License incorporates -the limitation as if written in the body of this License. - - 13. The Free Software Foundation may publish revised and/or new -versions of the Lesser General Public License from time to time. -Such new versions will be similar in spirit to the present version, -but may differ in detail to address new problems or concerns. - -Each version is given a distinguishing version number. If the Library -specifies a version number of this License which applies to it and -"any later version", you have the option of following the terms and -conditions either of that version or of any later version published by -the Free Software Foundation. If the Library does not specify a -license version number, you may choose any version ever published by -the Free Software Foundation. - - 14. If you wish to incorporate parts of the Library into other free -programs whose distribution conditions are incompatible with these, -write to the author to ask for permission. For software which is -copyrighted by the Free Software Foundation, write to the Free -Software Foundation; we sometimes make exceptions for this. Our -decision will be guided by the two goals of preserving the free status -of all derivatives of our free software and of promoting the sharing -and reuse of software generally. - - NO WARRANTY - - 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO -WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. -EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR -OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY -KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE -LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME -THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. - - 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN -WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY -AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU -FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR -CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE -LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING -RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A -FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF -SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH -DAMAGES. - - END OF TERMS AND CONDITIONS - - How to Apply These Terms to Your New Libraries - - If you develop a new library, and you want it to be of the greatest -possible use to the public, we recommend making it free software that -everyone can redistribute and change. You can do so by permitting -redistribution under these terms (or, alternatively, under the terms -of the ordinary General Public License). - - To apply these terms, attach the following notices to the library. -It is safest to attach them to the start of each source file to most -effectively convey the exclusion of warranty; and each file should -have at least the "copyright" line and a pointer to where the full -notice is found. - - - - Copyright (C) - - This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Lesser General Public - License as published by the Free Software Foundation; either - version 2.1 of the License, or (at your option) any later version. - - This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public - License along with this library; if not, write to the Free Software - Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA - -Also add information on how to contact you by electronic and paper mail. - -You should also get your employer (if you work as a programmer) or -your school, if any, to sign a "copyright disclaimer" for the library, -if necessary. Here is a sample; alter the names: - - Yoyodyne, Inc., hereby disclaims all copyright interest in the - library `Frob' (a library for tweaking knobs) written by James - Random Hacker. - - , 1 April 1990 - Ty Coon, President of Vice - -That's all there is to it! -``` - ## asttokens (3.0.1) ### Licenses @@ -1443,42 +846,6 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ``` -## babel (2.18.0) - -### Licenses -License: `BSD-3-Clause` - - - `LICENSE`: -``` -Copyright (c) 2013-2026 by the Babel Team, see AUTHORS for more information. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions -are met: - - 1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - 2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - 3. Neither the name of the copyright holder nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -``` - ## beautifulsoup4 (4.14.3) ### Licenses @@ -1549,24 +916,6 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ``` -## cattrs (24.1.3) - -### Licenses -License: `MIT` - - - `LICENSE`: -``` -MIT License - -Copyright (c) 2016, Tin Tvrtković - -Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -``` - ## certifi (2026.2.25) ### Licenses @@ -2496,174 +1845,6 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ``` -## docutils (0.21.2) - -### Licenses -License: `Public Domain OR Python Software Foundation License OR BSD License OR GNU General Public License (GPL)` - - - `COPYING.txt`: -``` -.. include:: docs/header0.txt - -================== - Copying Docutils -================== - -:Author: David Goodger -:Contact: goodger@python.org -:Date: $Date: 2023-06-22 17:34:37 +0200 (Do, 22. Jun 2023) $ -:Web site: https://docutils.sourceforge.io/ -:Copyright: This document has been placed in the public domain. - -Most of the files included in this project have been placed in the -public domain, and therefore have no license requirements and no -restrictions on copying or usage; see the `Public Domain Dedication`_ -below. There are exceptions_, listed below. -Files in the Sandbox_ are not distributed with Docutils releases and -may have different license terms. - - -Public Domain Dedication -======================== - -The persons who have associated their work with this project (the -"Dedicator": David Goodger and the many contributors to the Docutils -project) hereby dedicate the entire copyright, less the exceptions_ -listed below, in the work of authorship known as "Docutils" identified -below (the "Work") to the public domain. - -The primary repository for the Work is the Internet World Wide Web -site . The Work consists of the -files within the "docutils" module of the Docutils project Subversion -repository (http://svn.code.sf.net/p/docutils/code/), -whose Internet web interface is located at -. Files dedicated to the -public domain may be identified by the inclusion, near the beginning -of each file, of a declaration of the form:: - - Copyright: This document/module/DTD/stylesheet/file/etc. has been - placed in the public domain. - -Dedicator makes this dedication for the benefit of the public at large -and to the detriment of Dedicator's heirs and successors. Dedicator -intends this dedication to be an overt act of relinquishment in -perpetuity of all present and future rights under copyright law, -whether vested or contingent, in the Work. Dedicator understands that -such relinquishment of all rights includes the relinquishment of all -rights to enforce (by lawsuit or otherwise) those copyrights in the -Work. - -Dedicator recognizes that, once placed in the public domain, the Work -may be freely reproduced, distributed, transmitted, used, modified, -built upon, or otherwise exploited by anyone for any purpose, -commercial or non-commercial, and in any way, including by methods -that have not yet been invented or conceived. - -(This dedication is derived from the text of the `Creative Commons -Public Domain Dedication`. [#]_) - -.. [#] Creative Commons has `retired this legal tool`__ and does not - recommend that it be applied to works: This tool is based on United - States law and may not be applicable outside the US. For dedicating new - works to the public domain, Creative Commons recommend the replacement - Public Domain Dedication CC0_ (CC zero, "No Rights Reserved"). So does - the Free Software Foundation in its license-list_. - - __ http://creativecommons.org/retiredlicenses - .. _CC0: http://creativecommons.org/about/cc0 - -Exceptions -========== - -The exceptions to the `Public Domain Dedication`_ above are: - -* docutils/utils/smartquotes.py - - Copyright © 2011 Günter Milde, - based on `SmartyPants`_ © 2003 John Gruber - (released under a "revised" `BSD 3-Clause License`_ included in the file) - and smartypants.py © 2004, 2007 Chad Miller. - Released under the terms of the `BSD 2-Clause License`_ - (`local copy `__). - - .. _SmartyPants: http://daringfireball.net/projects/smartypants/ - -* docutils/utils/math/latex2mathml.py - - Copyright © Jens Jørgen Mortensen, Günter Milde. - Released under the terms of the `BSD 2-Clause License`_ - (`local copy `__). - -* | docutils/utils/math/math2html.py, - | docutils/writers/html5_polyglot/math.css - - Copyright © 2009,2010 Alex Fernández; 2021 Günter Milde - - These files were part of eLyXer_, released under the `GNU - General Public License`_ version 3 or later. The author relicensed - them for Docutils under the terms of the `BSD 2-Clause License`_ - (`local copy `__). - - .. _eLyXer: https://github.com/alexfernandez/elyxer - -* | docutils/__main__.py, - | docutils/parsers/commonmark_wrapper.py, - | docutils/parsers/recommonmark_wrapper.py, - | docutils/utils/error_reporting.py, - | docutils/utils/math/__init__.py, - | docutils/utils/math/latex2mathml.py, - | docutils/utils/math/tex2mathml_extern.py, - | docutils/utils/punctuation_chars.py, - | docutils/utils/smartquotes.py, - | docutils/writers/html5_polyglot/__init__.py, - | docutils/writers/html5_polyglot/\*.css, - | docutils/writers/latex2e/docutils.sty, - | docutils/writers/xetex/__init__.py, - | test/test_parsers/test_recommonmark/\*.py, - | test/test_parsers/test_rst/test_directives/test__init__.py, - | test/test_parsers/test_rst/test_directives/test_code_parsing.py, - | test/test_parsers/test_rst/test_line_length_limit_default.py, - | test/test_parsers/test_rst/test_line_length_limit.py, - | test/test_writers/test_latex2e_misc.py, - | test/transforms/test_smartquotes.py, - | tools/docutils-cli.py, - | tools/rst2html5.py - - Copyright © Günter Milde. - Released under the terms of the `BSD 2-Clause License`_ - (`local copy `__). - -* docutils/utils/roman.py - - copyright by Mark Pilgrim, released under the - `Zope Public License Version 2.1`_ (`local copy`__). - - __ licenses/ZPL-2-1.txt - -* tools/editors/emacs/rst.el - - copyright by Free Software Foundation, Inc., - released under the `GNU General Public License`_ version 3 or later - (`local copy`__). - - __ licenses/gpl-3-0.txt - -All used licenses are OSI-approved_ and GPL-compatible_. - -Plaintext versions of all the linked-to licenses are provided in the -licenses_ directory. - -.. _sandbox: https://docutils.sourceforge.io/sandbox/README.html -.. _licenses: licenses/ -.. _GNU General Public License: https://www.gnu.org/copyleft/gpl.html -.. _BSD 2-Clause License: http://opensource.org/licenses/BSD-2-Clause -.. _BSD 3-Clause License: https://opensource.org/licenses/BSD-3-Clause -.. _Zope Public License Version 2.1: https://opensource.org/license/zpl-2-1/ -.. _OSI-approved: http://opensource.org/licenses/ -.. _license-list: -.. _GPL-compatible: https://www.gnu.org/licenses/license-list.html -``` - ## executing (2.2.1) ### Licenses @@ -3540,34 +2721,6 @@ NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ``` -## imagesize (2.0.0) - -### Licenses -License: `MIT` - - - `LICENSE.rst`: -``` -The MIT License (MIT) ----------------------------- - -Copyright © 2016 Yoshiki Shibukawa - -Permission is hereby granted, free of charge, to any person obtaining a copy of this software -and associated documentation files (the “Software”), to deal in the Software without restriction, -including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, -and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, -subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all copies or substantial -portions of the Software. - -THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT -NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, -WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH -THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -``` - ## iniconfig (2.3.0) ### Licenses @@ -3673,43 +2826,6 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ``` -## jinja2 (3.1.6) - -### Licenses -License: `BSD License` - - - `LICENSE.txt`: -``` -Copyright 2007 Pallets - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -3. Neither the name of the copyright holder nor the names of its - contributors may be used to endorse or promote products derived from - this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A -PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED -TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR -PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF -LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING -NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -``` - ## jiter (0.14.0) ### Licenses @@ -4084,73 +3200,6 @@ License: `MIT` (No license file found in locked artifact for langsmith; see package metadata or PyPI.) ``` -## markdown-it-py (3.0.0) - -### Licenses -License: `MIT` - - - `LICENSE`: -``` -MIT License - -Copyright (c) 2020 ExecutableBookProject - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. -``` - -## markupsafe (3.0.3) - -### Licenses -License: `BSD-3-Clause` - - - `LICENSE.txt`: -``` -Copyright 2010 Pallets - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -3. Neither the name of the copyright holder nor the names of its - contributors may be used to endorse or promote products derived from - this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A -PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED -TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR -PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF -LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING -NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -``` - ## matplotlib-inline (0.2.1) ### Licenses @@ -4223,153 +3272,38 @@ IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ``` -## mdit-py-plugins (0.5.0) +## multidict (6.7.1) ### Licenses -License: `MIT` +License: `Apache License 2.0` - `LICENSE`: ``` -MIT License - -Copyright (c) 2020 ExecutableBookProject +Copyright 2016 Andrew Svetlov and aio-libs contributors -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. + http://www.apache.org/licenses/LICENSE-2.0 -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. ``` -## mdurl (0.1.2) +## nodeenv (1.10.0) ### Licenses -License: `MIT` +License: `BSD` - `LICENSE`: ``` -Copyright (c) 2015 Vitaly Puzrin, Alex Kocharin. -Copyright (c) 2021 Taneli Hukkinen +Copyright (c) 2011, Eugene Kalinin. -Permission is hereby granted, free of charge, to any person -obtaining a copy of this software and associated documentation -files (the "Software"), to deal in the Software without -restriction, including without limitation the rights to use, -copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the -Software is furnished to do so, subject to the following -conditions: - -The above copyright notice and this permission notice shall be -included in all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, -EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES -OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND -NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT -HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, -WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING -FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -OTHER DEALINGS IN THE SOFTWARE. - --------------------------------------------------------------------------------- - -.parse() is based on Joyent's node.js `url` code: - -Copyright Joyent, Inc. and other Node contributors. All rights reserved. -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to -deal in the Software without restriction, including without limitation the -rights to use, copy, modify, merge, publish, distribute, sublicense, and/or -sell copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING -FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS -IN THE SOFTWARE. -``` - -## multidict (6.7.1) - -### Licenses -License: `Apache License 2.0` - - - `LICENSE`: -``` -Copyright 2016 Andrew Svetlov and aio-libs contributors - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. -``` - -## myst-parser (4.0.1) - -### Licenses -License: `MIT` - - - `LICENSE`: -``` -MIT License - -Copyright (c) 2020 ExecutableBookProject - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. -``` - -## nodeenv (1.10.0) - -### Licenses -License: `BSD` - - - `LICENSE`: -``` -Copyright (c) 2011, Eugene Kalinin. - -Some rights reserved. +Some rights reserved. Redistribution and use in source and binary forms of the software as well as documentation, with or without modification, are permitted provided @@ -4401,67 +3335,6 @@ SOFTWARE AND DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ``` -## nvidia-sphinx-theme (0.0.9.post1) - -### Licenses -License: `NVIDIA License Agreement` - - - `LICENSE`: -``` -NVIDIA LICENSE AGREEMENT - -This NVIDIA License Agreement (“AGREEMENT”) is a legal agreement between you and NVIDIA Corporation ("NVIDIA") and governs your use of the NVIDIA font, icons and other assets, and software, in each case if and when available (“Licensed Materials”). - -This AGREEMENT can be accepted only by an adult of legal age of majority in the country in which the Licensed Materials is used. If you are under the legal age of majority, you must ask your parent or legal guardian to consent to this AGREEMENT. If you are entering into this AGREEMENT on behalf of a company or other legal entity, you represent that you have legal authority and “you” will mean the entity you represent. - -By using the Licensed Materials, you affirm that you have reached the legal age of majority, you accept the terms of this AGREEMENT, and you take legal and financial responsibility for the actions of your permitted users. - -You agree to use the Licensed Materials only for purposes that are permitted by (a) this AGREEMENT, and (b) any applicable law, regulation or generally accepted practices or guidelines in the relevant jurisdictions. - -1. LICENSE. Subject to the terms of this AGREEMENT, NVIDIA hereby grants you a limited, non-exclusive, non-assignable, non-transferable, non-sublicensable (except as expressly provided in this AGREEMENT) license to: -1.1 use, copy and reproduce the Licensed Materials when provided in an NVIDIA products or service with the applicable NVIDIA product or service; and -1.2 use, copy and reproduce the Licensed Materials when provided stand-alone with products, related packaging, advertising marketing collaterals and assets used for offline or online marketing, and web sites, in each case, in connection with NVIDIA’s products and services only (“PERMITTED PRODUCTS”). - -2. LIMITATIONS. Your license to use the Licensed Materials is restricted as follows: -2.1 For Licensed Materials provided with an NVIDIA product or service, you must not separate or use the Licensed Materials apart from the applicable product or service. -2.2 You may not reverse engineer, decompile or disassemble, or remove copyright or other proprietary notices from any portion of the Licensed Materials or copies of the Licensed Materials. -2.3 Except as provided in this AGREEMENT, you may not copy, modify, adapt, convert the Licensed Materials, nor create derivative works from the Licensed Materials or any portion thereof. Further, you may not use the Licensed Materials in connection with software and/or hardware which create derivative works of such Licensed Materials. -2.4 Except as provided in this AGREEMENT, you may not sell, rent, sublicense, transfer or distribute the Licensed Materials, or make its functionality available to others, or embed the Licensed Materials into a product or other content that is not a PERMITTED PRODUCT. -2.5 You may not use the Licensed Materials for the purpose of developing competing products or technologies or assisting a third party in such activities. -2.6 You may not bypass, disable, or circumvent any technical limitations, encryption, security, digital rights management or authentication mechanism in the Licensed Materials. -2.7 You may not use the Licensed Materials in any manner that would cause it to become subject to an OSS License. “OSS License” means any software, data or documentation subject to any license identified as an open source license by the Open Source Initiative (http://opensource.org), Free Software Foundation (http://www.fsf.org) or other similar open source organization or listed by the Software Package Data Exchange (SPDX) Workgroup under the Linux Foundation (http://www.spdx.org). - -3. AUTHORIZED USERS. You may allow employees and contractors of your entity or of your subsidiary(ies) to access and use the Licensed Materials from your secure network to perform work on your behalf. If you are an academic institution you may allow users enrolled or employed by the academic institution to access and use the Licensed Materials from your secure network. You are responsible for the compliance with the terms of this AGREEMENT by your authorized users. - -4. UPDATES. NVIDIA is not obligated to support or update the Licensed Materials. This AGREEMENT also applies to Licensed Materials patches, workarounds or other updates, each of which will be deemed part of the Licensed Materials, unless other terms accompany those items. - -5. OWNERSHIP. NVIDIA reserves all rights, title and interest in and to the Licensed Materials not expressly granted to you under this AGREEMENT. The Licensed Materials and the related intellectual property rights therein, and all derivative works thereof, are and will remain the sole and exclusive property of NVIDIA or its licensors. The Licensed Materials is copyrighted and protected by the laws of the United States and other countries, and international treaty provisions. - -You agree to use trademarks associated with the Licensed Materials in accordance with the NVIDIA Trademark License Agreement (https://www.nvidia.com/content/dam/en-zz/Solutions/about-us/documents/Trademark-License-Agreement.pdf) and the NVIDIA Trademark and Logo Usage Guidelines (https://www.nvidia.com/content/dam/en-zz/Solutions/about-us/documents/NVIDIA-Trademark-and-Logo-Usage-Guidelines.pdf), including identification of the trademark owner and only in reference to output produced by the Licensed Materials. Referring to a trademark does not give you any ownership rights for that trademark and all use of any trademark shall inure to the sole benefit of NVIDIA. You may not change any trademark or trade name designation for the Licensed Materials. - -6. FEEDBACK. You may, but are not obligated to, provide to NVIDIA suggestions, fixes, modifications, feature requests or other feedback regarding the Licensed Materials (“Feedback”). Feedback, even if designated as confidential by Customer, will not create any confidentiality obligation for NVIDIA or its Affiliates beyond not identifying Customer as the source of the Feedback. If Customer provides Feedback, Customer hereby grants NVIDIA, its Affiliates and its designees a non-exclusive, perpetual, irrevocable, sublicensable, worldwide, royalty-free, fully paid-up, and transferable license, under Customer’s Intellectual Property Rights, to publicly perform, publicly display, reproduce, use, make, have made, sell, offer for sale, distribute (through multiple tiers of distribution), import, create derivative works of, and otherwise commercialize and exploit the Feedback for any purpose at NVIDIA’s discretion. NVIDIA agrees that Customer Feedback is provided “as-is” without a warranty of any kind. - -7. NO WARRANTIES. THE LICENSED MATERIALS ARE PROVIDED "AS IS". TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, NVIDIA DISCLAIMS ALL WARRANTIES AND REPRESENTATIONS OF ANY KIND, WHETHER EXPRESS, IMPLIED OR STATUTORY, RELATING TO OR ARISING UNDER THE AGREEMENT, INCLUDING, WITHOUT LIMITATION, THE WARRANTIES OF TITLE, NONINFRINGEMENT, MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, USAGE OF TRADE AND COURSE OF DEALING. NVIDIA DOES NOT WARRANT THAT THE LICENSED MATERIALS WILL MEET YOUR REQUIREMENTS OR THAT THE OPERATION THEREOF WILL BE UNINTERRUPTED OR ERROR-FREE, OR THAT ALL ERRORS WILL BE CORRECTED. NVIDIA does not warrant or assume responsibility for the accuracy or completeness of any information, text, graphics, links or other items contained within the Licensed Materials. - -8. LIMITATIONS OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT WILL NVIDIA BE LIABLE FOR ANY (I) INDIRECT, PUNITIVE, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES, OR (II) DAMAGES FOR THE (A) COST OF PROCURING SUBSTITUTE GOODS OR (B) LOSS OF PROFITS, REVENUES, USE, DATA OR GOODWILL ARISING OUT OF OR RELATED TO THIS AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), STRICT LIABILITY, OR OTHERWISE, AND EVEN IF NVIDIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES AND EVEN IF A PARTY'S REMEDIES FAIL THEIR ESSENTIAL PURPOSE. ADDITIONALLY, TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, NVIDIA’S TOTAL CUMULATIVE AGGREGATE LIABILITY FOR ANY AND ALL LIABILITIES, OBLIGATIONS OR CLAIMS ARISING OUT OF OR RELATED TO THIS AGREEMENT WILL NOT EXCEED TEN U.S. DOLLARS (US$10). - -9. TERMINATION. Your rights under this AGREEMENT will terminate automatically without notice from NVIDIA if you fail to comply with any term of this AGREEMENT or if you commence or participate in any legal proceeding against NVIDIA with respect to the Licensed Materials. NVIDIA may terminate this AGREEMENT with advance written notice to you. Upon any termination of this AGREEMENT, you agree to promptly discontinue use of the Licensed Materials and destroy all copies in your possession or control. All provisions of this AGREMENT will survive termination, except for the license granted to you and Section 3. - -10. APPLICABLE LAW. This AGREEMENT will be governed in all respects by the laws of the United States and of the State of Delaware, without regard to the conflicts of laws principles. The United Nations Convention on Contracts for the International Sale of Goods is specifically disclaimed. You agree to all terms of this AGREEMENT in the English language. The state or federal courts residing in Santa Clara County, California shall have exclusive jurisdiction over any dispute or claim arising out of this AGREEMENT. Notwithstanding this, you agree that NVIDIA shall still be allowed to apply for injunctive remedies or an equivalent type of urgent legal relief in any jurisdiction. - -11. NO ASSIGNMENT. This AGREMEENT and your rights and obligations thereunder may not be assigned by you by any means or operation of law without NVIDIA’s permission. Any attempted assignment not approved by NVIDIA in writing shall be void and of no effect. - -12. EXPORT. The Licensed Materials is subject to United States export laws and regulations. You agree to comply with all applicable U.S. and international export laws, including the Export Administration Regulations (EAR) administered by the U.S. Department of Commerce and economic sanctions administered by the U.S. Department of Treasury’s Office of Foreign Assets Control (OFAC). These laws include restrictions on destinations, end-users and end-use. By accepting this AGREEMENT, you confirm that you are not currently residing in a country or region currently embargoed by the U.S. and that you are not otherwise prohibited from receiving the Licensed Materials. - -13. GOVERNMENT USE. The Software, including its documentation and technology (“Protected Items”), are “Commercial products” as this term is defined at 48 C.F.R. 2.101, consisting of “commercial computer software” and “commercial computer software documentation” as such terms are used in, respectively, 48 C.F.R. 12.212 and 48 C.F.R. 227.7202 & 252.227-7014(a)(1). Before any Protected Items are supplied to the U.S. Government, you will (i) inform the U.S. Government in writing that the Protected Items are and must be treated as commercial computer software and commercial computer software documentation developed at private expense; (ii) inform the U.S. Government that the Protected Items are provided subject to the terms of this Agreement; and (iii) mark the Protected Items as commercial computer software and commercial computer software documentation developed at private expense. In no event will you permit the U.S. Government to acquire rights in Protected Items beyond those specified in 48 C.F.R. 52.227-19(b)(1)-(2) or 252.227-7013(c) except as expressly approved by NVIDIA in writing. - -14. NOTICES. Please direct your legal notices or other correspondence to NVIDIA Corporation, 2788 San Tomas Expressway, Santa Clara, California 95051, United States of America, Attention: Legal Department, with an emailed copy to legalnotices@nvidia.com. - -15. ENTIRE AGREEMENT. Regarding the subject matter of this Agreement, the parties agree that this Agreement constitutes the entire and exclusive agreement between the parties regarding the Licensed Materials and supersedes all prior and contemporaneous communications. If any provision of this Agreement is deemed invalid by a court of competent jurisdiction, the invalidity of such provision will not affect the validity of the remaining provisions of this Agreement, which will remain in full force and effect. - -(v. July 1, 2024) -``` - ## orjson (3.11.9) ### Licenses @@ -4894,34 +3767,6 @@ found in LICENSE.APACHE or LICENSE.BSD. Contributions to this software is made under the terms of *both* these licenses. ``` -## parsimonious (0.10.0) - -### Licenses -License: `MIT` - - - `LICENSE`: -``` -Copyright (c) 2012 Erik Rose - -Permission is hereby granted, free of charge, to any person obtaining a copy of -this software and associated documentation files (the "Software"), to deal in -the Software without restriction, including without limitation the rights to -use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies -of the Software, and to permit persons to whom the Software is furnished to do -so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. -``` - ## parso (0.8.6) ### Licenses @@ -5664,44 +4509,6 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ``` -## pydata-sphinx-theme (0.17.0) - -### Licenses -License: `BSD License` - - - `LICENSE`: -``` -BSD 3-Clause License - -Copyright (c) 2018, pandas -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -* Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -* Neither the name of the copyright holder nor the names of its - contributors may be used to endorse or promote products derived from - this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -``` - ## pygments (2.20.0) ### Licenses @@ -6062,21 +4869,14 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ``` -## regex (2026.4.4) +## requests (2.33.1) ### Licenses -License: `Apache-2.0 AND CNRI-Python` +License: `Apache-2.0` - - `LICENSE.txt`: + - `LICENSE`: ``` -This work was derived from the 're' module of CPython 2.6 and CPython 3.1, -copyright (c) 1998-2001 by Secret Labs AB and licensed under CNRI's Python 1.6 -license. - -All additions and alterations are licensed under the Apache 2.0 License. - - - Apache License +Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ @@ -6250,27 +5050,22 @@ All additions and alterations are licensed under the Apache 2.0 License. defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. +``` - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. +## requests-toolbelt (1.0.0) - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. +### Licenses +License: `Apache 2.0` - Copyright 2020 Matthew Barnett + - `LICENSE`: +``` +Copyright 2014 Ian Cordasco, Cory Benfield Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - http://www.apache.org/licenses/LICENSE-2.0 + https://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, @@ -6279,565 +5074,50 @@ All additions and alterations are licensed under the Apache 2.0 License. limitations under the License. ``` -## requests (2.33.1) +## ruff (0.15.9) ### Licenses -License: `Apache-2.0` +License: `MIT` - `LICENSE`: ``` -Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ +MIT License - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION +Copyright (c) 2022 Charles Marsh - 1. Definitions. +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. +end of terms and conditions - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. +The externally maintained libraries from which parts of the Software is derived +are: - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. +- autoflake, licensed as follows: + """ + Copyright (C) 2012-2018 Steven Myint - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. -``` - -## requests-toolbelt (1.0.0) - -### Licenses -License: `Apache 2.0` - - - `LICENSE`: -``` -Copyright 2014 Ian Cordasco, Cory Benfield - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - https://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. -``` - -## roman-numerals (4.1.0) - -### Licenses -License: `0BSD OR CC0-1.0` - - - `LICENCE.rst`: -``` -========= - Licence -========= - -This project is licenced under the terms of either the `Zero-Clause BSD licence`_ -or the `CC0 1.0 Universal licence`_. - - -Zero-Clause BSD Licence -======================= - -Copyright (c) 2024, Adam Turner - -Permission to use, copy, modify, and/or distribute this software for -any purpose with or without fee is hereby granted. - -THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL -WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES -OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE -FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY -DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN -AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT -OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. - - -CC0 1.0 Universal licence -========================= - -Statement of Purpose --------------------- - -The laws of most jurisdictions throughout the world automatically confer -exclusive Copyright and Related Rights (defined below) upon the creator -and subsequent owner(s) (each and all, an "owner") of an original work of -authorship and/or a database (each, a "Work"). - -Certain owners wish to permanently relinquish those rights to a Work for -the purpose of contributing to a commons of creative, cultural and -scientific works ("Commons") that the public can reliably and without fear -of later claims of infringement build upon, modify, incorporate in other -works, reuse and redistribute as freely as possible in any form whatsoever -and for any purposes, including without limitation commercial purposes. -These owners may contribute to the Commons to promote the ideal of a free -culture and the further production of creative, cultural and scientific -works, or to gain reputation or greater distribution for their Work in -part through the use and efforts of others. - -For these and/or other purposes and motivations, and without any -expectation of additional consideration or compensation, the person -associating CC0 with a Work (the "Affirmer"), to the extent that he or she -is an owner of Copyright and Related Rights in the Work, voluntarily -elects to apply CC0 to the Work and publicly distribute the Work under its -terms, with knowledge of his or her Copyright and Related Rights in the -Work and the meaning and intended legal effect of CC0 on those rights. - -1. Copyright and Related Rights. --------------------------------- - -A Work made available under CC0 may be protected by copyright and related -or neighboring rights ("Copyright and Related Rights"). -Copyright and Related Rights include, but are not limited to, the following: - -i. the right to reproduce, adapt, distribute, perform, display, - communicate, and translate a Work; -ii. moral rights retained by the original author(s) and/or performer(s); -iii. publicity and privacy rights pertaining to a person's image or - likeness depicted in a Work; -iv. rights protecting against unfair competition in regards to a Work, - subject to the limitations in paragraph 4(a), below; -v. rights protecting the extraction, dissemination, use and reuse of data - in a Work; -vi. database rights (such as those arising under Directive 96/9/EC of the - European Parliament and of the Council of 11 March 1996 on the legal - protection of databases, and under any national implementation - thereof, including any amended or successor version of such - directive); and -vii. other similar, equivalent or corresponding rights throughout the - world based on applicable law or treaty, and any national - implementations thereof. - -2. Waiver. ----------- - -To the greatest extent permitted by, but not in contravention -of, applicable law, Affirmer hereby overtly, fully, permanently, -irrevocably and unconditionally waives, abandons, and surrenders all of -Affirmer's Copyright and Related Rights and associated claims and causes -of action, whether now known or unknown (including existing as well as -future claims and causes of action), in the Work (i) in all territories -worldwide, (ii) for the maximum duration provided by applicable law or -treaty (including future time extensions), (iii) in any current or future -medium and for any number of copies, and (iv) for any purpose whatsoever, -including without limitation commercial, advertising or promotional -purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each -member of the public at large and to the detriment of Affirmer's heirs and -successors, fully intending that such Waiver shall not be subject to -revocation, rescission, cancellation, termination, or any other legal or -equitable action to disrupt the quiet enjoyment of the Work by the public -as contemplated by Affirmer's express Statement of Purpose. - -3. Public License Fallback. ---------------------------- - -Should any part of the Waiver for any reason be judged legally invalid -or ineffective under applicable law, then the Waiver shall be preserved -to the maximum extent permitted taking into account Affirmer's express -Statement of Purpose. In addition, to the extent the Waiver is so judged -Affirmer hereby grants to each affected person a royalty-free, -non transferable, non sublicensable, non exclusive, irrevocable -and unconditional license to exercise Affirmer's Copyright and -Related Rights in the Work (i) in all territories worldwide, (ii) for the -maximum duration provided by applicable law or treaty (including future -time extensions), (iii) in any current or future medium and for any number -of copies, and (iv) for any purpose whatsoever, including without -limitation commercial, advertising or promotional purposes (the -"License"). The License shall be deemed effective as of the date CC0 was -applied by Affirmer to the Work. Should any part of the License for any -reason be judged legally invalid or ineffective under applicable law, such -partial invalidity or ineffectiveness shall not invalidate the remainder -of the License, and in such case Affirmer hereby affirms that he or she -will not (i) exercise any of his or her remaining Copyright and Related -Rights in the Work or (ii) assert any associated claims and causes of -action with respect to the Work, in either case contrary to Affirmer's -express Statement of Purpose. - -4. Limitations and Disclaimers. -------------------------------- - -a. No trademark or patent rights held by Affirmer are waived, abandoned, - surrendered, licensed or otherwise affected by this document. -b. Affirmer offers the Work as-is and makes no representations or - warranties of any kind concerning the Work, express, implied, - statutory or otherwise, including without limitation warranties of - title, merchantability, fitness for a particular purpose, non - infringement, or the absence of latent or other defects, accuracy, or - the present or absence of errors, whether or not discoverable, all to - the greatest extent permissible under applicable law. -c. Affirmer disclaims responsibility for clearing rights of other persons - that may apply to the Work or any use thereof, including without - limitation any person's Copyright and Related Rights in the Work. - Further, Affirmer disclaims responsibility for obtaining any necessary - consents, permissions or other rights required for any use of the - Work. -d. Affirmer understands and acknowledges that Creative Commons is not a - party to this document and has no duty or obligation with respect to - this CC0 or use of the Work. -``` - -## roman-numerals-py (4.1.0) - -### Licenses -License: `0BSD OR CC0-1.0` - - - `LICENCE.rst`: -``` -========= - Licence -========= - -This project is licenced under the terms of either the `Zero-Clause BSD licence`_ -or the `CC0 1.0 Universal licence`_. - - -Zero-Clause BSD Licence -======================= - -Copyright (c) 2024, Adam Turner - -Permission to use, copy, modify, and/or distribute this software for -any purpose with or without fee is hereby granted. - -THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL -WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES -OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE -FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY -DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN -AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT -OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. - - -CC0 1.0 Universal licence -========================= - -Statement of Purpose --------------------- - -The laws of most jurisdictions throughout the world automatically confer -exclusive Copyright and Related Rights (defined below) upon the creator -and subsequent owner(s) (each and all, an "owner") of an original work of -authorship and/or a database (each, a "Work"). - -Certain owners wish to permanently relinquish those rights to a Work for -the purpose of contributing to a commons of creative, cultural and -scientific works ("Commons") that the public can reliably and without fear -of later claims of infringement build upon, modify, incorporate in other -works, reuse and redistribute as freely as possible in any form whatsoever -and for any purposes, including without limitation commercial purposes. -These owners may contribute to the Commons to promote the ideal of a free -culture and the further production of creative, cultural and scientific -works, or to gain reputation or greater distribution for their Work in -part through the use and efforts of others. - -For these and/or other purposes and motivations, and without any -expectation of additional consideration or compensation, the person -associating CC0 with a Work (the "Affirmer"), to the extent that he or she -is an owner of Copyright and Related Rights in the Work, voluntarily -elects to apply CC0 to the Work and publicly distribute the Work under its -terms, with knowledge of his or her Copyright and Related Rights in the -Work and the meaning and intended legal effect of CC0 on those rights. - -1. Copyright and Related Rights. --------------------------------- - -A Work made available under CC0 may be protected by copyright and related -or neighboring rights ("Copyright and Related Rights"). -Copyright and Related Rights include, but are not limited to, the following: - -i. the right to reproduce, adapt, distribute, perform, display, - communicate, and translate a Work; -ii. moral rights retained by the original author(s) and/or performer(s); -iii. publicity and privacy rights pertaining to a person's image or - likeness depicted in a Work; -iv. rights protecting against unfair competition in regards to a Work, - subject to the limitations in paragraph 4(a), below; -v. rights protecting the extraction, dissemination, use and reuse of data - in a Work; -vi. database rights (such as those arising under Directive 96/9/EC of the - European Parliament and of the Council of 11 March 1996 on the legal - protection of databases, and under any national implementation - thereof, including any amended or successor version of such - directive); and -vii. other similar, equivalent or corresponding rights throughout the - world based on applicable law or treaty, and any national - implementations thereof. - -2. Waiver. ----------- - -To the greatest extent permitted by, but not in contravention -of, applicable law, Affirmer hereby overtly, fully, permanently, -irrevocably and unconditionally waives, abandons, and surrenders all of -Affirmer's Copyright and Related Rights and associated claims and causes -of action, whether now known or unknown (including existing as well as -future claims and causes of action), in the Work (i) in all territories -worldwide, (ii) for the maximum duration provided by applicable law or -treaty (including future time extensions), (iii) in any current or future -medium and for any number of copies, and (iv) for any purpose whatsoever, -including without limitation commercial, advertising or promotional -purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each -member of the public at large and to the detriment of Affirmer's heirs and -successors, fully intending that such Waiver shall not be subject to -revocation, rescission, cancellation, termination, or any other legal or -equitable action to disrupt the quiet enjoyment of the Work by the public -as contemplated by Affirmer's express Statement of Purpose. - -3. Public License Fallback. ---------------------------- - -Should any part of the Waiver for any reason be judged legally invalid -or ineffective under applicable law, then the Waiver shall be preserved -to the maximum extent permitted taking into account Affirmer's express -Statement of Purpose. In addition, to the extent the Waiver is so judged -Affirmer hereby grants to each affected person a royalty-free, -non transferable, non sublicensable, non exclusive, irrevocable -and unconditional license to exercise Affirmer's Copyright and -Related Rights in the Work (i) in all territories worldwide, (ii) for the -maximum duration provided by applicable law or treaty (including future -time extensions), (iii) in any current or future medium and for any number -of copies, and (iv) for any purpose whatsoever, including without -limitation commercial, advertising or promotional purposes (the -"License"). The License shall be deemed effective as of the date CC0 was -applied by Affirmer to the Work. Should any part of the License for any -reason be judged legally invalid or ineffective under applicable law, such -partial invalidity or ineffectiveness shall not invalidate the remainder -of the License, and in such case Affirmer hereby affirms that he or she -will not (i) exercise any of his or her remaining Copyright and Related -Rights in the Work or (ii) assert any associated claims and causes of -action with respect to the Work, in either case contrary to Affirmer's -express Statement of Purpose. - -4. Limitations and Disclaimers. -------------------------------- - -a. No trademark or patent rights held by Affirmer are waived, abandoned, - surrendered, licensed or otherwise affected by this document. -b. Affirmer offers the Work as-is and makes no representations or - warranties of any kind concerning the Work, express, implied, - statutory or otherwise, including without limitation warranties of - title, merchantability, fitness for a particular purpose, non - infringement, or the absence of latent or other defects, accuracy, or - the present or absence of errors, whether or not discoverable, all to - the greatest extent permissible under applicable law. -c. Affirmer disclaims responsibility for clearing rights of other persons - that may apply to the Work or any use thereof, including without - limitation any person's Copyright and Related Rights in the Work. - Further, Affirmer disclaims responsibility for obtaining any necessary - consents, permissions or other rights required for any use of the - Work. -d. Affirmer understands and acknowledges that Creative Commons is not a - party to this document and has no duty or obligation with respect to - this CC0 or use of the Work. -``` - -## ruff (0.15.9) - -### Licenses -License: `MIT` - - - `LICENSE`: -``` -MIT License - -Copyright (c) 2022 Charles Marsh - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. - -end of terms and conditions - -The externally maintained libraries from which parts of the Software is derived -are: - -- autoflake, licensed as follows: - """ - Copyright (C) 2012-2018 Steven Myint - - Permission is hereby granted, free of charge, to any person obtaining a copy of - this software and associated documentation files (the "Software"), to deal in - the Software without restriction, including without limitation the rights to - use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies - of the Software, and to permit persons to whom the Software is furnished to do - so, subject to the following conditions: + Permission is hereby granted, free of charge, to any person obtaining a copy of + this software and associated documentation files (the "Software"), to deal in + the Software without restriction, including without limitation the rights to + use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies + of the Software, and to permit persons to whom the Software is furnished to do + so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. @@ -7245,195 +5525,23 @@ licenses found in LICENSE.APACHE2 or LICENSE.MIT. Contributions to are made under the terms of *both* these licenses. ``` -## snowballstemmer (3.0.1) +## soupsieve (2.8.3) ### Licenses -License: `BSD-3-Clause` +License: `MIT` - - `COPYING`: + - `LICENSE.md`: ``` -Copyright (c) 2001, Dr Martin Porter -Copyright (c) 2004,2005, Richard Boulton -Copyright (c) 2013, Yoshiki Shibukawa -Copyright (c) 2006,2007,2009,2010,2011,2014-2019, Olly Betts -All rights reserved. +MIT License -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions -are met: +Copyright (c) 2018 - 2026 Isaac Muse - 1. Redistributions of source code must retain the above copyright notice, - this list of conditions and the following disclaimer. - 2. Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - 3. Neither the name of the Snowball project nor the names of its contributors - may be used to endorse or promote products derived from this software - without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND -ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR -ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON -ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -``` - -## soupsieve (2.8.3) - -### Licenses -License: `MIT` - - - `LICENSE.md`: -``` -MIT License - -Copyright (c) 2018 - 2026 Isaac Muse - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. -``` - -## sphinx (8.2.3) - -### Licenses -License: `BSD-2-Clause` - - - `LICENSE.rst`: -``` -License for Sphinx -================== - -Unless otherwise indicated, all code in the Sphinx project is licenced under the -two clause BSD licence below. - -Copyright (c) 2007-2025 by the Sphinx team (see AUTHORS file). -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -* Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -``` - -## sphinx-autoapi (3.8.0) - -### Licenses -License: `MIT` - - - `LICENSE.rst`: -``` -The MIT License (MIT) -===================== - -Copyright (c) 2015 Read the Docs, Inc - -Permission is hereby granted, free of charge, to any person -obtaining a copy of this software and associated documentation -files (the "Software"), to deal in the Software without -restriction, including without limitation the rights to use, -copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the -Software is furnished to do so, subject to the following -conditions: - -The above copyright notice and this permission notice shall be -included in all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, -EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES -OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND -NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT -HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, -WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING -FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -OTHER DEALINGS IN THE SOFTWARE. -``` - -## sphinx-design (0.7.0) - -### Licenses -License: `MIT` - - - `LICENSE`: -``` -MIT License Copyright (c) 2023 Chris Sewell - -Permission is hereby granted, free -of charge, to any person obtaining a copy of this software and associated -documentation files (the "Software"), to deal in the Software without -restriction, including without limitation the rights to use, copy, modify, merge, -publish, distribute, sublicense, and/or sell copies of the Software, and to -permit persons to whom the Software is furnished to do so, subject to the -following conditions: - -The above copyright notice and this permission notice -(including the next paragraph) shall be included in all copies or substantial -portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF -ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO -EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR -OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING -FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN -THE SOFTWARE. -``` - -## sphinx-js (5.0.3) - -### Licenses -License: `MIT` - - - `LICENSE`: -``` -MIT License - -Copyright (c) 2017 Mozilla Foundation - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. @@ -7447,909 +5555,6 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ``` -## sphinx-multiversion (0.2.4) - -### Licenses -License: `BSD` - - - `LICENSE`: -``` -(No license file found in locked artifact for sphinx-multiversion; see package metadata or PyPI.) -``` - -## sphinxcontrib-applehelp (2.0.0) - -### Licenses -License: `BSD License` - - - `LICENCE.rst`: -``` -License for sphinxcontrib-applehelp -=================================== - -Copyright (c) 2007-2019 by the Sphinx team -(see https://github.com/sphinx-doc/sphinx/blob/master/AUTHORS). -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -* Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -``` - -## sphinxcontrib-devhelp (2.0.0) - -### Licenses -License: `BSD License` - - - `LICENCE.rst`: -``` -License for sphinxcontrib-devhelp -================================= - -Copyright (c) 2007-2019 by the Sphinx team -(see https://github.com/sphinx-doc/sphinx/blob/master/AUTHORS). -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -* Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -``` - -## sphinxcontrib-htmlhelp (2.1.0) - -### Licenses -License: `BSD License` - - - `LICENCE.rst`: -``` -License for sphinxcontrib-htmlhelp -================================== - -Copyright (c) 2007-2019 by the Sphinx team -(see https://github.com/sphinx-doc/sphinx/blob/master/AUTHORS). -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -* Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -``` - -## sphinxcontrib-jsmath (1.0.1) - -### Licenses -License: `BSD` - - - `LICENSE`: -``` -License for sphinxcontrib-jsmath -================================ - -Copyright (c) 2007-2019 by the Sphinx team -(see https://github.com/sphinx-doc/sphinx/blob/master/AUTHORS). -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -* Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -``` - -## sphinxcontrib-mermaid (1.2.3) - -### Licenses -License: `BSD` - - - `LICENSE.rst`: -``` -| sphinxcontrib-mermaid is a Sphinx extension for Mermaid Diagrams -| Copyright (c) 2016 by Martín Gaitán -| All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -* Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -``` - -## sphinxcontrib-qthelp (2.0.0) - -### Licenses -License: `BSD License` - - - `LICENCE.rst`: -``` -License for sphinxcontrib-qthelp -================================ - -Copyright (c) 2007-2019 by the Sphinx team -(see https://github.com/sphinx-doc/sphinx/blob/master/AUTHORS). -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -* Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -``` - -## sphinxcontrib-rust (1.0.1) - -### Licenses -License: `GPL-3.0-or-later` - - - `LICENSE`: -``` -GNU GENERAL PUBLIC LICENSE - Version 3, 29 June 2007 - - Copyright (C) 2007 Free Software Foundation, Inc. - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - Preamble - - The GNU General Public License is a free, copyleft license for -software and other kinds of works. - - The licenses for most software and other practical works are designed -to take away your freedom to share and change the works. By contrast, -the GNU General Public License is intended to guarantee your freedom to -share and change all versions of a program--to make sure it remains free -software for all its users. We, the Free Software Foundation, use the -GNU General Public License for most of our software; it applies also to -any other work released this way by its authors. You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -them if you wish), that you receive source code or can get it if you -want it, that you can change the software or use pieces of it in new -free programs, and that you know you can do these things. - - To protect your rights, we need to prevent others from denying you -these rights or asking you to surrender the rights. Therefore, you have -certain responsibilities if you distribute copies of the software, or if -you modify it: responsibilities to respect the freedom of others. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must pass on to the recipients the same -freedoms that you received. You must make sure that they, too, receive -or can get the source code. And you must show them these terms so they -know their rights. - - Developers that use the GNU GPL protect your rights with two steps: -(1) assert copyright on the software, and (2) offer you this License -giving you legal permission to copy, distribute and/or modify it. - - For the developers' and authors' protection, the GPL clearly explains -that there is no warranty for this free software. For both users' and -authors' sake, the GPL requires that modified versions be marked as -changed, so that their problems will not be attributed erroneously to -authors of previous versions. - - Some devices are designed to deny users access to install or run -modified versions of the software inside them, although the manufacturer -can do so. This is fundamentally incompatible with the aim of -protecting users' freedom to change the software. The systematic -pattern of such abuse occurs in the area of products for individuals to -use, which is precisely where it is most unacceptable. Therefore, we -have designed this version of the GPL to prohibit the practice for those -products. If such problems arise substantially in other domains, we -stand ready to extend this provision to those domains in future versions -of the GPL, as needed to protect the freedom of users. - - Finally, every program is threatened constantly by software patents. -States should not allow patents to restrict development and use of -software on general-purpose computers, but in those that do, we wish to -avoid the special danger that patents applied to a free program could -make it effectively proprietary. To prevent this, the GPL assures that -patents cannot be used to render the program non-free. - - The precise terms and conditions for copying, distribution and -modification follow. - - TERMS AND CONDITIONS - - 0. Definitions. - - "This License" refers to version 3 of the GNU General Public License. - - "Copyright" also means copyright-like laws that apply to other kinds of -works, such as semiconductor masks. - - "The Program" refers to any copyrightable work licensed under this -License. Each licensee is addressed as "you". "Licensees" and -"recipients" may be individuals or organizations. - - To "modify" a work means to copy from or adapt all or part of the work -in a fashion requiring copyright permission, other than the making of an -exact copy. The resulting work is called a "modified version" of the -earlier work or a work "based on" the earlier work. - - A "covered work" means either the unmodified Program or a work based -on the Program. - - To "propagate" a work means to do anything with it that, without -permission, would make you directly or secondarily liable for -infringement under applicable copyright law, except executing it on a -computer or modifying a private copy. Propagation includes copying, -distribution (with or without modification), making available to the -public, and in some countries other activities as well. - - To "convey" a work means any kind of propagation that enables other -parties to make or receive copies. Mere interaction with a user through -a computer network, with no transfer of a copy, is not conveying. - - An interactive user interface displays "Appropriate Legal Notices" -to the extent that it includes a convenient and prominently visible -feature that (1) displays an appropriate copyright notice, and (2) -tells the user that there is no warranty for the work (except to the -extent that warranties are provided), that licensees may convey the -work under this License, and how to view a copy of this License. If -the interface presents a list of user commands or options, such as a -menu, a prominent item in the list meets this criterion. - - 1. Source Code. - - The "source code" for a work means the preferred form of the work -for making modifications to it. "Object code" means any non-source -form of a work. - - A "Standard Interface" means an interface that either is an official -standard defined by a recognized standards body, or, in the case of -interfaces specified for a particular programming language, one that -is widely used among developers working in that language. - - The "System Libraries" of an executable work include anything, other -than the work as a whole, that (a) is included in the normal form of -packaging a Major Component, but which is not part of that Major -Component, and (b) serves only to enable use of the work with that -Major Component, or to implement a Standard Interface for which an -implementation is available to the public in source code form. A -"Major Component", in this context, means a major essential component -(kernel, window system, and so on) of the specific operating system -(if any) on which the executable work runs, or a compiler used to -produce the work, or an object code interpreter used to run it. - - The "Corresponding Source" for a work in object code form means all -the source code needed to generate, install, and (for an executable -work) run the object code and to modify the work, including scripts to -control those activities. However, it does not include the work's -System Libraries, or general-purpose tools or generally available free -programs which are used unmodified in performing those activities but -which are not part of the work. For example, Corresponding Source -includes interface definition files associated with source files for -the work, and the source code for shared libraries and dynamically -linked subprograms that the work is specifically designed to require, -such as by intimate data communication or control flow between those -subprograms and other parts of the work. - - The Corresponding Source need not include anything that users -can regenerate automatically from other parts of the Corresponding -Source. - - The Corresponding Source for a work in source code form is that -same work. - - 2. Basic Permissions. - - All rights granted under this License are granted for the term of -copyright on the Program, and are irrevocable provided the stated -conditions are met. This License explicitly affirms your unlimited -permission to run the unmodified Program. The output from running a -covered work is covered by this License only if the output, given its -content, constitutes a covered work. This License acknowledges your -rights of fair use or other equivalent, as provided by copyright law. - - You may make, run and propagate covered works that you do not -convey, without conditions so long as your license otherwise remains -in force. You may convey covered works to others for the sole purpose -of having them make modifications exclusively for you, or provide you -with facilities for running those works, provided that you comply with -the terms of this License in conveying all material for which you do -not control copyright. Those thus making or running the covered works -for you must do so exclusively on your behalf, under your direction -and control, on terms that prohibit them from making any copies of -your copyrighted material outside their relationship with you. - - Conveying under any other circumstances is permitted solely under -the conditions stated below. Sublicensing is not allowed; section 10 -makes it unnecessary. - - 3. Protecting Users' Legal Rights From Anti-Circumvention Law. - - No covered work shall be deemed part of an effective technological -measure under any applicable law fulfilling obligations under article -11 of the WIPO copyright treaty adopted on 20 December 1996, or -similar laws prohibiting or restricting circumvention of such -measures. - - When you convey a covered work, you waive any legal power to forbid -circumvention of technological measures to the extent such circumvention -is effected by exercising rights under this License with respect to -the covered work, and you disclaim any intention to limit operation or -modification of the work as a means of enforcing, against the work's -users, your or third parties' legal rights to forbid circumvention of -technological measures. - - 4. Conveying Verbatim Copies. - - You may convey verbatim copies of the Program's source code as you -receive it, in any medium, provided that you conspicuously and -appropriately publish on each copy an appropriate copyright notice; -keep intact all notices stating that this License and any -non-permissive terms added in accord with section 7 apply to the code; -keep intact all notices of the absence of any warranty; and give all -recipients a copy of this License along with the Program. - - You may charge any price or no price for each copy that you convey, -and you may offer support or warranty protection for a fee. - - 5. Conveying Modified Source Versions. - - You may convey a work based on the Program, or the modifications to -produce it from the Program, in the form of source code under the -terms of section 4, provided that you also meet all of these conditions: - - a) The work must carry prominent notices stating that you modified - it, and giving a relevant date. - - b) The work must carry prominent notices stating that it is - released under this License and any conditions added under section - 7. This requirement modifies the requirement in section 4 to - "keep intact all notices". - - c) You must license the entire work, as a whole, under this - License to anyone who comes into possession of a copy. This - License will therefore apply, along with any applicable section 7 - additional terms, to the whole of the work, and all its parts, - regardless of how they are packaged. This License gives no - permission to license the work in any other way, but it does not - invalidate such permission if you have separately received it. - - d) If the work has interactive user interfaces, each must display - Appropriate Legal Notices; however, if the Program has interactive - interfaces that do not display Appropriate Legal Notices, your - work need not make them do so. - - A compilation of a covered work with other separate and independent -works, which are not by their nature extensions of the covered work, -and which are not combined with it such as to form a larger program, -in or on a volume of a storage or distribution medium, is called an -"aggregate" if the compilation and its resulting copyright are not -used to limit the access or legal rights of the compilation's users -beyond what the individual works permit. Inclusion of a covered work -in an aggregate does not cause this License to apply to the other -parts of the aggregate. - - 6. Conveying Non-Source Forms. - - You may convey a covered work in object code form under the terms -of sections 4 and 5, provided that you also convey the -machine-readable Corresponding Source under the terms of this License, -in one of these ways: - - a) Convey the object code in, or embodied in, a physical product - (including a physical distribution medium), accompanied by the - Corresponding Source fixed on a durable physical medium - customarily used for software interchange. - - b) Convey the object code in, or embodied in, a physical product - (including a physical distribution medium), accompanied by a - written offer, valid for at least three years and valid for as - long as you offer spare parts or customer support for that product - model, to give anyone who possesses the object code either (1) a - copy of the Corresponding Source for all the software in the - product that is covered by this License, on a durable physical - medium customarily used for software interchange, for a price no - more than your reasonable cost of physically performing this - conveying of source, or (2) access to copy the - Corresponding Source from a network server at no charge. - - c) Convey individual copies of the object code with a copy of the - written offer to provide the Corresponding Source. This - alternative is allowed only occasionally and noncommercially, and - only if you received the object code with such an offer, in accord - with subsection 6b. - - d) Convey the object code by offering access from a designated - place (gratis or for a charge), and offer equivalent access to the - Corresponding Source in the same way through the same place at no - further charge. You need not require recipients to copy the - Corresponding Source along with the object code. If the place to - copy the object code is a network server, the Corresponding Source - may be on a different server (operated by you or a third party) - that supports equivalent copying facilities, provided you maintain - clear directions next to the object code saying where to find the - Corresponding Source. Regardless of what server hosts the - Corresponding Source, you remain obligated to ensure that it is - available for as long as needed to satisfy these requirements. - - e) Convey the object code using peer-to-peer transmission, provided - you inform other peers where the object code and Corresponding - Source of the work are being offered to the general public at no - charge under subsection 6d. - - A separable portion of the object code, whose source code is excluded -from the Corresponding Source as a System Library, need not be -included in conveying the object code work. - - A "User Product" is either (1) a "consumer product", which means any -tangible personal property which is normally used for personal, family, -or household purposes, or (2) anything designed or sold for incorporation -into a dwelling. In determining whether a product is a consumer product, -doubtful cases shall be resolved in favor of coverage. For a particular -product received by a particular user, "normally used" refers to a -typical or common use of that class of product, regardless of the status -of the particular user or of the way in which the particular user -actually uses, or expects or is expected to use, the product. A product -is a consumer product regardless of whether the product has substantial -commercial, industrial or non-consumer uses, unless such uses represent -the only significant mode of use of the product. - - "Installation Information" for a User Product means any methods, -procedures, authorization keys, or other information required to install -and execute modified versions of a covered work in that User Product from -a modified version of its Corresponding Source. The information must -suffice to ensure that the continued functioning of the modified object -code is in no case prevented or interfered with solely because -modification has been made. - - If you convey an object code work under this section in, or with, or -specifically for use in, a User Product, and the conveying occurs as -part of a transaction in which the right of possession and use of the -User Product is transferred to the recipient in perpetuity or for a -fixed term (regardless of how the transaction is characterized), the -Corresponding Source conveyed under this section must be accompanied -by the Installation Information. But this requirement does not apply -if neither you nor any third party retains the ability to install -modified object code on the User Product (for example, the work has -been installed in ROM). - - The requirement to provide Installation Information does not include a -requirement to continue to provide support service, warranty, or updates -for a work that has been modified or installed by the recipient, or for -the User Product in which it has been modified or installed. Access to a -network may be denied when the modification itself materially and -adversely affects the operation of the network or violates the rules and -protocols for communication across the network. - - Corresponding Source conveyed, and Installation Information provided, -in accord with this section must be in a format that is publicly -documented (and with an implementation available to the public in -source code form), and must require no special password or key for -unpacking, reading or copying. - - 7. Additional Terms. - - "Additional permissions" are terms that supplement the terms of this -License by making exceptions from one or more of its conditions. -Additional permissions that are applicable to the entire Program shall -be treated as though they were included in this License, to the extent -that they are valid under applicable law. If additional permissions -apply only to part of the Program, that part may be used separately -under those permissions, but the entire Program remains governed by -this License without regard to the additional permissions. - - When you convey a copy of a covered work, you may at your option -remove any additional permissions from that copy, or from any part of -it. (Additional permissions may be written to require their own -removal in certain cases when you modify the work.) You may place -additional permissions on material, added by you to a covered work, -for which you have or can give appropriate copyright permission. - - Notwithstanding any other provision of this License, for material you -add to a covered work, you may (if authorized by the copyright holders of -that material) supplement the terms of this License with terms: - - a) Disclaiming warranty or limiting liability differently from the - terms of sections 15 and 16 of this License; or - - b) Requiring preservation of specified reasonable legal notices or - author attributions in that material or in the Appropriate Legal - Notices displayed by works containing it; or - - c) Prohibiting misrepresentation of the origin of that material, or - requiring that modified versions of such material be marked in - reasonable ways as different from the original version; or - - d) Limiting the use for publicity purposes of names of licensors or - authors of the material; or - - e) Declining to grant rights under trademark law for use of some - trade names, trademarks, or service marks; or - - f) Requiring indemnification of licensors and authors of that - material by anyone who conveys the material (or modified versions of - it) with contractual assumptions of liability to the recipient, for - any liability that these contractual assumptions directly impose on - those licensors and authors. - - All other non-permissive additional terms are considered "further -restrictions" within the meaning of section 10. If the Program as you -received it, or any part of it, contains a notice stating that it is -governed by this License along with a term that is a further -restriction, you may remove that term. If a license document contains -a further restriction but permits relicensing or conveying under this -License, you may add to a covered work material governed by the terms -of that license document, provided that the further restriction does -not survive such relicensing or conveying. - - If you add terms to a covered work in accord with this section, you -must place, in the relevant source files, a statement of the -additional terms that apply to those files, or a notice indicating -where to find the applicable terms. - - Additional terms, permissive or non-permissive, may be stated in the -form of a separately written license, or stated as exceptions; -the above requirements apply either way. - - 8. Termination. - - You may not propagate or modify a covered work except as expressly -provided under this License. Any attempt otherwise to propagate or -modify it is void, and will automatically terminate your rights under -this License (including any patent licenses granted under the third -paragraph of section 11). - - However, if you cease all violation of this License, then your -license from a particular copyright holder is reinstated (a) -provisionally, unless and until the copyright holder explicitly and -finally terminates your license, and (b) permanently, if the copyright -holder fails to notify you of the violation by some reasonable means -prior to 60 days after the cessation. - - Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - - Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, you do not qualify to receive new licenses for the same -material under section 10. - - 9. Acceptance Not Required for Having Copies. - - You are not required to accept this License in order to receive or -run a copy of the Program. Ancillary propagation of a covered work -occurring solely as a consequence of using peer-to-peer transmission -to receive a copy likewise does not require acceptance. However, -nothing other than this License grants you permission to propagate or -modify any covered work. These actions infringe copyright if you do -not accept this License. Therefore, by modifying or propagating a -covered work, you indicate your acceptance of this License to do so. - - 10. Automatic Licensing of Downstream Recipients. - - Each time you convey a covered work, the recipient automatically -receives a license from the original licensors, to run, modify and -propagate that work, subject to this License. You are not responsible -for enforcing compliance by third parties with this License. - - An "entity transaction" is a transaction transferring control of an -organization, or substantially all assets of one, or subdividing an -organization, or merging organizations. If propagation of a covered -work results from an entity transaction, each party to that -transaction who receives a copy of the work also receives whatever -licenses to the work the party's predecessor in interest had or could -give under the previous paragraph, plus a right to possession of the -Corresponding Source of the work from the predecessor in interest, if -the predecessor has it or can get it with reasonable efforts. - - You may not impose any further restrictions on the exercise of the -rights granted or affirmed under this License. For example, you may -not impose a license fee, royalty, or other charge for exercise of -rights granted under this License, and you may not initiate litigation -(including a cross-claim or counterclaim in a lawsuit) alleging that -any patent claim is infringed by making, using, selling, offering for -sale, or importing the Program or any portion of it. - - 11. Patents. - - A "contributor" is a copyright holder who authorizes use under this -License of the Program or a work on which the Program is based. The -work thus licensed is called the contributor's "contributor version". - - A contributor's "essential patent claims" are all patent claims -owned or controlled by the contributor, whether already acquired or -hereafter acquired, that would be infringed by some manner, permitted -by this License, of making, using, or selling its contributor version, -but do not include claims that would be infringed only as a -consequence of further modification of the contributor version. For -purposes of this definition, "control" includes the right to grant -patent sublicenses in a manner consistent with the requirements of -this License. - - Each contributor grants you a non-exclusive, worldwide, royalty-free -patent license under the contributor's essential patent claims, to -make, use, sell, offer for sale, import and otherwise run, modify and -propagate the contents of its contributor version. - - In the following three paragraphs, a "patent license" is any express -agreement or commitment, however denominated, not to enforce a patent -(such as an express permission to practice a patent or covenant not to -sue for patent infringement). To "grant" such a patent license to a -party means to make such an agreement or commitment not to enforce a -patent against the party. - - If you convey a covered work, knowingly relying on a patent license, -and the Corresponding Source of the work is not available for anyone -to copy, free of charge and under the terms of this License, through a -publicly available network server or other readily accessible means, -then you must either (1) cause the Corresponding Source to be so -available, or (2) arrange to deprive yourself of the benefit of the -patent license for this particular work, or (3) arrange, in a manner -consistent with the requirements of this License, to extend the patent -license to downstream recipients. "Knowingly relying" means you have -actual knowledge that, but for the patent license, your conveying the -covered work in a country, or your recipient's use of the covered work -in a country, would infringe one or more identifiable patents in that -country that you have reason to believe are valid. - - If, pursuant to or in connection with a single transaction or -arrangement, you convey, or propagate by procuring conveyance of, a -covered work, and grant a patent license to some of the parties -receiving the covered work authorizing them to use, propagate, modify -or convey a specific copy of the covered work, then the patent license -you grant is automatically extended to all recipients of the covered -work and works based on it. - - A patent license is "discriminatory" if it does not include within -the scope of its coverage, prohibits the exercise of, or is -conditioned on the non-exercise of one or more of the rights that are -specifically granted under this License. You may not convey a covered -work if you are a party to an arrangement with a third party that is -in the business of distributing software, under which you make payment -to the third party based on the extent of your activity of conveying -the work, and under which the third party grants, to any of the -parties who would receive the covered work from you, a discriminatory -patent license (a) in connection with copies of the covered work -conveyed by you (or copies made from those copies), or (b) primarily -for and in connection with specific products or compilations that -contain the covered work, unless you entered into that arrangement, -or that patent license was granted, prior to 28 March 2007. - - Nothing in this License shall be construed as excluding or limiting -any implied license or other defenses to infringement that may -otherwise be available to you under applicable patent law. - - 12. No Surrender of Others' Freedom. - - If conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot convey a -covered work so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you may -not convey it at all. For example, if you agree to terms that obligate you -to collect a royalty for further conveying from those to whom you convey -the Program, the only way you could satisfy both those terms and this -License would be to refrain entirely from conveying the Program. - - 13. Use with the GNU Affero General Public License. - - Notwithstanding any other provision of this License, you have -permission to link or combine any covered work with a work licensed -under version 3 of the GNU Affero General Public License into a single -combined work, and to convey the resulting work. The terms of this -License will continue to apply to the part which is the covered work, -but the special requirements of the GNU Affero General Public License, -section 13, concerning interaction through a network will apply to the -combination as such. - - 14. Revised Versions of this License. - - The Free Software Foundation may publish revised and/or new versions of -the GNU General Public License from time to time. Such new versions will -be similar in spirit to the present version, but may differ in detail to -address new problems or concerns. - - Each version is given a distinguishing version number. If the -Program specifies that a certain numbered version of the GNU General -Public License "or any later version" applies to it, you have the -option of following the terms and conditions either of that numbered -version or of any later version published by the Free Software -Foundation. If the Program does not specify a version number of the -GNU General Public License, you may choose any version ever published -by the Free Software Foundation. - - If the Program specifies that a proxy can decide which future -versions of the GNU General Public License can be used, that proxy's -public statement of acceptance of a version permanently authorizes you -to choose that version for the Program. - - Later license versions may give you additional or different -permissions. However, no additional obligations are imposed on any -author or copyright holder as a result of your choosing to follow a -later version. - - 15. Disclaimer of Warranty. - - THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY -APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT -HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY -OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, -THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM -IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF -ALL NECESSARY SERVICING, REPAIR OR CORRECTION. - - 16. Limitation of Liability. - - IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS -THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY -GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE -USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF -DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD -PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), -EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF -SUCH DAMAGES. - - 17. Interpretation of Sections 15 and 16. - - If the disclaimer of warranty and limitation of liability provided -above cannot be given local legal effect according to their terms, -reviewing courts shall apply local law that most closely approximates -an absolute waiver of all civil liability in connection with the -Program, unless a warranty or assumption of liability accompanies a -copy of the Program in return for a fee. - - END OF TERMS AND CONDITIONS -``` - -## sphinxcontrib-serializinghtml (2.0.0) - -### Licenses -License: `BSD License` - - - `LICENCE.rst`: -``` -License for sphinxcontrib-serializinghtml -========================================= - -Copyright (c) 2007-2019 by the Sphinx team -(see https://github.com/sphinx-doc/sphinx/blob/master/AUTHORS). -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -* Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -``` - ## stack-data (0.6.3) ### Licenses diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 19924a6a..b35e06f5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -143,7 +143,7 @@ uv run pre-commit install The hooks enforce: - **General**: trailing whitespace removal, end-of-file fixup, YAML/TOML/JSON validity, merge conflict marker detection, large file check (500 KB max) -- **Docs**: Markdown link checking for `README.md`, `CONTRIBUTING.md`, and `docs/` via `lychee` +- **Docs**: Fern validation for `docs/` and `fern/`, plus external Markdown/MDX link checking for `README.md`, `CONTRIBUTING.md`, and `docs/` via `lychee` - **Python**: Ruff linting and formatting, ty type checking - **Rust**: FFI header sync for `crates/ffi/nemo_flow.h` through Cargo/build.rs, `cargo fmt` formatting check, `cargo clippy` lints, `cargo deny` auditing - **Go**: `gofmt` formatting, `go vet` static analysis @@ -201,7 +201,7 @@ Before opening a PR, check the following: 2. The relevant reference docs are updated for any public API change. 3. The relevant crate or package README is updated when that surface changed. 4. Embedded documentation snippets, patch docs, and binding-support notes are updated if examples or supported bindings changed. -5. For docs site changes, run `./scripts/build-docs.sh`. +5. For docs site changes, run `./scripts/build-docs.sh`; it regenerates ignored Fern API reference pages before validation. For documentation-heavy changes, prefer small targeted commits so the history shows entry-point changes, reference changes, examples, and maintenance updates @@ -325,9 +325,9 @@ The pre-commit hooks do not currently enforce SPDX headers automatically, but re Before making significant changes, read through the documentation in [`docs/`](docs/), especially: -- [Architecture Overview](docs/about/architecture.md) -- runtime model and data flow -- [Scopes](docs/about/concepts/scopes.md) -- scopes, handles, events, and runtime ownership -- [Middleware](docs/about/concepts/middleware.md) -- execution ordering and middleware behavior -- [API Reference](docs/reference/api/index.md) -- public surfaces across Rust, Python, and Node.js +- [Architecture Overview](docs/about/architecture.mdx) -- runtime model and data flow +- [Scopes](docs/about/concepts/scopes.mdx) -- scopes, handles, events, and runtime ownership +- [Middleware](docs/about/concepts/middleware.mdx) -- execution ordering and middleware behavior +- [API Reference](docs/reference/api/index.mdx) -- public surfaces across Rust, Python, and Node.js The codebase follows a layered architecture: **Core (Rust)** provides the runtime, with bindings through **FFI (C, used by Go through CGo)**, **PyO3 (Python)**, **NAPI (Node.js)**, and **wasm-bindgen (WebAssembly)**. Each binding mirrors the full API surface. diff --git a/RELEASING.md b/RELEASING.md index 69766002..17945c12 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -33,7 +33,6 @@ The release pipeline publishes these package surfaces from a tag push: | crates.io | `nemo-flow`, `nemo-flow-adaptive`, `nemo-flow-ffi`, `nemo-flow-cli` | | PyPI | `nemo-flow` | | npm | `nemo-flow-node`, `nemo-flow-openclaw`, `nemo-flow-wasm` | -| GitHub Pages | The documentation site, including the versioned docs build | Go remains source-first. There is no separate Go package-manager publication step in the repository release workflow. @@ -164,7 +163,7 @@ Review docs and snippets that mention explicit versions, including: - [`README.md`](README.md) - [`CONTRIBUTING.md`](CONTRIBUTING.md) -- [`docs/getting-started/installation.md`](docs/getting-started/installation.md) +- [`fern/versions/dev/pages/getting-started/installation.mdx`](fern/versions/dev/pages/getting-started/installation.mdx) - Any binding README or example that pins a release number Do not commit a static Python package version into `pyproject.toml` just to cut @@ -182,8 +181,8 @@ just test-python just test-go just test-node just test-wasm +./scripts/build-docs.sh check ./scripts/build-docs.sh linkcheck -./scripts/build-docs.sh pages ``` If you want to validate the packaging recipes before pushing a tag, run: @@ -223,21 +222,20 @@ git push upstream 0.1.0-rc.1 ## What CI Does On A Tag Push Pushing a valid tag triggers [`.github/workflows/ci.yaml`](.github/workflows/ci.yaml). -That workflow then calls [`.github/workflows/ci_pipe.yml`](.github/workflows/ci_pipe.yml) -for the shared release documentation and packaging stages. +That workflow then calls the language-specific reusable workflows for validation +and package artifact creation. The release pipeline then: 1. Validates the tag format in the `prepare` job. -2. Skips repo checks and the Rust, Python, Go, Node.js, and WebAssembly test jobs. - Run those checks before creating and pushing the release tag. -3. Builds and uploads the versioned GitHub Pages documentation artifact. -4. Builds publishable package artifacts with the exact tag version: +2. Runs the required repository checks, language test jobs, and Fern documentation + validation. +3. Builds publishable package artifacts with the exact tag version: - `package-node` packs the npm Node.js package. - `package-openclaw` packs the npm OpenClaw plugin package. - `package-python` builds platform wheels. - `package-wasm` packs the npm WebAssembly package. -5. Publishes packages from the top-level workflow after the reusable packaging +4. Publishes packages from the top-level workflow after the reusable packaging jobs complete: - `publish-rust` stamps Cargo workspace versions from the release tag, then runs `cargo publish --package` for `nemo-flow`, `nemo-flow-adaptive`, @@ -250,17 +248,15 @@ The release pipeline then: - Stable tags publish to the npm `latest` dist-tag - Prerelease tags such as `0.1.0-rc.1` publish to the npm `next` dist-tag so they do not become the default upgrade target -6. Deploys the GitHub Pages docs site. The workflow boundary is split intentionally: -- [`.github/workflows/ci_pipe.yml`](.github/workflows/ci_pipe.yml) produces the - publishable package artifacts, runs the docs build, and uploads the GitHub - Pages artifact. +- The language-specific reusable workflows produce publishable package artifacts + after their tests pass. +- [`.github/workflows/ci_docs.yml`](.github/workflows/ci_docs.yml) validates the + Fern documentation. - [`.github/workflows/ci.yaml`](.github/workflows/ci.yaml) owns all crates.io, PyPI, and npm publication decisions and credentials. -- [`.github/workflows/ci.yaml`](.github/workflows/ci.yaml) performs only the - `actions/deploy-pages` step for documentation publication. - This layout also satisfies the official `pypa/gh-action-pypi-publish` guidance that trusted publishing should not run inside reusable workflows. @@ -284,14 +280,10 @@ npm trusted publishing has its own registry-side constraints: - npm trusted publishing currently supports GitHub-hosted runners, not self-hosted runners. -Stable docs versioning is narrower than package publication: - -- Stable released docs are selected from tags that match `X.Y.Z`. -- Prerelease tags such as `0.1.0-rc.1` still run the docs workflow, but they - are not treated as stable released versions by the Sphinx multiversion - configuration. -- Those prerelease docs can still appear in the published version switcher as - prerelease snapshots when they are among the selected recent release tags. +Stable docs versioning is managed through Fern configuration, not the release +tag workflow. Update the Fern version entries when introducing a stable +documentation version; prerelease tags do not publish a separate documentation +artifact from CI. ## Publish The GitHub Release Entry @@ -312,7 +304,7 @@ After the release is live, verify: 2. The `nemo-flow` wheel is visible on PyPI. 3. The `nemo-flow-node`, `nemo-flow-openclaw`, and `nemo-flow-wasm` packages are visible on npm. -4. The GitHub Pages deployment completed successfully. +4. The Fern documentation site shows the expected version and release notes. 5. The GitHub Release page is complete and accurate. ## If Something Fails diff --git a/docs/_static/extra.css b/docs/_static/extra.css deleted file mode 100644 index f30ea65d..00000000 --- a/docs/_static/extra.css +++ /dev/null @@ -1,1336 +0,0 @@ -/* -SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. -SPDX-License-Identifier: Apache-2.0 -*/ - -:root { - --nf-home-accent: #76b900; - --nf-home-accent-dark: #3d5f1a; - --nf-home-border: rgba(61, 95, 26, 0.18); - --nf-home-surface: rgba(118, 185, 0, 0.06); - --nf-scrollbar-thumb: #76b900; - --nf-scrollbar-thumb-hover: #5d9600; - --nf-scrollbar-track: rgba(118, 185, 0, 0.12); - --nf-switcher-surface: var(--pst-color-background); - --nf-switcher-menu-surface: var(--pst-color-background); - --nf-switcher-border: rgba(51, 51, 51, 0.16); - --nf-switcher-border-strong: rgba(51, 51, 51, 0.28); - --nf-switcher-shadow: 0 10px 26px rgba(0, 0, 0, 0.12); - --nf-switcher-label: var(--pst-color-primary); - --nf-switcher-hover-bg: var(--pst-color-surface); - --nf-switcher-current-bg: var(--pst-color-surface); - --nf-switcher-pill-bg: rgba(118, 185, 0, 0.12); - --nf-switcher-pill-text: var(--nv-color-green-2); - --nf-switcher-beta-bg: rgba(0, 72, 49, 0.12); - --nf-switcher-beta-text: var(--pst-color-primary); - --nf-switcher-focus-ring: rgba(118, 185, 0, 0.2); -} - -html[data-theme="dark"] { - --nf-scrollbar-track: rgba(118, 185, 0, 0.2); - --nf-switcher-surface: var(--pst-color-background); - --nf-switcher-menu-surface: var(--pst-color-surface); - --nf-switcher-border: rgba(221, 221, 221, 0.16); - --nf-switcher-border-strong: rgba(221, 221, 221, 0.28); - --nf-switcher-shadow: 0 16px 32px rgba(0, 0, 0, 0.42); - --nf-switcher-label: var(--pst-color-primary); - --nf-switcher-hover-bg: rgba(255, 255, 255, 0.04); - --nf-switcher-current-bg: rgba(255, 255, 255, 0.05); - --nf-switcher-pill-bg: rgba(118, 185, 0, 0.18); - --nf-switcher-pill-text: var(--pst-color-primary); - --nf-switcher-beta-bg: rgba(0, 72, 49, 0.42); - --nf-switcher-beta-text: #d7e7de; - --nf-switcher-focus-ring: rgba(118, 185, 0, 0.28); -} - -* { - scrollbar-color: var(--nf-scrollbar-thumb) var(--nf-scrollbar-track); - scrollbar-width: thin; -} - -*::-webkit-scrollbar { - height: 0.85rem; - width: 0.85rem; -} - -*::-webkit-scrollbar-track { - background: var(--nf-scrollbar-track); -} - -*::-webkit-scrollbar-thumb { - background-color: var(--nf-scrollbar-thumb); - border: 0.18rem solid var(--nf-scrollbar-track); - border-radius: 999px; -} - -*::-webkit-scrollbar-thumb:hover { - background-color: var(--nf-scrollbar-thumb-hover); -} - -.mermaid, -.mermaid > svg { - --surface: #ffffff; - --border: #e0e0e0; - --line: #757575; - --text: #000000; - --edge-label-background: #ffffff; - --white-fill: #ffffff; - --white-stroke: #757575; - --white-text: #000000; - --black-fill: #000000; - --black-stroke: #ffffff; - --black-text: #ffffff; - --grey-lightest-fill: #e0e0e0; - --grey-lightest-stroke: #a7a7a7; - --grey-lightest-text: #000000; - --grey-light-fill: #a7a7a7; - --grey-light-stroke: #757575; - --grey-light-text: #000000; - --grey-fill: #757575; - --grey-stroke: #e0e0e0; - --grey-text: #ffffff; - --grey-dark-fill: #757575; - --grey-dark-stroke: #a7a7a7; - --grey-dark-text: #ffffff; - --grey-darkest-fill: #757575; - --grey-darkest-stroke: #e0e0e0; - --grey-darkest-text: #ffffff; - --grey-hint-fill: #e0e0e0; - --grey-hint-stroke: #a7a7a7; - --grey-hint-text: #000000; - --green-lightest-fill: #cfff40; - --green-lightest-stroke: #76b900; - --green-lightest-text: #000000; - --green-light-fill: #bff230; - --green-light-stroke: #76b900; - --green-light-text: #000000; - --green-fill: #76b900; - --green-stroke: #3f8500; - --green-text: #000000; - --green-dark-fill: #3f8500; - --green-dark-stroke: #265600; - --green-dark-text: #ffffff; - --green-darkest-fill: #265600; - --green-darkest-stroke: #3f8500; - --green-darkest-text: #ffffff; - --purple-lightest-fill: #f9d4ff; - --purple-lightest-stroke: #c359ef; - --purple-lightest-text: #000000; - --purple-light-fill: #c359ef; - --purple-light-stroke: #952fc6; - --purple-light-text: #000000; - --purple-fill: #952fc6; - --purple-stroke: #741d9d; - --purple-text: #ffffff; - --purple-dark-fill: #741d9d; - --purple-dark-stroke: #4d1368; - --purple-dark-text: #ffffff; - --purple-darkest-fill: #4d1368; - --purple-darkest-stroke: #741d9d; - --purple-darkest-text: #ffffff; - --yellow-lightest-fill: #feeeb2; - --yellow-lightest-stroke: #fcde7b; - --yellow-lightest-text: #000000; - --yellow-light-fill: #fcde7b; - --yellow-light-stroke: #f9c500; - --yellow-light-text: #000000; - --yellow-fill: #f9c500; - --yellow-stroke: #ef9100; - --yellow-text: #000000; - --yellow-dark-fill: #ef9100; - --yellow-dark-stroke: #df6500; - --yellow-dark-text: #ffffff; - --yellow-darkest-fill: #df6500; - --yellow-darkest-stroke: #ef9100; - --yellow-darkest-text: #ffffff; - --blue-lightest-fill: #cbf5ff; - --blue-lightest-stroke: #7cd7fe; - --blue-lightest-text: #000000; - --blue-light-fill: #7cd7fe; - --blue-light-stroke: #0074df; - --blue-light-text: #000000; - --blue-fill: #0074df; - --blue-stroke: #0046a4; - --blue-text: #000000; - --blue-dark-fill: #0046a4; - --blue-dark-stroke: #002781; - --blue-dark-text: #ffffff; - --blue-darkest-fill: #002781; - --blue-darkest-stroke: #0046a4; - --blue-darkest-text: #ffffff; - --red-lightest-fill: #ffd7d7; - --red-lightest-stroke: #ff8181; - --red-lightest-text: #000000; - --red-light-fill: #ff8181; - --red-light-stroke: #e52020; - --red-light-text: #000000; - --red-fill: #e52020; - --red-stroke: #961515; - --red-text: #000000; - --red-dark-fill: #961515; - --red-dark-stroke: #650b0b; - --red-dark-text: #ffffff; - --red-darkest-fill: #650b0b; - --red-darkest-stroke: #961515; - --red-darkest-text: #ffffff; - --magenta-lightest-fill: #ffd3f2; - --magenta-lightest-stroke: #fc79ca; - --magenta-lightest-text: #000000; - --magenta-light-fill: #fc79ca; - --magenta-light-stroke: #d2308e; - --magenta-light-text: #000000; - --magenta-fill: #d2308e; - --magenta-stroke: #8c1c55; - --magenta-text: #000000; - --magenta-dark-fill: #8c1c55; - --magenta-dark-stroke: #5d1337; - --magenta-dark-text: #ffffff; - --magenta-darkest-fill: #5d1337; - --magenta-darkest-stroke: #8c1c55; - --magenta-darkest-text: #ffffff; - --teal-lightest-fill: #adfcf8; - --teal-lightest-stroke: #9aefe5; - --teal-lightest-text: #000000; - --teal-light-fill: #9aefe5; - --teal-light-stroke: #1dbba4; - --teal-light-text: #000000; - --teal-fill: #1dbba4; - --teal-stroke: #0d8473; - --teal-text: #000000; - --teal-dark-fill: #0d8473; - --teal-dark-stroke: #04554b; - --teal-dark-text: #ffffff; - --teal-darkest-fill: #04554b; - --teal-darkest-stroke: #0d8473; - --teal-darkest-text: #ffffff; -} - -.mermaid > svg .label text, -.mermaid > svg .label span, -.mermaid > svg .label tspan, -.mermaid > svg .nodeLabel, -.mermaid > svg .nodeLabel p, -.mermaid > svg .cluster-label text, -.mermaid > svg .cluster-label span, -.mermaid > svg .cluster-label tspan, -.mermaid > svg .cluster text, -.mermaid > svg .cluster span, -.mermaid > svg .cluster tspan { - color: var(--text) !important; - fill: var(--text) !important; -} - -.mermaid > svg .edgePath .path, -.mermaid > svg .flowchart-link { - stroke: var(--line) !important; -} - -.mermaid > svg .marker, -.mermaid > svg .marker.cross, -.mermaid > svg .arrowheadPath { - fill: var(--line) !important; - stroke: var(--line) !important; -} - -.mermaid > svg .edgeLabel rect, -.mermaid > svg .edgeLabel p, -.mermaid > svg .labelBkg, -.mermaid > svg .icon-shape, -.mermaid > svg .icon-shape p, -.mermaid > svg .image-shape, -.mermaid > svg .image-shape p { - background-color: var(--edge-label-background) !important; - fill: var(--edge-label-background) !important; -} - -.mermaid > svg .edgeLabel text, -.mermaid > svg .edgeLabel span, -.mermaid > svg .edgeLabel tspan { - color: var(--text) !important; - fill: var(--text) !important; -} - -.mermaid > svg .cluster { - --mermaid-fill: var(--grey-hint-fill); - --mermaid-stroke: var(--grey-hint-stroke); - --mermaid-text: var(--grey-hint-text); -} - -.mermaid > svg .node :is(rect, polygon, circle, ellipse, path), -.mermaid > svg .cluster rect { - stroke-width: 2px !important; -} - -.mermaid > svg .white { - --mermaid-fill: var(--white-fill); - --mermaid-stroke: var(--white-stroke); - --mermaid-text: var(--white-text); -} - -.mermaid > svg .black { - --mermaid-fill: var(--black-fill); - --mermaid-stroke: var(--black-stroke); - --mermaid-text: var(--black-text); -} - -.mermaid > svg .grey-lightest { - --mermaid-fill: var(--grey-lightest-fill); - --mermaid-stroke: var(--grey-lightest-stroke); - --mermaid-text: var(--grey-lightest-text); -} - -.mermaid > svg .grey-light { - --mermaid-fill: var(--grey-light-fill); - --mermaid-stroke: var(--grey-light-stroke); - --mermaid-text: var(--grey-light-text); -} - -.mermaid > svg .grey { - --mermaid-fill: var(--grey-fill); - --mermaid-stroke: var(--grey-stroke); - --mermaid-text: var(--grey-text); -} - -.mermaid > svg .grey-dark { - --mermaid-fill: var(--grey-dark-fill); - --mermaid-stroke: var(--grey-dark-stroke); - --mermaid-text: var(--grey-dark-text); -} - -.mermaid > svg .grey-darkest { - --mermaid-fill: var(--grey-darkest-fill); - --mermaid-stroke: var(--grey-darkest-stroke); - --mermaid-text: var(--grey-darkest-text); -} - -.mermaid > svg .grey-hint { - --mermaid-fill: var(--grey-hint-fill); - --mermaid-stroke: var(--grey-hint-stroke); - --mermaid-text: var(--grey-hint-text); -} - -.mermaid > svg .green-lightest { - --mermaid-fill: var(--green-lightest-fill); - --mermaid-stroke: var(--green-lightest-stroke); - --mermaid-text: var(--green-lightest-text); -} - -.mermaid > svg .green-light { - --mermaid-fill: var(--green-light-fill); - --mermaid-stroke: var(--green-light-stroke); - --mermaid-text: var(--green-light-text); -} - -.mermaid > svg .green { - --mermaid-fill: var(--green-fill); - --mermaid-stroke: var(--green-stroke); - --mermaid-text: var(--green-text); -} - -.mermaid > svg .green-dark { - --mermaid-fill: var(--green-dark-fill); - --mermaid-stroke: var(--green-dark-stroke); - --mermaid-text: var(--green-dark-text); -} - -.mermaid > svg .green-darkest { - --mermaid-fill: var(--green-darkest-fill); - --mermaid-stroke: var(--green-darkest-stroke); - --mermaid-text: var(--green-darkest-text); -} - -.mermaid > svg .purple-lightest { - --mermaid-fill: var(--purple-lightest-fill); - --mermaid-stroke: var(--purple-lightest-stroke); - --mermaid-text: var(--purple-lightest-text); -} - -.mermaid > svg .purple-light { - --mermaid-fill: var(--purple-light-fill); - --mermaid-stroke: var(--purple-light-stroke); - --mermaid-text: var(--purple-light-text); -} - -.mermaid > svg .purple { - --mermaid-fill: var(--purple-fill); - --mermaid-stroke: var(--purple-stroke); - --mermaid-text: var(--purple-text); -} - -.mermaid > svg .purple-dark { - --mermaid-fill: var(--purple-dark-fill); - --mermaid-stroke: var(--purple-dark-stroke); - --mermaid-text: var(--purple-dark-text); -} - -.mermaid > svg .purple-darkest { - --mermaid-fill: var(--purple-darkest-fill); - --mermaid-stroke: var(--purple-darkest-stroke); - --mermaid-text: var(--purple-darkest-text); -} - -.mermaid > svg .yellow-lightest { - --mermaid-fill: var(--yellow-lightest-fill); - --mermaid-stroke: var(--yellow-lightest-stroke); - --mermaid-text: var(--yellow-lightest-text); -} - -.mermaid > svg .yellow-light { - --mermaid-fill: var(--yellow-light-fill); - --mermaid-stroke: var(--yellow-light-stroke); - --mermaid-text: var(--yellow-light-text); -} - -.mermaid > svg .yellow { - --mermaid-fill: var(--yellow-fill); - --mermaid-stroke: var(--yellow-stroke); - --mermaid-text: var(--yellow-text); -} - -.mermaid > svg .yellow-dark { - --mermaid-fill: var(--yellow-dark-fill); - --mermaid-stroke: var(--yellow-dark-stroke); - --mermaid-text: var(--yellow-dark-text); -} - -.mermaid > svg .yellow-darkest { - --mermaid-fill: var(--yellow-darkest-fill); - --mermaid-stroke: var(--yellow-darkest-stroke); - --mermaid-text: var(--yellow-darkest-text); -} - -.mermaid > svg .blue-lightest { - --mermaid-fill: var(--blue-lightest-fill); - --mermaid-stroke: var(--blue-lightest-stroke); - --mermaid-text: var(--blue-lightest-text); -} - -.mermaid > svg .blue-light { - --mermaid-fill: var(--blue-light-fill); - --mermaid-stroke: var(--blue-light-stroke); - --mermaid-text: var(--blue-light-text); -} - -.mermaid > svg .blue { - --mermaid-fill: var(--blue-fill); - --mermaid-stroke: var(--blue-stroke); - --mermaid-text: var(--blue-text); -} - -.mermaid > svg .blue-dark { - --mermaid-fill: var(--blue-dark-fill); - --mermaid-stroke: var(--blue-dark-stroke); - --mermaid-text: var(--blue-dark-text); -} - -.mermaid > svg .blue-darkest { - --mermaid-fill: var(--blue-darkest-fill); - --mermaid-stroke: var(--blue-darkest-stroke); - --mermaid-text: var(--blue-darkest-text); -} - -.mermaid > svg .red-lightest { - --mermaid-fill: var(--red-lightest-fill); - --mermaid-stroke: var(--red-lightest-stroke); - --mermaid-text: var(--red-lightest-text); -} - -.mermaid > svg .red-light { - --mermaid-fill: var(--red-light-fill); - --mermaid-stroke: var(--red-light-stroke); - --mermaid-text: var(--red-light-text); -} - -.mermaid > svg .red { - --mermaid-fill: var(--red-fill); - --mermaid-stroke: var(--red-stroke); - --mermaid-text: var(--red-text); -} - -.mermaid > svg .red-dark { - --mermaid-fill: var(--red-dark-fill); - --mermaid-stroke: var(--red-dark-stroke); - --mermaid-text: var(--red-dark-text); -} - -.mermaid > svg .red-darkest { - --mermaid-fill: var(--red-darkest-fill); - --mermaid-stroke: var(--red-darkest-stroke); - --mermaid-text: var(--red-darkest-text); -} - -.mermaid > svg .magenta-lightest { - --mermaid-fill: var(--magenta-lightest-fill); - --mermaid-stroke: var(--magenta-lightest-stroke); - --mermaid-text: var(--magenta-lightest-text); -} - -.mermaid > svg .magenta-light { - --mermaid-fill: var(--magenta-light-fill); - --mermaid-stroke: var(--magenta-light-stroke); - --mermaid-text: var(--magenta-light-text); -} - -.mermaid > svg .magenta { - --mermaid-fill: var(--magenta-fill); - --mermaid-stroke: var(--magenta-stroke); - --mermaid-text: var(--magenta-text); -} - -.mermaid > svg .magenta-dark { - --mermaid-fill: var(--magenta-dark-fill); - --mermaid-stroke: var(--magenta-dark-stroke); - --mermaid-text: var(--magenta-dark-text); -} - -.mermaid > svg .magenta-darkest { - --mermaid-fill: var(--magenta-darkest-fill); - --mermaid-stroke: var(--magenta-darkest-stroke); - --mermaid-text: var(--magenta-darkest-text); -} - -.mermaid > svg .teal-lightest { - --mermaid-fill: var(--teal-lightest-fill); - --mermaid-stroke: var(--teal-lightest-stroke); - --mermaid-text: var(--teal-lightest-text); -} - -.mermaid > svg .teal-light { - --mermaid-fill: var(--teal-light-fill); - --mermaid-stroke: var(--teal-light-stroke); - --mermaid-text: var(--teal-light-text); -} - -.mermaid > svg .teal { - --mermaid-fill: var(--teal-fill); - --mermaid-stroke: var(--teal-stroke); - --mermaid-text: var(--teal-text); -} - -.mermaid > svg .teal-dark { - --mermaid-fill: var(--teal-dark-fill); - --mermaid-stroke: var(--teal-dark-stroke); - --mermaid-text: var(--teal-dark-text); -} - -.mermaid > svg .teal-darkest { - --mermaid-fill: var(--teal-darkest-fill); - --mermaid-stroke: var(--teal-darkest-stroke); - --mermaid-text: var(--teal-darkest-text); -} - -.mermaid > svg .white-fixed { - --mermaid-fill: #ffffff; - --mermaid-stroke: #757575; - --mermaid-text: #000000; -} - -.mermaid > svg .black-fixed { - --mermaid-fill: #000000; - --mermaid-stroke: #ffffff; - --mermaid-text: #ffffff; -} - -.mermaid > svg .grey-lightest-fixed, -.mermaid > svg .grey-hint-fixed { - --mermaid-fill: #e0e0e0; - --mermaid-stroke: #a7a7a7; - --mermaid-text: #000000; -} - -.mermaid > svg .grey-light-fixed { - --mermaid-fill: #a7a7a7; - --mermaid-stroke: #757575; - --mermaid-text: #000000; -} - -.mermaid > svg .grey-fixed, -.mermaid > svg .grey-dark-fixed, -.mermaid > svg .grey-darkest-fixed { - --mermaid-fill: #757575; - --mermaid-stroke: #e0e0e0; - --mermaid-text: #ffffff; -} - -.mermaid > svg .green-lightest-fixed { - --mermaid-fill: #cfff40; - --mermaid-stroke: #76b900; - --mermaid-text: #000000; -} - -.mermaid > svg .green-light-fixed { - --mermaid-fill: #bff230; - --mermaid-stroke: #76b900; - --mermaid-text: #000000; -} - -.mermaid > svg .green-fixed { - --mermaid-fill: #76b900; - --mermaid-stroke: #3f8500; - --mermaid-text: #000000; -} - -.mermaid > svg .green-dark-fixed { - --mermaid-fill: #3f8500; - --mermaid-stroke: #265600; - --mermaid-text: #ffffff; -} - -.mermaid > svg .green-darkest-fixed { - --mermaid-fill: #265600; - --mermaid-stroke: #3f8500; - --mermaid-text: #ffffff; -} - -.mermaid > svg .purple-lightest-fixed { - --mermaid-fill: #f9d4ff; - --mermaid-stroke: #c359ef; - --mermaid-text: #000000; -} - -.mermaid > svg .purple-light-fixed { - --mermaid-fill: #c359ef; - --mermaid-stroke: #952fc6; - --mermaid-text: #000000; -} - -.mermaid > svg .purple-fixed { - --mermaid-fill: #952fc6; - --mermaid-stroke: #741d9d; - --mermaid-text: #ffffff; -} - -.mermaid > svg .purple-dark-fixed { - --mermaid-fill: #741d9d; - --mermaid-stroke: #4d1368; - --mermaid-text: #ffffff; -} - -.mermaid > svg .purple-darkest-fixed { - --mermaid-fill: #4d1368; - --mermaid-stroke: #741d9d; - --mermaid-text: #ffffff; -} - -.mermaid > svg .yellow-lightest-fixed { - --mermaid-fill: #feeeb2; - --mermaid-stroke: #fcde7b; - --mermaid-text: #000000; -} - -.mermaid > svg .yellow-light-fixed { - --mermaid-fill: #fcde7b; - --mermaid-stroke: #f9c500; - --mermaid-text: #000000; -} - -.mermaid > svg .yellow-fixed { - --mermaid-fill: #f9c500; - --mermaid-stroke: #ef9100; - --mermaid-text: #000000; -} - -.mermaid > svg .yellow-dark-fixed { - --mermaid-fill: #ef9100; - --mermaid-stroke: #df6500; - --mermaid-text: #ffffff; -} - -.mermaid > svg .yellow-darkest-fixed { - --mermaid-fill: #df6500; - --mermaid-stroke: #ef9100; - --mermaid-text: #ffffff; -} - -.mermaid > svg .blue-lightest-fixed { - --mermaid-fill: #cbf5ff; - --mermaid-stroke: #7cd7fe; - --mermaid-text: #000000; -} - -.mermaid > svg .blue-light-fixed { - --mermaid-fill: #7cd7fe; - --mermaid-stroke: #0074df; - --mermaid-text: #000000; -} - -.mermaid > svg .blue-fixed { - --mermaid-fill: #0074df; - --mermaid-stroke: #0046a4; - --mermaid-text: #000000; -} - -.mermaid > svg .blue-dark-fixed { - --mermaid-fill: #0046a4; - --mermaid-stroke: #002781; - --mermaid-text: #ffffff; -} - -.mermaid > svg .blue-darkest-fixed { - --mermaid-fill: #002781; - --mermaid-stroke: #0046a4; - --mermaid-text: #ffffff; -} - -.mermaid > svg .red-lightest-fixed { - --mermaid-fill: #ffd7d7; - --mermaid-stroke: #ff8181; - --mermaid-text: #000000; -} - -.mermaid > svg .red-light-fixed { - --mermaid-fill: #ff8181; - --mermaid-stroke: #e52020; - --mermaid-text: #000000; -} - -.mermaid > svg .red-fixed { - --mermaid-fill: #e52020; - --mermaid-stroke: #961515; - --mermaid-text: #000000; -} - -.mermaid > svg .red-dark-fixed { - --mermaid-fill: #961515; - --mermaid-stroke: #650b0b; - --mermaid-text: #ffffff; -} - -.mermaid > svg .red-darkest-fixed { - --mermaid-fill: #650b0b; - --mermaid-stroke: #961515; - --mermaid-text: #ffffff; -} - -.mermaid > svg .magenta-lightest-fixed { - --mermaid-fill: #ffd3f2; - --mermaid-stroke: #fc79ca; - --mermaid-text: #000000; -} - -.mermaid > svg .magenta-light-fixed { - --mermaid-fill: #fc79ca; - --mermaid-stroke: #d2308e; - --mermaid-text: #000000; -} - -.mermaid > svg .magenta-fixed { - --mermaid-fill: #d2308e; - --mermaid-stroke: #8c1c55; - --mermaid-text: #000000; -} - -.mermaid > svg .magenta-dark-fixed { - --mermaid-fill: #8c1c55; - --mermaid-stroke: #5d1337; - --mermaid-text: #ffffff; -} - -.mermaid > svg .magenta-darkest-fixed { - --mermaid-fill: #5d1337; - --mermaid-stroke: #8c1c55; - --mermaid-text: #ffffff; -} - -.mermaid > svg .teal-lightest-fixed { - --mermaid-fill: #adfcf8; - --mermaid-stroke: #9aefe5; - --mermaid-text: #000000; -} - -.mermaid > svg .teal-light-fixed { - --mermaid-fill: #9aefe5; - --mermaid-stroke: #1dbba4; - --mermaid-text: #000000; -} - -.mermaid > svg .teal-fixed { - --mermaid-fill: #1dbba4; - --mermaid-stroke: #0d8473; - --mermaid-text: #000000; -} - -.mermaid > svg .teal-dark-fixed { - --mermaid-fill: #0d8473; - --mermaid-stroke: #04554b; - --mermaid-text: #ffffff; -} - -.mermaid > svg .teal-darkest-fixed { - --mermaid-fill: #04554b; - --mermaid-stroke: #0d8473; - --mermaid-text: #ffffff; -} - -.mermaid > svg .orange-fixed { - --mermaid-fill: #ef9100; - --mermaid-stroke: #df6500; - --mermaid-text: #000000; -} - -.mermaid > svg .orange-dark-fixed, -.mermaid > svg .orange-darkest-fixed { - --mermaid-fill: #df6500; - --mermaid-stroke: #ef9100; - --mermaid-text: #ffffff; -} - -.mermaid > svg :is( - .white, - .black, - .grey-lightest, - .grey-light, - .grey, - .grey-dark, - .grey-darkest, - .grey-hint, - .green-lightest, - .green-light, - .green, - .green-dark, - .green-darkest, - .purple-lightest, - .purple-light, - .purple, - .purple-dark, - .purple-darkest, - .yellow-lightest, - .yellow-light, - .yellow, - .yellow-dark, - .yellow-darkest, - .blue-lightest, - .blue-light, - .blue, - .blue-dark, - .blue-darkest, - .red-lightest, - .red-light, - .red, - .red-dark, - .red-darkest, - .magenta-lightest, - .magenta-light, - .magenta, - .magenta-dark, - .magenta-darkest, - .teal-lightest, - .teal-light, - .teal, - .teal-dark, - .teal-darkest, - .white-fixed, - .black-fixed, - .grey-lightest-fixed, - .grey-light-fixed, - .grey-fixed, - .grey-dark-fixed, - .grey-darkest-fixed, - .grey-hint-fixed, - .green-lightest-fixed, - .green-light-fixed, - .green-fixed, - .green-dark-fixed, - .green-darkest-fixed, - .purple-lightest-fixed, - .purple-light-fixed, - .purple-fixed, - .purple-dark-fixed, - .purple-darkest-fixed, - .yellow-lightest-fixed, - .yellow-light-fixed, - .yellow-fixed, - .yellow-dark-fixed, - .yellow-darkest-fixed, - .blue-lightest-fixed, - .blue-light-fixed, - .blue-fixed, - .blue-dark-fixed, - .blue-darkest-fixed, - .red-lightest-fixed, - .red-light-fixed, - .red-fixed, - .red-dark-fixed, - .red-darkest-fixed, - .magenta-lightest-fixed, - .magenta-light-fixed, - .magenta-fixed, - .magenta-dark-fixed, - .magenta-darkest-fixed, - .teal-lightest-fixed, - .teal-light-fixed, - .teal-fixed, - .teal-dark-fixed, - .teal-darkest-fixed, - .orange-fixed, - .orange-dark-fixed, - .orange-darkest-fixed - ) - > * { - color: var(--mermaid-text) !important; - fill: var(--mermaid-fill) !important; - stroke: var(--mermaid-stroke) !important; -} - -.mermaid > svg :is( - .white, - .black, - .grey-lightest, - .grey-light, - .grey, - .grey-dark, - .grey-darkest, - .grey-hint, - .green-lightest, - .green-light, - .green, - .green-dark, - .green-darkest, - .purple-lightest, - .purple-light, - .purple, - .purple-dark, - .purple-darkest, - .yellow-lightest, - .yellow-light, - .yellow, - .yellow-dark, - .yellow-darkest, - .blue-lightest, - .blue-light, - .blue, - .blue-dark, - .blue-darkest, - .red-lightest, - .red-light, - .red, - .red-dark, - .red-darkest, - .magenta-lightest, - .magenta-light, - .magenta, - .magenta-dark, - .magenta-darkest, - .teal-lightest, - .teal-light, - .teal, - .teal-dark, - .teal-darkest, - .white-fixed, - .black-fixed, - .grey-lightest-fixed, - .grey-light-fixed, - .grey-fixed, - .grey-dark-fixed, - .grey-darkest-fixed, - .grey-hint-fixed, - .green-lightest-fixed, - .green-light-fixed, - .green-fixed, - .green-dark-fixed, - .green-darkest-fixed, - .purple-lightest-fixed, - .purple-light-fixed, - .purple-fixed, - .purple-dark-fixed, - .purple-darkest-fixed, - .yellow-lightest-fixed, - .yellow-light-fixed, - .yellow-fixed, - .yellow-dark-fixed, - .yellow-darkest-fixed, - .blue-lightest-fixed, - .blue-light-fixed, - .blue-fixed, - .blue-dark-fixed, - .blue-darkest-fixed, - .red-lightest-fixed, - .red-light-fixed, - .red-fixed, - .red-dark-fixed, - .red-darkest-fixed, - .magenta-lightest-fixed, - .magenta-light-fixed, - .magenta-fixed, - .magenta-dark-fixed, - .magenta-darkest-fixed, - .teal-lightest-fixed, - .teal-light-fixed, - .teal-fixed, - .teal-dark-fixed, - .teal-darkest-fixed, - .orange-fixed, - .orange-dark-fixed, - .orange-darkest-fixed - ) - :is(text, tspan, span, p, div, foreignObject) { - color: var(--mermaid-text) !important; - fill: var(--mermaid-text) !important; -} - -.bd-content .mermaid-container { - margin: 1.25rem 0; -} - -.mermaid { - background-color: var(--surface); - border: 1px solid var(--border); - border-radius: 0.75rem; - padding: 1rem; -} - -.mermaid > svg { - background-color: var(--surface) !important; - color: var(--text); - display: block; - height: auto; - margin: 0 auto; - max-width: 100%; -} - -html[data-theme="dark"] .mermaid > svg, -html[data-theme="dark"] pre.mermaid > svg, -html[data-mode="dark"] .mermaid > svg, -html[data-mode="dark"] pre.mermaid > svg { - filter: invert(1) hue-rotate(180deg) !important; -} - -html[data-theme="dark"] .mermaid, -html[data-theme="dark"] .mermaid-container-fullscreen, -html[data-theme="dark"] .mermaid-fullscreen-modal, -html[data-mode="dark"] .mermaid, -html[data-mode="dark"] .mermaid-container-fullscreen, -html[data-mode="dark"] .mermaid-fullscreen-modal { - background-color: #000000 !important; -} - -html[data-theme="dark"] .mermaid-container-fullscreen, -html[data-mode="dark"] .mermaid-container-fullscreen { - box-shadow: 0 10px 40px rgba(0, 0, 0, 0.8) !important; -} - -html[data-theme="dark"] .mermaid-fullscreen-btn, -html[data-theme="dark"] .mermaid-fullscreen-close, -html[data-mode="dark"] .mermaid-fullscreen-btn, -html[data-mode="dark"] .mermaid-fullscreen-close { - background: rgba(50, 50, 50, 0.95) !important; - border: 1px solid rgba(255, 255, 255, 0.3) !important; - color: #e0e0e0 !important; -} - -html[data-theme="dark"] .mermaid-fullscreen-btn:hover, -html[data-theme="dark"] .mermaid-fullscreen-close:hover, -html[data-mode="dark"] .mermaid-fullscreen-btn:hover, -html[data-mode="dark"] .mermaid-fullscreen-close:hover { - background: rgba(60, 60, 60, 1) !important; -} - -.bd-main .bd-content .bd-article-container { - max-width: 54rem; -} - -.bd-content a { - text-underline-offset: 0.14em; -} - -.bd-content a:focus-visible, -.bd-sidebar a:focus-visible, -.navbar-nav a:focus-visible { - outline: 3px solid var(--nf-home-accent); - outline-offset: 2px; -} - -.bd-content table.autosummary { - table-layout: fixed; - width: 100%; -} - -.bd-content table.autosummary td { - vertical-align: top; -} - -.bd-content table.autosummary td:first-child { - width: 42%; -} - -.bd-content table.autosummary td > p { - margin-bottom: 0; -} - -.bd-content table.autosummary td:first-child code, -.bd-content table.autosummary td:first-child .pre { - overflow-wrap: anywhere; - white-space: normal; -} - -.docs-version-switcher { - border: 0; - font-family: var(--pst-font-family-base); - margin-bottom: 1rem; - position: relative; -} - -.docs-version-switcher[open] { - z-index: 40; -} - -.docs-version-switcher__summary { - cursor: pointer; - list-style: none; - user-select: none; -} - -.docs-version-switcher__summary::-webkit-details-marker { - display: none; -} - -.docs-version-switcher__summary:focus-visible { - outline: none; -} - -.docs-version-switcher__eyebrow { - color: var(--nf-switcher-label); - display: block; - font-size: 0.74rem; - font-weight: 700; - letter-spacing: 0.06em; - line-height: 1; - margin-bottom: 0.5rem; - text-transform: uppercase; -} - -.docs-version-switcher__trigger { - align-items: center; - background: var(--nf-switcher-surface); - border: 1px solid var(--nf-switcher-border); - border-radius: var(--bs-border-radius); - box-shadow: 0 1px 2px rgba(0, 0, 0, 0.04); - color: var(--pst-color-text-base); - display: flex; - gap: 0.75rem; - justify-content: space-between; - min-height: 3.1rem; - padding: 0.72rem 0.95rem; - transition: - border-color 0.18s ease, - box-shadow 0.18s ease, - transform 0.18s ease; -} - -.docs-version-switcher__summary:hover .docs-version-switcher__trigger { - border-color: var(--nf-switcher-border-strong); - transform: translateY(-1px); -} - -.docs-version-switcher__summary:focus-visible .docs-version-switcher__trigger { - border-color: var(--nf-switcher-label); - box-shadow: 0 0 0 0.22rem var(--nf-switcher-focus-ring); -} - -.docs-version-switcher__trigger-copy, -.docs-version-switcher__option-copy { - display: flex; - flex-direction: column; - gap: 0.12rem; - min-width: 0; -} - -.docs-version-switcher__trigger-label, -.docs-version-switcher__option-label { - color: var(--pst-color-text-base); - font-size: 1rem; - font-weight: 700; - line-height: 1.25; -} - -.docs-version-switcher__trigger-meta, -.docs-version-switcher__option-meta { - color: var(--pst-color-text-muted); - font-size: 0.76rem; - line-height: 1.2; -} - -.docs-version-switcher__trigger-trailing, -.docs-version-switcher__option-trailing { - align-items: center; - display: flex; - flex-shrink: 0; - gap: 0.6rem; -} - -.docs-version-switcher__pill { - border-radius: var(--bs-border-radius-pill, 999px); - font-size: 0.7rem; - font-weight: 700; - letter-spacing: 0.02em; - line-height: 1; - padding: 0.36rem 0.58rem; - text-transform: uppercase; - white-space: nowrap; -} - -.docs-version-switcher__pill.is-stable { - background: var(--nf-switcher-pill-bg); - color: var(--nf-switcher-pill-text); -} - -.docs-version-switcher__pill.is-beta { - background: var(--nf-switcher-beta-bg); - color: var(--nf-switcher-beta-text); -} - -.docs-version-switcher__chevron, -.docs-version-switcher__check { - color: var(--nf-switcher-label); - display: inline-flex; - height: 1rem; - width: 1rem; -} - -.docs-version-switcher__chevron svg, -.docs-version-switcher__check svg { - fill: currentColor; - height: 100%; - width: 100%; -} - -.docs-version-switcher__chevron { - transition: transform 0.18s ease; -} - -.docs-version-switcher[open] .docs-version-switcher__chevron { - transform: rotate(180deg); -} - -.docs-version-switcher__menu-wrap { - left: 0; - margin-top: 0.4rem; - position: absolute; - right: 0; - top: 100%; -} - -.docs-version-switcher__menu { - background: var(--nf-switcher-menu-surface); - border: 1px solid var(--nf-switcher-border); - border-radius: var(--bs-border-radius); - box-shadow: var(--nf-switcher-shadow); - list-style: none; - margin: 0; - max-height: min(24rem, calc(100vh - 10rem)); - overflow-y: auto; - padding: 0.35rem; -} - -.docs-version-switcher__option + .docs-version-switcher__option { - margin-top: 0.08rem; -} - -.docs-version-switcher__option-link { - align-items: center; - border: 1px solid transparent; - border-radius: var(--bs-border-radius); - color: inherit; - display: flex; - gap: 0.75rem; - justify-content: space-between; - min-height: 2.85rem; - padding: 0.64rem 0.75rem; - text-decoration: none; - transition: background-color 0.18s ease, color 0.18s ease; -} - -.docs-version-switcher__option-link:hover { - background: var(--nf-switcher-hover-bg); -} - -.docs-version-switcher__option-link:focus-visible { - outline: none; - background: var(--nf-switcher-hover-bg); - box-shadow: 0 0 0 0.2rem var(--nf-switcher-focus-ring); -} - -.docs-version-switcher__option-link.is-current { - background: var(--nf-switcher-current-bg); - border-color: var(--nv-color-green); -} - -.nf-home { - border-left: 0.35rem solid var(--nf-home-accent); - margin: 0 0 2rem; - padding: 0.25rem 0 0.25rem 1.1rem; -} - -.nf-kicker { - color: var(--nf-home-accent-dark); - font-size: 0.9rem; - font-weight: 700; - letter-spacing: 0.04em; - margin: 0 0 0.5rem; - text-transform: uppercase; -} - -.nf-lead { - font-size: 1.3rem; - line-height: 1.6; - margin: 0 0 0.85rem; - max-width: 44rem; -} - -.nf-intro { - color: var(--pst-color-text-muted); - margin: 0; - max-width: 42rem; -} - -.bd-content h1 { - letter-spacing: -0.02em; - margin-bottom: 1rem; -} - -.bd-content h2 { - border-top: 1px solid var(--nf-home-border); - margin-top: 2.5rem; - padding-top: 1.5rem; -} - -.bd-content ul li, -.bd-content ol li { - margin-bottom: 0.45rem; -} - -.bd-content li > p { - margin-bottom: 0.35rem; -} - -body:has(dialog[open]) .bd-container { - filter: blur(5px) !important; -} - -#pst-search-dialog[open]::backdrop { - background-color: transparent !important; -} - -@media (max-width: 768px) { - .docs-version-switcher__trigger, - .docs-version-switcher__option-link { - align-items: flex-start; - } - - .docs-version-switcher__trigger-trailing, - .docs-version-switcher__option-trailing { - gap: 0.45rem; - } - - .docs-version-switcher__menu { - max-height: min(20rem, calc(100vh - 8rem)); - } - - .nf-home { - padding-left: 0.9rem; - } - - .nf-lead { - font-size: 1.15rem; - } -} diff --git a/docs/_static/version-switcher.js b/docs/_static/version-switcher.js deleted file mode 100644 index 09ebf88b..00000000 --- a/docs/_static/version-switcher.js +++ /dev/null @@ -1,51 +0,0 @@ -/* -SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. -SPDX-License-Identifier: Apache-2.0 -*/ - -(() => { - const selector = ".docs-version-switcher"; - - const closeOthers = (active) => { - document.querySelectorAll(`${selector}[open]`).forEach((node) => { - if (node !== active) { - node.removeAttribute("open"); - } - }); - }; - - document.addEventListener("toggle", (event) => { - const node = event.target; - if (!(node instanceof HTMLElement) || !node.matches(selector) || !node.open) { - return; - } - closeOthers(node); - }); - - document.addEventListener("click", (event) => { - const target = event.target; - if (!(target instanceof Node)) { - return; - } - - document.querySelectorAll(`${selector}[open]`).forEach((node) => { - if (!node.contains(target)) { - node.removeAttribute("open"); - } - }); - }); - - document.addEventListener("keydown", (event) => { - if (event.key !== "Escape") { - return; - } - - const openSwitcher = document.querySelector(`${selector}[open]`); - if (!(openSwitcher instanceof HTMLDetailsElement)) { - return; - } - - openSwitcher.removeAttribute("open"); - openSwitcher.querySelector("summary")?.focus(); - }); -})(); diff --git a/docs/_templates/version-switcher.html b/docs/_templates/version-switcher.html deleted file mode 100644 index d6cf56af..00000000 --- a/docs/_templates/version-switcher.html +++ /dev/null @@ -1,125 +0,0 @@ -{# -SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. -SPDX-License-Identifier: Apache-2.0 -#} -{% macro version_switcher_item(label, meta, status, status_class, url, selected=false) -%} -
  • - {% if selected %} - - - {{ label }} - {% if meta %} - {{ meta }} - {% endif %} - - - {% if status %} - {{ status }} - {% endif %} - - - - {% else %} - - - {{ label }} - {% if meta %} - {{ meta }} - {% endif %} - - - {% if status %} - {{ status }} - {% endif %} - - - {% endif %} -
    • -{%- endmacro %} -{% if versions %} -{% set ordered_releases = versions.releases|stable_release_order %} -{% set latest_stable_release = find_latest_stable_release(ordered_releases) %} -{% set recent_release_versions = ordered_releases[1:5] if latest_stable_release else ordered_releases[:5] %} -{% set main_development_version = find_version_by_name(versions.in_development, "main") %} -{% if latest_stable_release and current_version.name == latest_stable_release.name %} -{% set current_label = display_release_label(latest_stable_release.name) %} -{% set current_meta = "Latest stable" %} -{% set current_status = "Stable" %} -{% set current_status_class = "is-stable" %} -{% elif main_development_version and current_version.name == main_development_version.name %} -{% set current_label = "main" %} -{% set current_meta = "Development" %} -{% set current_status = "Prerelease" %} -{% set current_status_class = "is-beta" %} -{% elif is_prerelease_name(current_version.name) %} -{% set current_label = display_release_label(current_version.name) %} -{% set current_meta = "Prerelease snapshot" %} -{% set current_status = "Prerelease" %} -{% set current_status_class = "is-beta" %} -{% else %} -{% set current_label = display_release_label(current_version.name) %} -{% set current_meta = "Release snapshot" %} -{% set current_status = "Stable" %} -{% set current_status_class = "is-stable" %} -{% endif %} -
    - - Version - - - {{ current_label }} - {{ current_meta }} - - - {{ current_status }} - - - - -
    -
      - {% if latest_stable_release %} - {{ version_switcher_item( - display_release_label(latest_stable_release.name), - "Latest stable", - "Stable", - "is-stable", - display_release_url(latest_stable_release.url, latest_stable_release.name), - current_version.name == latest_stable_release.name, - ) }} - {% endif %} - {% if main_development_version %} - {{ version_switcher_item( - "main", - "Development", - "Prerelease", - "is-beta", - main_development_version.url, - current_version.name == main_development_version.name, - ) }} - {% endif %} - {% for item in recent_release_versions %} - {% set item_meta = "Prerelease snapshot" if is_prerelease_name(item.name) else "Release snapshot" %} - {% set item_status = "Prerelease" if is_prerelease_name(item.name) else "Stable" %} - {% set item_status_class = "is-beta" if is_prerelease_name(item.name) else "is-stable" %} - {{ version_switcher_item( - display_release_label(item.name), - item_meta, - item_status, - item_status_class, - display_release_url(item.url, item.name), - current_version.name == item.name, - ) }} - {% endfor %} -
    -
    -
    -{% endif %} diff --git a/docs/about/architecture.md b/docs/about/architecture.mdx similarity index 91% rename from docs/about/architecture.md rename to docs/about/architecture.mdx index ff2e1f17..2f0da7f7 100644 --- a/docs/about/architecture.md +++ b/docs/about/architecture.mdx @@ -1,9 +1,10 @@ - - -# Architecture +--- +title: "Architecture" +description: "" +position: 2 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} This page explains how NeMo Flow connects scopes, middleware, plugins, events, subscribers, and exporters. @@ -12,7 +13,7 @@ subscribers, and exporters. This diagram connects the runtime pieces to the layers they inhabit. -```{mermaid} +```mermaid flowchart TB subgraph AppLayer[Framework Integrations and Application Code] App[Application Code] @@ -159,7 +160,7 @@ Two distinctions matter: - Intercepts affect the real execution path - Sanitize guardrails affect the emitted observability payload -For the expanded request-to-response runtime path, including streaming and subscriber handoff, see [Middleware](concepts/middleware.md#detailed-execution-flow). +For the expanded request-to-response runtime path, including streaming and subscriber handoff, see [Middleware](/about-nemo-flow/concepts/middleware#detailed-execution-flow). ## Runtime Layers @@ -181,8 +182,8 @@ NeMo Flow is designed so that application developers, framework integrators, plu The following concepts are related to this architecture: -- [Scopes](concepts/scopes.md) -- [Middleware](concepts/middleware.md) -- [Events](concepts/events.md) -- [Subscribers](concepts/subscribers.md) -- [Plugins](concepts/plugins.md) +- [Scopes](/about-nemo-flow/concepts/scopes) +- [Middleware](/about-nemo-flow/concepts/middleware) +- [Events](/about-nemo-flow/concepts/events) +- [Subscribers](/about-nemo-flow/concepts/subscribers) +- [Plugins](/about-nemo-flow/concepts/plugins) diff --git a/docs/about/concepts/events.md b/docs/about/concepts/events.mdx similarity index 93% rename from docs/about/concepts/events.md rename to docs/about/concepts/events.mdx index c50cf5c5..a10984c8 100644 --- a/docs/about/concepts/events.md +++ b/docs/about/concepts/events.mdx @@ -1,9 +1,10 @@ - - -# Events +--- +title: "Events" +description: "" +position: 4 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} This page explains the lifecycle events emitted by scopes, tools, LLM calls, middleware, and subscribers. diff --git a/docs/about/concepts/framework-integrations.md b/docs/about/concepts/framework-integrations.mdx similarity index 93% rename from docs/about/concepts/framework-integrations.md rename to docs/about/concepts/framework-integrations.mdx index 371e65c6..3ca1b67f 100644 --- a/docs/about/concepts/framework-integrations.md +++ b/docs/about/concepts/framework-integrations.mdx @@ -1,9 +1,10 @@ - - -# Framework Integrations +--- +title: "Framework Integrations" +description: "" +position: 6 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} This page explains how framework integrations should attach existing application work to NeMo Flow runtime semantics. @@ -149,5 +150,5 @@ Use these practices when applying the concept in application or integration code without managed callback wrapping. - Use mark events to fill visibility gaps rather than to model full execution spans. -- Keep binding-level API details in the [API Reference](../../reference/api/index.md) and - deeper integration patterns in [Integrate into Frameworks](../../integrate-frameworks/about.md). +- Keep binding-level API details in the [API Reference](/reference/api) and + deeper integration patterns in [Integrate into Frameworks](/integrate-into-frameworks/about). diff --git a/docs/about/concepts/index.md b/docs/about/concepts/index.md deleted file mode 100644 index 3378eb0b..00000000 --- a/docs/about/concepts/index.md +++ /dev/null @@ -1,67 +0,0 @@ - - -# Concepts - -Use these pages to understand the NeMo Flow runtime model before applying it in a use-case workflow. - -::::{grid} 1 1 2 2 -:gutter: 3 - -:::{grid-item-card} {octicon}`stack;1.2em` Scopes -:link: scopes -:link-type: doc - -Ownership boundaries for agent runs, requests, workflows, tools, LLM calls, and nested runtime work. -::: - -:::{grid-item-card} {octicon}`workflow;1.2em` Middleware -:link: middleware -:link-type: doc - -Guardrails and intercepts that sanitize, transform, block, or wrap tool and LLM execution. -::: - -:::{grid-item-card} {octicon}`package;1.2em` Plugins -:link: plugins -:link-type: doc - -Configuration-driven bundles that install reusable middleware, subscribers, and adaptive behavior. -::: - -:::{grid-item-card} {octicon}`pulse;1.2em` Events -:link: events -:link-type: doc - -Canonical lifecycle records for scopes, tool calls, LLM calls, marks, subscribers, and exporters. -::: - -:::{grid-item-card} {octicon}`broadcast;1.2em` Subscribers -:link: subscribers -:link-type: doc - -Consumers for lifecycle events, including logs, traces, trajectories, analytics, and diagnostics. -::: - -:::{grid-item-card} {octicon}`plug;1.2em` Framework Integrations -:link: framework-integrations -:link-type: doc - -Integration patterns for frameworks that own invocation boundaries, scheduling, retries, or provider payloads. -::: - -:::: - -```{toctree} -:hidden: -:maxdepth: 1 - -scopes -middleware -plugins -events -subscribers -framework-integrations -``` diff --git a/docs/about/concepts/index.mdx b/docs/about/concepts/index.mdx new file mode 100644 index 00000000..46ceacc7 --- /dev/null +++ b/docs/about/concepts/index.mdx @@ -0,0 +1,43 @@ +--- +title: "Concepts" +description: "" +position: 4 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} + +Use these pages to understand the NeMo Flow runtime model before applying it in a use-case workflow. + + + + + +Ownership boundaries for agent runs, requests, workflows, tools, LLM calls, and nested runtime work. + + + + +Guardrails and intercepts that sanitize, transform, block, or wrap tool and LLM execution. + + + + +Configuration-driven bundles that install reusable middleware, subscribers, and adaptive behavior. + + + + +Canonical lifecycle records for scopes, tool calls, LLM calls, marks, subscribers, and exporters. + + + + +Consumers for lifecycle events, including logs, traces, trajectories, analytics, and diagnostics. + + + + +Integration patterns for frameworks that own invocation boundaries, scheduling, retries, or provider payloads. + + + diff --git a/docs/about/concepts/middleware.md b/docs/about/concepts/middleware.mdx similarity index 97% rename from docs/about/concepts/middleware.md rename to docs/about/concepts/middleware.mdx index 99debd53..75c79087 100644 --- a/docs/about/concepts/middleware.md +++ b/docs/about/concepts/middleware.mdx @@ -1,9 +1,10 @@ - - -# Middleware +--- +title: "Middleware" +description: "" +position: 2 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} This page explains the runtime behavior that runs around managed tool and LLM calls. @@ -110,7 +111,7 @@ arguments passed to the callback or the real value returned to the caller. For managed execution, NeMo Flow applies middleware in this order: -```{mermaid} +```mermaid sequenceDiagram autonumber actor Caller as Application / Framework @@ -168,7 +169,7 @@ diagram below expands the same flow to show where guardrail rejections, event subscribers, execution-intercept chaining, and streaming collection/finalization fit into the runtime path. -```{mermaid} +```mermaid flowchart TB Request([Request]) diff --git a/docs/about/concepts/plugins.md b/docs/about/concepts/plugins.mdx similarity index 90% rename from docs/about/concepts/plugins.md rename to docs/about/concepts/plugins.mdx index 7eb0e6e0..7af595f9 100644 --- a/docs/about/concepts/plugins.md +++ b/docs/about/concepts/plugins.mdx @@ -1,9 +1,10 @@ - - -# Plugins +--- +title: "Plugins" +description: "" +position: 3 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} This page explains how plugins package reusable runtime behavior behind configuration. @@ -56,7 +57,7 @@ behavior. Reporting provides structured diagnostics about what activated successfully and what did not. -```{mermaid} +```mermaid flowchart TB subgraph Config[Plugin Configuration] Document[Plugin Config
    version + components + policy] @@ -145,9 +146,9 @@ through the same component lifecycle as other plugins: - Inspect the activation result if needed Detailed adaptive configuration belongs in -[Adaptive Configuration](../../plugins/adaptive/configuration.md), -[Adaptive Cache Governor (ACG)](../../plugins/adaptive/acg.md), and -[Adaptive Hints](../../plugins/adaptive/adaptive-hints.md). +[Adaptive Configuration](/adaptive-plugin/configuration), +[Adaptive Cache Governor (ACG)](/adaptive-plugin/acg), and +[Adaptive Hints](/adaptive-plugin/adaptive-hints). ### Observability @@ -158,10 +159,10 @@ disabled unless its section sets `enabled: true`, and subscriber names are inferred from the plugin namespace instead of exposed in public config. Detailed observability plugin configuration belongs in -[Observability Configuration](../../plugins/observability/configuration.md). +[Observability Configuration](/observability-plugin/configuration). For the CLI gateway's `plugins.toml` discovery, precedence, merge, and editing -rules, see [Plugin Configuration Files](../../build-plugins/plugin-configuration-files.md). +rules, see [Plugin Configuration Files](/build-plugins/plugin-configuration-files). ## Practical Guidance diff --git a/docs/about/concepts/scopes.md b/docs/about/concepts/scopes.mdx similarity index 95% rename from docs/about/concepts/scopes.md rename to docs/about/concepts/scopes.mdx index e76c24d7..246f39c6 100644 --- a/docs/about/concepts/scopes.md +++ b/docs/about/concepts/scopes.mdx @@ -1,9 +1,10 @@ - - -# Scopes +--- +title: "Scopes" +description: "" +position: 1 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} This page explains how scope stacks establish ownership, parentage, cleanup, and isolation. diff --git a/docs/about/concepts/subscribers.md b/docs/about/concepts/subscribers.mdx similarity index 89% rename from docs/about/concepts/subscribers.md rename to docs/about/concepts/subscribers.mdx index 71780d81..76e33225 100644 --- a/docs/about/concepts/subscribers.md +++ b/docs/about/concepts/subscribers.mdx @@ -1,9 +1,10 @@ - - -# Subscribers +--- +title: "Subscribers" +description: "" +position: 5 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} This page explains how subscribers consume lifecycle events without changing runtime execution. @@ -83,13 +84,13 @@ of the canonical event stream. ### Agent Trajectory Interchange Format (ATIF) Exporter -The [Agent Trajectory Interchange Format (ATIF) exporter](../../plugins/observability/atif.md) +The [Agent Trajectory Interchange Format (ATIF) exporter](/observability-plugin/atif) collects lifecycle events and emits trajectory artifacts for offline analysis, replay, or debugging. ### Agent Trajectory Observability Format (ATOF) JSONL Exporter -The [Agent Trajectory Observability Format (ATOF) JSONL exporter](../../plugins/observability/atof.md) +The [Agent Trajectory Observability Format (ATOF) JSONL exporter](/observability-plugin/atof) writes the canonical event stream to a native filesystem path as one raw ATOF event per line. @@ -104,9 +105,9 @@ The OpenInference subscriber maps runtime events into OTLP traces using OpenInference semantics for model-centric observability. Detailed setup, configuration, and API shape for these subscribers belongs in -[Observability](../../plugins/observability/about.md). +[Observability](/observability-plugin/about). For configuration-driven setup, use the built-in -[`observability` plugin](../../plugins/observability/configuration.md) +[`observability` plugin](/observability-plugin/configuration) to install ATOF, ATIF, OpenTelemetry, and OpenInference subscribers from one plugin component. diff --git a/docs/about/ecosystem.md b/docs/about/ecosystem.mdx similarity index 91% rename from docs/about/ecosystem.md rename to docs/about/ecosystem.mdx index bbaea3f5..db0a8ef3 100644 --- a/docs/about/ecosystem.md +++ b/docs/about/ecosystem.mdx @@ -1,9 +1,10 @@ - - -# Ecosystem +--- +title: "Ecosystem" +description: "" +position: 3 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} NeMo Flow is the agent execution runtime layer in the NVIDIA NeMo ecosystem. It does not replace an agent framework, model provider, guardrail authoring system, @@ -20,7 +21,7 @@ Use this page to understand where NeMo Flow fits: ## How NeMo Flow Fits In The NVIDIA NeMo Ecosystem -The NVIDIA NeMo ecosystem spans model development, agent construction, +The NVIDIA NeMo ecosystem spans model dev, agent construction, guardrailing, inference, optimization, and runtime operations. NeMo Flow has a narrower responsibility: it is the portable execution substrate that agent systems can call when actual work crosses a scope, tool, or model boundary. @@ -38,7 +39,7 @@ agent products. A framework asks, "What should the agent do next?" NeMo Flow asks, "When the agent does work, which scope owns it, which middleware applies, what events are emitted, and which subscribers can consume the result?" -```{mermaid} +```mermaid flowchart TB User[User / Application] Framework[Agent Framework or Harness] @@ -105,8 +106,8 @@ Use these links to continue into adjacent concepts and workflows. - [NVIDIA NeMo documentation](https://docs.nvidia.com/nemo/index.html) - [NVIDIA NeMo Agent Toolkit documentation](https://docs.nvidia.com/nemo/agent-toolkit/latest/) - [NVIDIA NeMo Guardrails documentation](https://docs.nvidia.com/nemo-guardrails/index.html) -- [Integrate into Frameworks](../integrate-frameworks/about.md) -- [Adding Framework Scopes](../integrate-frameworks/adding-scopes.md) -- [Wrapping Tool Calls](../integrate-frameworks/wrap-tool-calls.md) -- [Wrapping LLM Calls](../integrate-frameworks/wrap-llm-calls.md) -- [Plugin Model](../build-plugins/basic-guide.md) +- [Integrate into Frameworks](/integrate-into-frameworks/about) +- [Adding Framework Scopes](/integrate-into-frameworks/adding-scopes) +- [Wrapping Tool Calls](/integrate-into-frameworks/wrap-tool-calls) +- [Wrapping LLM Calls](/integrate-into-frameworks/wrap-llm-calls) +- [Plugin Model](/build-plugins/basic-guide) diff --git a/docs/about/overview.mdx b/docs/about/overview.mdx new file mode 100644 index 00000000..68f15cf7 --- /dev/null +++ b/docs/about/overview.mdx @@ -0,0 +1,127 @@ +--- +title: "Overview" +description: "" +position: 1 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} + +NeMo Flow is a portable execution runtime for agent systems that already have a +framework, model provider, policy layer, or observability backend. It gives those +systems one consistent way to describe what is happening when an agent crosses a +request, tool, or LLM boundary. + +That layer is useful because agent applications rarely live inside one clean +abstraction. A production stack might combine NeMo Agent Toolkit, LangChain, +LangGraph, provider SDKs, custom harness code, NeMo Guardrails, tracing systems, +and evaluation pipelines. NeMo Flow sits underneath those choices as the shared +runtime contract for scopes, middleware, plugins, lifecycle events, adaptive +behavior, and observability. Under the NeMo Flow scope stack and middleware, the scoped execution path is referred to as work. + +The result is a framework-neutral substrate for agent execution. Applications +keep their orchestration model, providers keep their native clients, and +middleware authors get one place to package policy, interception, telemetry, and +adaptive behavior across Rust, Python, and Node.js. + +## Benefits + +NeMo Flow is designed for teams that need agent runtime behavior to stay +consistent as applications grow across frameworks, languages, and deployment +targets. + +- **Instrument once at the execution boundary**: Managed tool and LLM helpers + attach work to the active scope, emit lifecycle events, and run the same + middleware pipeline without scattering custom wrappers through every call site. +- **Keep concurrent agents isolated**: Hierarchical scopes preserve parent-child + event relationships, expose request-local middleware and subscribers, and + clean up scope-owned registrations when work finishes. +- **Turn policy into reusable runtime components**: Guardrails and intercepts can + block work, sanitize observability payloads, transform requests, or wrap + execution. Plugins package that behavior so applications and framework + integrations can install it from configuration. +- **Export one event stream to many backends**: Subscribers consume the canonical + lifecycle stream in-process or translate it to Agent Trajectory Interchange + Format (ATIF) trajectories, OpenTelemetry traces, and OpenInference-compatible + traces for debugging, evaluation, and production observability. +- **Adopt without replacing the stack**: NeMo Flow can sit below NeMo ecosystem + components, third-party agent frameworks, provider adapters, or direct + application code, so teams can add shared runtime semantics without a + framework migration. +- **Share semantics across primary bindings**: The Rust core, Python wrapper, + and Node.js binding expose the same execution model, which helps framework + authors, plugin authors, and application teams reason about behavior + consistently. + +## What Should I Read First? + +Use the reading path that matches your task: + +| Task | Start With | +|---|---| +| Run a minimal example | [Quick Start](/getting-started/quick-start) | +| Install packages | [Installation](/getting-started/installation) | +| Develop from source | [Development Setup](/contribute/development-setup) | +| Understand the runtime model | [Concepts](/about-nemo-flow/concepts) | +| Instrument an application | [Instrument Applications](/instrument-applications/about) | +| Use a maintained integration | [Supported Integrations](/supported-integrations/about) | +| Integrate a framework | [Integrate into Frameworks](/integrate-into-frameworks/about) | +| Observe a local coding-agent CLI | [NeMo Flow CLI](/nemo-flow-cli/about) | +| Package reusable behavior | [Build Plugins](/build-plugins/about) | +| Export traces or trajectories | [Observability](/observability-plugin/about) | +| Configure adaptive behavior | [Adaptive](/adaptive-plugin/about) | +| Look up symbols | [APIs](/reference/api) | + +## Conceptual Diagram + +The diagram below shows how applications, runtime components, and exporters +relate to each other. Scopes define where work belongs, middleware registries +define what runs around that work, and subscribers consume the lifecycle events +that the core emits. + +```mermaid +flowchart TB + Plugin[Plugin] + App[Application Code / Agent Harness / Agent Framework] + Framework[Framework Integration] + + subgraph Runtime[Runtime] + PluginSystem[Plugin System] + Bindings[Language Bindings] + Core[Rust Core Runtime] + Events[Lifecycle Events] + + subgraph RuntimeState[Runtime State] + Registry[Middleware Registries
    what runs around work] + Scope[Scope Stack
    where work belongs] + end + + Subs[Subscribers / Exporters] + + PluginSystem --->|installs| Registry + PluginSystem ----->|installs| Subs + Bindings --> Core + Core -->|emits| Events -->|consumed by| Subs + Core -->|updates| Scope + Core -->|resolves| Registry + end + + App -->|registers| Plugin + App -->|uses| Framework + App -->|configures/initializes| PluginSystem + App -->|uses| Bindings + Framework -->|calls| Bindings + Plugin -->|registers with| PluginSystem + + class Runtime grey-lightest; + class RuntimeState grey-lightest; + class App purple-lightest; + class Framework yellow-lightest; + class Plugin blue-lightest; + class Bindings green-lightest; + class PluginSystem green-light; + class Core green-light; + class Scope green-light; + class Registry green-light; + class Events green-light; + class Subs green-light; +``` diff --git a/docs/about/release-notes/highlights.md b/docs/about/release-notes/highlights.mdx similarity index 60% rename from docs/about/release-notes/highlights.md rename to docs/about/release-notes/highlights.mdx index 119f4f8c..6716680b 100644 --- a/docs/about/release-notes/highlights.md +++ b/docs/about/release-notes/highlights.mdx @@ -1,9 +1,10 @@ - - -# Highlights +--- +title: "Highlights" +description: "" +position: 1 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} This page summarizes the notable capabilities in the current release documentation set. diff --git a/docs/about/release-notes/index.md b/docs/about/release-notes/index.mdx similarity index 58% rename from docs/about/release-notes/index.md rename to docs/about/release-notes/index.mdx index 34698368..5e324436 100644 --- a/docs/about/release-notes/index.md +++ b/docs/about/release-notes/index.mdx @@ -1,20 +1,13 @@ - - -# Release Notes +--- +title: "Release Notes" +description: "" +position: 5 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} This page summarizes the current documentation-visible release state. GitHub Releases remain the source of truth for complete release history and tag-specific notes. -```{toctree} -:maxdepth: 1 - -highlights -known-issues -related-topics -``` - ## Current Release Use this page as the release-notes entry point. Use the child pages for current highlights, known issues, and related release resources. diff --git a/docs/about/release-notes/known-issues.md b/docs/about/release-notes/known-issues.mdx similarity index 77% rename from docs/about/release-notes/known-issues.md rename to docs/about/release-notes/known-issues.mdx index 0ccc6c8b..10d8a5d2 100644 --- a/docs/about/release-notes/known-issues.md +++ b/docs/about/release-notes/known-issues.mdx @@ -1,9 +1,10 @@ - - -# Known Issues +--- +title: "Known Issues" +description: "" +position: 2 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} This page lists current limitations and support notes for the release documentation set. @@ -17,7 +18,6 @@ These notes apply to the NeMo Flow 0.3 Release. ### Fixed issues from NeMo Flow 0.2: - ### Fixed issues from NeMo Flow 0.1: - Enabled TLS support for OTLP HTTP export. - Preserved Go scope stacks across OS threads. diff --git a/docs/about/release-notes/related-topics.md b/docs/about/release-notes/related-topics.md deleted file mode 100644 index b1316688..00000000 --- a/docs/about/release-notes/related-topics.md +++ /dev/null @@ -1,11 +0,0 @@ - - -# Related Topics - -Use these links to continue into adjacent concepts and workflows. - -- [Ecosystem](../ecosystem.md) -- [Support and FAQs](../../resources/support-and-faqs.md) diff --git a/docs/about/release-notes/related-topics.mdx b/docs/about/release-notes/related-topics.mdx new file mode 100644 index 00000000..847cb7f2 --- /dev/null +++ b/docs/about/release-notes/related-topics.mdx @@ -0,0 +1,12 @@ +--- +title: "Related Topics" +description: "" +position: 3 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} + +Use these links to continue into adjacent concepts and workflows. + +- [Ecosystem](/about-nemo-flow/ecosystem) +- [Support and FAQs](/resources/support-and-faqs) diff --git a/docs/build-plugins/about.md b/docs/build-plugins/about.mdx similarity index 55% rename from docs/build-plugins/about.md rename to docs/build-plugins/about.mdx index bd66cfa8..57198fd4 100644 --- a/docs/build-plugins/about.md +++ b/docs/build-plugins/about.mdx @@ -1,9 +1,10 @@ - - -# About +--- +title: "About" +description: "" +position: 1 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this section when you want to package reusable NeMo Flow behavior as a plugin that can be activated from configuration. @@ -31,13 +32,13 @@ If the behavior applies to only one request or tenant, consider scope-local midd Use these guide links to move from the overview into task-specific instructions. -- [Define a Plugin](basic-guide.md) explains plugin kinds, shape, runtime ownership, and the activation lifecycle. -- [Validate Plugin Configuration](validate-configuration.md) covers JSON-compatible config, validation rules, and structured diagnostics. -- [Plugin Configuration Files](plugin-configuration-files.md) documents `plugins.toml` file discovery, precedence, merge behavior, and editor controls for the CLI gateway. -- [Register Plugin Behavior](register-behavior.md) shows how to initialize config and install subscribers or middleware through `PluginContext`. -- [Design Plugin Configuration](advanced-configuration.md) covers validation rules, advanced configuration patterns, rollout controls, and `PluginContext` usage. -- [NeMo Guardrails Example Plugin](nemoguardrails.md) shows an external Python plugin that applies NeMo Guardrails checks around NeMo Flow LLM and tool calls. -- [Code Examples](code-examples.md) provides patterns for dynamic header injection, subscriber-oriented export, multi-surface bundles, and framework-facing plugins. +- [Define a Plugin](/build-plugins/basic-guide) explains plugin kinds, shape, runtime ownership, and the activation lifecycle. +- [Validate Plugin Configuration](/build-plugins/validate-configuration) covers JSON-compatible config, validation rules, and structured diagnostics. +- [Plugin Configuration Files](/build-plugins/plugin-configuration-files) documents `plugins.toml` file discovery, precedence, merge behavior, and editor controls for the CLI gateway. +- [Register Plugin Behavior](/build-plugins/register-behavior) shows how to initialize config and install subscribers or middleware through `PluginContext`. +- [Design Plugin Configuration](/build-plugins/advanced-configuration) covers validation rules, advanced configuration patterns, rollout controls, and `PluginContext` usage. +- [NeMo Guardrails Example Plugin](/build-plugins/nemoguardrails) shows an external Python plugin that applies NeMo Guardrails checks around NeMo Flow LLM and tool calls. +- [Code Examples](/build-plugins/code-examples) provides patterns for dynamic header injection, subscriber-oriented export, multi-surface bundles, and framework-facing plugins. Start by deciding which runtime surfaces the plugin owns: middleware, subscribers, or a combination of related runtime behavior. Define the smallest diff --git a/docs/build-plugins/advanced-configuration.md b/docs/build-plugins/advanced-configuration.mdx similarity index 91% rename from docs/build-plugins/advanced-configuration.md rename to docs/build-plugins/advanced-configuration.mdx index 08d223f0..1be2699c 100644 --- a/docs/build-plugins/advanced-configuration.md +++ b/docs/build-plugins/advanced-configuration.mdx @@ -1,9 +1,10 @@ - - -# Design Plugin Configuration +--- +title: "Design Plugin Configuration" +description: "" +position: 6 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this guide when a plugin needs more than a single flag or string to configure it safely. @@ -172,7 +173,7 @@ Before publishing a plugin config contract: Use these links to continue from this workflow into the next related task. -- Build the first plugin with [Define a Plugin](basic-guide.md). -- Validate plugin config with [Validate Plugin Configuration](validate-configuration.md). -- Register runtime behavior with [Register Plugin Behavior](register-behavior.md). -- Review reusable patterns in [Code Examples](code-examples.md). +- Build the first plugin with [Define a Plugin](/build-plugins/basic-guide). +- Validate plugin config with [Validate Plugin Configuration](/build-plugins/validate-configuration). +- Register runtime behavior with [Register Plugin Behavior](/build-plugins/register-behavior). +- Review reusable patterns in [Code Examples](/build-plugins/code-examples). diff --git a/docs/build-plugins/basic-guide.md b/docs/build-plugins/basic-guide.mdx similarity index 90% rename from docs/build-plugins/basic-guide.md rename to docs/build-plugins/basic-guide.mdx index a76828d2..2e3b56f5 100644 --- a/docs/build-plugins/basic-guide.md +++ b/docs/build-plugins/basic-guide.mdx @@ -1,9 +1,10 @@ - - -# Define a Plugin +--- +title: "Define a Plugin" +description: "" +position: 2 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this guide when you want to package reusable NeMo Flow behavior as a plugin that can be activated from configuration. @@ -11,12 +12,13 @@ Use this guide when you want to package reusable NeMo Flow behavior as a plugin You will define the plugin's purpose, stable kind name, configuration boundary, runtime surfaces, and activation lifecycle. The result is a small plugin contract that can be validated and registered through the more focused follow-on guides. -:::{note} + NeMo Flow plugin configuration keys use `snake_case` in every language and file format. Node.js helper function names are `camelCase`, but the objects passed to `plugin.initialize(...)` use the same canonical `snake_case` keys as Python, Rust, JSON, and TOML plugin configuration. -::: + + ## Before You Start @@ -65,7 +67,7 @@ Start with one surface. Add a bundle only when one configuration document clearl The diagram below shows how plugin configuration turns into registered runtime behavior. -```{mermaid} +```mermaid flowchart TB Kind[Plugin kind
    registered once] Config[Plugin config
    version + components + policy] @@ -142,7 +144,7 @@ Before you write the plugin implementation, answer these questions: Use these links to continue from this workflow into the next related task. -- Define validation behavior with [Validate Plugin Configuration](validate-configuration.md). -- Register runtime behavior with [Register Plugin Behavior](register-behavior.md). -- Add rollout controls with [Design Plugin Configuration](advanced-configuration.md). -- Review complete examples in [Code Examples](code-examples.md). +- Define validation behavior with [Validate Plugin Configuration](/build-plugins/validate-configuration). +- Register runtime behavior with [Register Plugin Behavior](/build-plugins/register-behavior). +- Add rollout controls with [Design Plugin Configuration](/build-plugins/advanced-configuration). +- Review complete examples in [Code Examples](/build-plugins/code-examples). diff --git a/docs/build-plugins/code-examples.md b/docs/build-plugins/code-examples.mdx similarity index 91% rename from docs/build-plugins/code-examples.md rename to docs/build-plugins/code-examples.mdx index 5b64221e..1d179edd 100644 --- a/docs/build-plugins/code-examples.md +++ b/docs/build-plugins/code-examples.mdx @@ -1,9 +1,10 @@ - - -# Code Examples +--- +title: "Code Examples" +description: "" +position: 8 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} This page collects concrete examples for the surrounding guide area. @@ -11,16 +12,11 @@ This page collects concrete examples for the surrounding guide area. Use an LLM request intercept when a plugin needs to inject tenant or routing metadata into every provider request. -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" import nemo_flow - class HeaderPlugin: def validate(self, plugin_config): if "header_name" not in plugin_config or "value" not in plugin_config: @@ -38,15 +34,10 @@ class HeaderPlugin: context.register_llm_request_intercept("inject-header", 100, False, add_header) - nemo_flow.plugin.register("header-plugin", HeaderPlugin()) ``` -::: - -:::{tab-item} Node.js -:sync: node -```ts +```ts title="Node.js" for="node" import * as plugin from 'nemo-flow-node/plugin'; const headerPlugin: plugin.Plugin = { @@ -78,8 +69,8 @@ const headerPlugin: plugin.Plugin = { plugin.register('header-plugin', headerPlugin); ``` -::: -:::: + + This pattern is useful for: @@ -91,16 +82,11 @@ This pattern is useful for: Use a subscriber-oriented plugin when the component should watch the full lifecycle rather than rewrite requests. -::::{tab-set} -:sync-group: language + -:::{tab-item} Python -:sync: python - -```python +```python title="Python" for="python" import nemo_flow - class OpenInferencePlugin: def validate(self, plugin_config): if "endpoint" not in plugin_config: @@ -119,15 +105,10 @@ class OpenInferencePlugin: context.register_subscriber("openinference-export", on_event) - nemo_flow.plugin.register("openinference-export", OpenInferencePlugin()) ``` -::: -:::{tab-item} Node.js -:sync: node - -```ts +```ts title="Node.js" for="node" import * as plugin from 'nemo-flow-node/plugin'; const openInferencePlugin: plugin.Plugin = { @@ -153,8 +134,8 @@ const openInferencePlugin: plugin.Plugin = { plugin.register('openinference-export', openInferencePlugin); ``` -::: -:::: + + This is the right pattern when the component: diff --git a/docs/build-plugins/nemoguardrails.md b/docs/build-plugins/nemoguardrails.mdx similarity index 94% rename from docs/build-plugins/nemoguardrails.md rename to docs/build-plugins/nemoguardrails.mdx index c77b5f1e..b008dc3a 100644 --- a/docs/build-plugins/nemoguardrails.md +++ b/docs/build-plugins/nemoguardrails.mdx @@ -1,9 +1,10 @@ - - -# NeMo Guardrails Example Plugin +--- +title: "NeMo Guardrails Example Plugin" +description: "" +position: 7 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} This example shows how to write a Python NeMo Flow plugin that calls the NeMo Guardrails Python API. @@ -44,7 +45,6 @@ import asyncio import nemo_flow import plugin as nemoguardrails_plugin - async def main() -> None: nemoguardrails_plugin.register() try: @@ -64,7 +64,6 @@ async def main() -> None: nemo_flow.plugin.clear() nemoguardrails_plugin.deregister() - asyncio.run(main()) ``` @@ -125,7 +124,7 @@ Exactly one of `config_path` or `config_yaml` is required. ## Example Agent The example includes -[`agent_example.py`](../../examples/nemoguardrails/example/agent_example.py), a +[`agent_example.py`](https://github.com/NVIDIA/NeMo-Flow/blob/main/examples/nemoguardrails/example/agent_example.py), a concrete example agent that initializes the plugin, checks a managed `tools.execute(...)` call, and checks a managed `llm.execute(...)` call against live NVIDIA-hosted inference. @@ -142,7 +141,7 @@ python examples/nemoguardrails/example/agent_example.py ``` To run the inline self-check rails example, load -[`example_config.yml`](../../examples/nemoguardrails/example/example_config.yml) +[`example_config.yml`](https://github.com/NVIDIA/NeMo-Flow/blob/main/examples/nemoguardrails/example/example_config.yml) from `example` and pass it as inline `config_yaml`: ```bash diff --git a/docs/build-plugins/plugin-configuration-files.md b/docs/build-plugins/plugin-configuration-files.mdx similarity index 94% rename from docs/build-plugins/plugin-configuration-files.md rename to docs/build-plugins/plugin-configuration-files.mdx index 18504c88..77c2db2c 100644 --- a/docs/build-plugins/plugin-configuration-files.md +++ b/docs/build-plugins/plugin-configuration-files.mdx @@ -1,9 +1,10 @@ - - -# Plugin Configuration Files +--- +title: "Plugin Configuration Files" +description: "" +position: 4 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use `plugins.toml` when the `nemo-flow` CLI gateway should activate plugins at startup. The file contains the same generic plugin configuration document used @@ -14,12 +15,13 @@ This page documents file discovery, precedence, merge behavior, editor behavior, and conflict rules for the CLI gateway. Component-specific fields are documented in the guide for each plugin component. -:::{note} + NeMo Flow plugin configuration keys use `snake_case` regardless of language or file format. Node.js helper APIs can have `camelCase` function names, but the generic plugin document and component-local `config` objects use canonical `snake_case` keys. -::: + + ## File Shape @@ -261,7 +263,7 @@ Observability exporters through `plugins.toml`. Use the component guides for field-level configuration: -- [Observability Configuration](../plugins/observability/configuration.md) -- [Adaptive Configuration](../plugins/adaptive/configuration.md) -- [Adaptive Cache Governor (ACG)](../plugins/adaptive/acg.md) -- [Adaptive Hints](../plugins/adaptive/adaptive-hints.md) +- [Observability Configuration](/observability-plugin/configuration) +- [Adaptive Configuration](/adaptive-plugin/configuration) +- [Adaptive Cache Governor (ACG)](/adaptive-plugin/acg) +- [Adaptive Hints](/adaptive-plugin/adaptive-hints) diff --git a/docs/build-plugins/register-behavior.md b/docs/build-plugins/register-behavior.mdx similarity index 92% rename from docs/build-plugins/register-behavior.md rename to docs/build-plugins/register-behavior.mdx index 7c08471f..526206d7 100644 --- a/docs/build-plugins/register-behavior.md +++ b/docs/build-plugins/register-behavior.mdx @@ -1,9 +1,10 @@ - - -# Register Plugin Behavior +--- +title: "Register Plugin Behavior" +description: "" +position: 5 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this guide when plugin config validation is in place and you need the plugin to install real NeMo Flow runtime behavior. @@ -34,13 +35,9 @@ Use the plugin APIs in this order: 5. Inspect the activation report. 6. Clear active config during teardown when needed. -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" import nemo_flow config = nemo_flow.plugin.PluginConfig() @@ -57,12 +54,7 @@ kinds = nemo_flow.plugin.list_kinds() nemo_flow.plugin.clear() ``` -::: - -:::{tab-item} Node.js -:sync: node - -```ts +```ts title="Node.js" for="node" import * as plugin from 'nemo-flow-node/plugin'; const config = plugin.defaultConfig(); @@ -80,12 +72,7 @@ const kinds = plugin.listKinds(); plugin.clear(); ``` -::: - -:::{tab-item} Rust -:sync: rust - -```rust +```rust title="Rust" for="rust" use nemo_flow::plugin::{ clear_plugin_configuration, initialize_plugins, list_plugin_kinds, validate_plugin_config, PluginComponentSpec, PluginConfig, @@ -103,24 +90,17 @@ let kinds = list_plugin_kinds(); clear_plugin_configuration()?; ``` -::: - -:::: + ## Header Plugin Example The same model applies in every binding: validate component-local config, then install middleware through the component-scoped registration context. -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" import nemo_flow - class HeaderPlugin: def validate(self, plugin_config): if "header_name" not in plugin_config or "value" not in plugin_config: @@ -138,16 +118,10 @@ class HeaderPlugin: context.register_llm_request_intercept("inject-header", 100, False, add_header) - nemo_flow.plugin.register("header-plugin", HeaderPlugin()) ``` -::: - -:::{tab-item} Node.js -:sync: node - -```ts +```ts title="Node.js" for="node" import * as plugin from 'nemo-flow-node/plugin'; const headerPlugin: plugin.Plugin = { @@ -178,12 +152,7 @@ const headerPlugin: plugin.Plugin = { plugin.register('header-plugin', headerPlugin); ``` -::: - -:::{tab-item} Rust -:sync: rust - -```rust +```rust title="Rust" for="rust" use nemo_flow::plugin::{ register_plugin, ConfigDiagnostic, DiagnosticLevel, Plugin, PluginRegistrationContext, Result as PluginResult, @@ -262,9 +231,7 @@ impl Plugin for HeaderPlugin { register_plugin(Arc::new(HeaderPlugin))?; ``` -::: - -:::: + ## Registration Checklist @@ -289,5 +256,5 @@ Check these symptoms first when the workflow does not behave as expected. Use these links to continue from this workflow into the next related task. -- Add advanced validation and rollout controls with [Design Plugin Configuration](advanced-configuration.md). -- Review concrete authoring patterns in [Code Examples](code-examples.md). +- Add advanced validation and rollout controls with [Design Plugin Configuration](/build-plugins/advanced-configuration). +- Review concrete authoring patterns in [Code Examples](/build-plugins/code-examples). diff --git a/docs/build-plugins/validate-configuration.md b/docs/build-plugins/validate-configuration.mdx similarity index 86% rename from docs/build-plugins/validate-configuration.md rename to docs/build-plugins/validate-configuration.mdx index 31b148ad..1e5a0a18 100644 --- a/docs/build-plugins/validate-configuration.md +++ b/docs/build-plugins/validate-configuration.mdx @@ -1,9 +1,10 @@ - - -# Validate Plugin Configuration +--- +title: "Validate Plugin Configuration" +description: "" +position: 3 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this guide when you have a plugin kind and need predictable diagnostics before the plugin installs runtime behavior. @@ -23,13 +24,9 @@ Each component has: Disabled components are still validated. This lets operators detect config problems before enabling a component in a later rollout. -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" from nemo_flow.plugin import ComponentSpec, ConfigPolicy, PluginConfig config = PluginConfig( @@ -48,12 +45,8 @@ config = PluginConfig( ), ) ``` -::: -:::{tab-item} Node.js -:sync: node - -```ts +```ts title="Node.js" for="node" import type { PluginConfig } from 'nemo-flow-node/plugin'; const config: PluginConfig = { @@ -72,12 +65,8 @@ const config: PluginConfig = { }, }; ``` -::: - -:::{tab-item} Rust -:sync: rust -```rust +```rust title="Rust" for="rust" use nemo_flow::plugin::{ConfigPolicy, PluginComponentSpec, PluginConfig}; let mut component = PluginComponentSpec::new("header-plugin"); @@ -91,9 +80,8 @@ let config = PluginConfig { policy: ConfigPolicy::default(), }; ``` -::: -:::: + ## Validation Rules @@ -132,13 +120,9 @@ Prefer stable diagnostic codes over prose-only messages. The message can improve Use the validation API before initialization and fail deployment if the report contains errors. -::::{tab-set} -:sync-group: language + -:::{tab-item} Python -:sync: python - -```python +```python title="Python" for="python" import nemo_flow report = nemo_flow.plugin.validate(config) @@ -146,12 +130,8 @@ has_errors = any(diagnostic["level"] == "error" for diagnostic in report["diagno if has_errors: raise RuntimeError(report["diagnostics"]) ``` -::: - -:::{tab-item} Node.js -:sync: node -```ts +```ts title="Node.js" for="node" import * as plugin from 'nemo-flow-node/plugin'; const report = plugin.validate(config); @@ -160,12 +140,8 @@ if (hasErrors) { throw new Error(JSON.stringify(report.diagnostics)); } ``` -::: - -:::{tab-item} Rust -:sync: rust -```rust +```rust title="Rust" for="rust" use nemo_flow::plugin::validate_plugin_config; let report = validate_plugin_config(&config); @@ -173,9 +149,8 @@ if report.has_errors() { anyhow::bail!("{:?}", report.diagnostics); } ``` -::: -:::: + ## Validation Checklist @@ -201,6 +176,6 @@ Check these symptoms first when the workflow does not behave as expected. Use these links to continue from this workflow into the next related task. -- Register runtime behavior with [Register Plugin Behavior](register-behavior.md). -- Add rollout controls with [Design Plugin Configuration](advanced-configuration.md). -- Review concrete validation patterns in [Code Examples](code-examples.md). +- Register runtime behavior with [Register Plugin Behavior](/build-plugins/register-behavior). +- Add rollout controls with [Design Plugin Configuration](/build-plugins/advanced-configuration). +- Review concrete validation patterns in [Code Examples](/build-plugins/code-examples). diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index b07bcdce..00000000 --- a/docs/conf.py +++ /dev/null @@ -1,710 +0,0 @@ -# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. -# SPDX-License-Identifier: Apache-2.0 - -"""Sphinx configuration plus docs-build orchestration for generated API content.""" - -from __future__ import annotations - -import os -import re -import shutil -import subprocess -from pathlib import Path - -import sphinx_js -from packaging.version import InvalidVersion, Version - -project = "NVIDIA NeMo Flow" -copyright = "Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved." -author = "NVIDIA CORPORATION & AFFILIATES" - -CONFIG_DOCS_DIR = Path(__file__).resolve().parent -CONFIG_REPO_ROOT = CONFIG_DOCS_DIR.parent -DOCS_DIR = CONFIG_DOCS_DIR -REPO_ROOT = CONFIG_REPO_ROOT -NODE_PACKAGE_DIR = REPO_ROOT / "crates" / "node" -RUST_CRATE_NAMES = ("core", "adaptive") - -NODE_API_GENERATED_DIR = DOCS_DIR / "reference" / "api" / "nodejs" / "_generated" -NODE_API_SOURCE_DIR = NODE_API_GENERATED_DIR / "source" -PYTHON_API_GENERATED_DIR = DOCS_DIR / "reference" / "api" / "python" / "_generated" -RUST_API_GENERATED_DIR = DOCS_DIR / "reference" / "api" / "rust" / "_generated" -RUST_API_SOURCE_DIR = DOCS_DIR / "reference" / "api" / "rust" / "_source" - -SPHINX_JS_PACKAGE_DIR = Path(sphinx_js.__file__).resolve().parent -SPHINX_JS_SOURCE_DIR = SPHINX_JS_PACKAGE_DIR / "js" -# We patch a local copy of sphinx-js under `_build` so docs generation does -# not mutate installed site-packages. -SPHINX_JS_WORK_DIR = DOCS_DIR / "_build" / ".tooling" / "sphinx-js" - -os.environ.setdefault("TYPEDOC_NODE_MODULES", str(CONFIG_REPO_ROOT / "crates" / "node" / "node_modules")) - -extensions = [ - "myst_parser", - "sphinx_design", - "autoapi.extension", - "sphinx.ext.napoleon", - "sphinx.ext.githubpages", - "sphinx_multiversion", - "sphinxcontrib_rust", - "sphinxcontrib.mermaid", -] - -templates_path = ["_templates"] -exclude_patterns = [ - "_build", - "Thumbs.db", - ".DS_Store", - "reference/api/rust/_source/*/README.md", -] - -source_suffix = { - ".rst": "restructuredtext", - ".md": "markdown", -} -root_doc = "index" - -myst_enable_extensions = [ - "attrs_block", - "colon_fence", - "deflist", - "html_admonition", - "replacements", - "smartquotes", - "strikethrough", - "tasklist", -] -myst_fence_as_directive = ["mermaid"] -myst_heading_anchors = 3 - -autoapi_dirs = ["../python/nemo_flow"] -autoapi_file_patterns = ["*.py", "*.pyi"] -autoapi_root = "reference/api/python/_generated" -autoapi_add_toctree_entry = False -autoapi_member_order = "bysource" -autoapi_options = [ - "members", - "undoc-members", - "show-inheritance", - "show-module-summary", - "imported-members", -] -suppress_warnings = [ - "autoapi.python_import_resolution", - "ref.python", - "myst.xref_missing", - "myst.xref_ambiguous", - "misc.highlighting_failure", - "toc.not_included", -] -napoleon_google_docstring = True -napoleon_numpy_docstring = False -napoleon_attr_annotations = True - -rust_crates = { - "nemo-flow": str(RUST_API_SOURCE_DIR / "core"), - "nemo-flow-adaptive": str(RUST_API_SOURCE_DIR / "adaptive"), -} -rust_doc_dir = str(RUST_API_GENERATED_DIR) -rust_rustdoc_fmt = "md" -rust_strip_src = False -rust_visibility = "pub" -rust_generate_mode = "always" - -html_theme = "nvidia_sphinx_theme" -html_title = "NVIDIA NeMo Flow" -html_static_path = ["_static"] -html_css_files = ["extra.css"] -html_js_files = ["version-switcher.js"] -html_theme_options = { - "navbar_start": ["navbar-logo"], - "navbar_center": [], - "navbar_persistent": ["search-button-field"], - "navbar_end": ["theme-switcher", "navbar-icon-links"], - "header_links_before_dropdown": 7, - "navigation_depth": 4, - "show_nav_level": 2, - "secondary_sidebar_items": ["page-toc"], - "navigation_with_keys": True, - "icon_links": [ - { - "name": "GitHub", - "url": "https://github.com/NVIDIA/NeMo-Flow", - "icon": "fa-brands fa-github", - } - ], -} - -html_context = { - "default_docs_version": "main", -} - -html_sidebars = { - "**": ["version-switcher.html", "sidebar-nav-bs.html"], -} - -_RELEASE_TAG_PATTERN = re.compile(r"^\d+\.\d+\.\d+(?:-(?:alpha|beta|rc)\.\d+)?$") -_MAX_RELEASE_VERSIONS = 5 -_CARGO_SECTION_HEADERS = ("\n[features]\n", "\n[dependencies]\n") -_REMOVED_RUST_LINES = {"mod tests;", "mod private_tests;"} -_TEST_MODULE_DECL = re.compile(r"^mod [A-Za-z_][A-Za-z0-9_]*tests\s*;$") -_PRIVATE_MODULE_DECL = re.compile(r"^(?P\s*)mod (?P[A-Za-z_][A-Za-z0-9_]*)\s*;$") -_PUBLIC_GLOB_REEXPORT = re.compile(r"^\s*pub use (?P[A-Za-z_][A-Za-z0-9_]*)::\*\s*;$") -_EXCLUDED_RUST_DOC_FEATURES = {"redis-backend"} - - -def _parse_release_name(name: str) -> Version | None: - try: - return Version(name) - except InvalidVersion: - return None - - -def _selected_release_tag_names() -> list[str]: - try: - output = subprocess.check_output( - ("git", "tag", "--list"), - text=True, - stderr=subprocess.DEVNULL, - ) - except (OSError, subprocess.CalledProcessError): - return [] - - selected: dict[tuple[int, int], tuple[Version, str]] = {} - latest_stable: tuple[Version, str] | None = None - for raw_name in output.splitlines(): - tag_name = raw_name.strip() - if not tag_name or _RELEASE_TAG_PATTERN.fullmatch(tag_name) is None: - continue - - parsed = _parse_release_name(tag_name) - if parsed is None or parsed.is_devrelease: - continue - - key = (parsed.major, parsed.minor) - current = selected.get(key) - if current is None or parsed > current[0]: - selected[key] = (parsed, tag_name) - - if not parsed.is_prerelease and (latest_stable is None or parsed > latest_stable[0]): - latest_stable = (parsed, tag_name) - - ordered = sorted(selected.values(), key=lambda item: item[0], reverse=True) - chosen: list[str] = [] - seen: set[str] = set() - - if latest_stable is not None: - seen.add(latest_stable[1]) - chosen.append(latest_stable[1]) - - for _, tag_name in ordered: - if tag_name in seen: - continue - chosen.append(tag_name) - seen.add(tag_name) - if len(chosen) >= _MAX_RELEASE_VERSIONS: - break - - return chosen - - -def _selected_release_tag_whitelist() -> str: - tag_names = _selected_release_tag_names() - if not tag_names: - return r"$^" - return r"^(?:" + "|".join(re.escape(name) for name in tag_names) + r")$" - - -# sphinx-multiversion defaults to publishing all branches. Publish tags only. -# `main` still runs regular docs builds in CI, but it should not become a -# published version. -smv_branch_whitelist = r"$^" -smv_tag_whitelist = _selected_release_tag_whitelist() -smv_remote_whitelist = None -smv_released_pattern = r"^refs/tags/\d+\.\d+\.\d+(?:-(?:alpha|beta|rc)\.\d+)?$" -smv_outputdir_format = "{ref.name}" - -mermaid_version = "11.6.0" - - -def _stable_release_order(items): - # The version switcher mixes semver tags, prereleases, and branch-like - # names such as `main`. Split them first so Python never has to compare - # heterogeneous sort keys. - stable = [] - prerelease = [] - other = [] - - for item in items: - parsed = _parse_release_name(item.name) - if parsed is None: - other.append(item) - elif parsed.is_prerelease or parsed.is_devrelease: - prerelease.append((parsed, item)) - else: - stable.append((parsed, item)) - - stable.sort(key=lambda entry: entry[0], reverse=True) - prerelease.sort(key=lambda entry: entry[0], reverse=True) - other.sort(key=lambda item: item.name.lower()) - - ordered = [item for _, item in stable] - ordered.extend(item for _, item in prerelease) - ordered.extend(other) - return ordered - - -def _find_version_by_name(items, name): - return next((item for item in items if item.name == name), None) - - -def _find_latest_stable_release(items): - for item in _stable_release_order(items): - if not _is_prerelease_name(item.name): - return item - return None - - -def _display_release_label(name: str) -> str: - parsed = _parse_release_name(name) - if parsed is None: - return name - - if parsed.is_prerelease: - prerelease_kind, prerelease_number = parsed.pre or ("pre", 0) - prerelease_labels = { - "a": "alpha", - "b": "beta", - "rc": "rc", - } - prerelease_label = prerelease_labels.get(prerelease_kind, prerelease_kind) - return f"v{parsed.major}.{parsed.minor} {prerelease_label}.{prerelease_number}" - - return f"v{parsed.major}.{parsed.minor}" - - -def _display_release_url(url: str, name: str) -> str: - parsed = _parse_release_name(name) - if parsed is None or parsed.is_prerelease: - return url - return url.replace(name, _display_release_label(name), 1) - - -def _is_prerelease_name(name: str) -> bool: - parsed = _parse_release_name(name) - return parsed is not None and (parsed.is_prerelease or parsed.is_devrelease) - - -def _register_version_template_helpers(app) -> None: - templates = getattr(app.builder, "templates", None) - if templates is None: - return - - environment = templates.environment - environment.filters["stable_release_order"] = _stable_release_order - environment.globals["find_version_by_name"] = _find_version_by_name - environment.globals["find_latest_stable_release"] = _find_latest_stable_release - environment.globals["display_release_label"] = _display_release_label - environment.globals["display_release_url"] = _display_release_url - environment.globals["is_prerelease_name"] = _is_prerelease_name - - -def _reset_directory(path: Path) -> None: - shutil.rmtree(path, ignore_errors=True) - path.mkdir(parents=True, exist_ok=True) - - -def _write_text(path: Path, contents: str) -> None: - path.write_text(contents, encoding="utf-8") - - -def _read_text(path: Path) -> str: - return path.read_text(encoding="utf-8") - - -def _replace_once(contents: str, original: str, replacement: str, *, label: str) -> str: - # Fail fast if upstream plugin code changed; silent partial rewrites would - # make docs generation much harder to debug. - if replacement in contents: - return contents - if original not in contents: - raise RuntimeError(f"Unable to apply docs patch for {label}: upstream source changed") - return contents.replace(original, replacement, 1) - - -def _require_node_modules() -> None: - node_modules_dir = NODE_PACKAGE_DIR / "node_modules" - if not node_modules_dir.is_dir(): - raise RuntimeError( - "Node.js docs dependencies are missing. " - "Run `npm install --ignore-scripts` from the repository root before building docs." - ) - - -def _resolve_runtime_paths(source_docs_dir: Path) -> None: - global DOCS_DIR - global REPO_ROOT - global NODE_PACKAGE_DIR - global NODE_API_GENERATED_DIR - global NODE_API_SOURCE_DIR - global PYTHON_API_GENERATED_DIR - global RUST_API_GENERATED_DIR - global RUST_API_SOURCE_DIR - global SPHINX_JS_WORK_DIR - - DOCS_DIR = source_docs_dir.resolve() - REPO_ROOT = DOCS_DIR.parent - NODE_PACKAGE_DIR = REPO_ROOT / "crates" / "node" - NODE_API_GENERATED_DIR = DOCS_DIR / "reference" / "api" / "nodejs" / "_generated" - NODE_API_SOURCE_DIR = NODE_API_GENERATED_DIR / "source" - PYTHON_API_GENERATED_DIR = DOCS_DIR / "reference" / "api" / "python" / "_generated" - RUST_API_GENERATED_DIR = DOCS_DIR / "reference" / "api" / "rust" / "_generated" - RUST_API_SOURCE_DIR = DOCS_DIR / "reference" / "api" / "rust" / "_source" - SPHINX_JS_WORK_DIR = DOCS_DIR / "_build" / ".tooling" / "sphinx-js" - - -def _wire_runtime_config(config) -> None: - config.autoapi_dirs = [str(REPO_ROOT / "python" / "nemo_flow")] - config.rust_crates = { - "nemo-flow": str(RUST_API_SOURCE_DIR / "core"), - "nemo-flow-adaptive": str(RUST_API_SOURCE_DIR / "adaptive"), - } - config.rust_doc_dir = str(RUST_API_GENERATED_DIR) - - -def _ensure_runtime_node_modules() -> None: - runtime_node_modules = NODE_PACKAGE_DIR / "node_modules" - if runtime_node_modules.exists(): - return - - shared_node_modules = CONFIG_REPO_ROOT / "crates" / "node" / "node_modules" - if not shared_node_modules.is_dir(): - return - - runtime_node_modules.parent.mkdir(parents=True, exist_ok=True) - runtime_node_modules.symlink_to(shared_node_modules) - - -def _prepare_output_directories() -> None: - for generated_dir in (NODE_API_GENERATED_DIR, PYTHON_API_GENERATED_DIR, RUST_API_GENERATED_DIR): - _reset_directory(generated_dir) - - NODE_API_SOURCE_DIR.mkdir(parents=True, exist_ok=True) - RUST_API_SOURCE_DIR.mkdir(parents=True, exist_ok=True) - - -def _prepare_patched_sphinx_js_runtime() -> None: - # These patches are compatibility shims for declaration-heavy TypeDoc input - # until the upstream sphinx-js behavior is robust enough for this repo. - _reset_directory(SPHINX_JS_WORK_DIR) - shutil.copytree(SPHINX_JS_SOURCE_DIR, SPHINX_JS_WORK_DIR, dirs_exist_ok=True) - - redirect_aliases = SPHINX_JS_WORK_DIR / "redirectPrivateAliases.ts" - _write_text( - redirect_aliases, - _replace_once( - _read_text(redirect_aliases), - " const decl = name.declarations![0];", - " const decl = name.declarations?.[0];\n if (!decl) {\n continue;\n }", - label="sphinx-js redirectPrivateAliases.ts", - ), - ) - - convert_top_level = SPHINX_JS_WORK_DIR / "convertTopLevel.ts" - _write_text( - convert_top_level, - _replace_once( - _read_text(convert_top_level), - " const first_sig = func.signatures![0]; // Should always have at least one\n", - ( - " const first_sig = func.signatures?.[0];\n" - " if (!first_sig) {\n" - " return {\n" - " ...this.memberProps(func),\n" - " ...this.topLevelProperties(func),\n" - " is_async: false,\n" - " params: [],\n" - " returns: [],\n" - " type_params: this.typeParamsToIR(func.typeParameters),\n" - ' kind: "function",\n' - " exceptions: [],\n" - " };\n" - " }\n" - ), - label="sphinx-js convertTopLevel.ts", - ), - ) - - -def _configure_sphinx_js_environment() -> None: - # The Node artifact builder launches sphinx-js through `tsx`, so it reads - # these paths from the environment instead of importing Python directly. - os.environ["NEMO_FLOW_SPHINX_JS_MAIN_TS"] = str(SPHINX_JS_WORK_DIR / "main.ts") - os.environ["NEMO_FLOW_SPHINX_JS_IMPORT_HOOK"] = str(SPHINX_JS_WORK_DIR / "registerImportHook.mjs") - os.environ["NEMO_FLOW_SPHINX_JS_TSX_TSCONFIG"] = str(SPHINX_JS_WORK_DIR / "tsconfig.json") - - -def _patch_autoapi_summary_signature_normalization() -> None: - # AutoAPI emits Unicode arrows in summary signatures, but Sphinx's - # autosummary mangler only understands ASCII `->` return annotations. - try: - import autoapi.directives as autoapi_directives - except ImportError: - return - - original_mangle_signature = autoapi_directives.mangle_signature - if getattr(original_mangle_signature, "_nemo_flow_normalizes_unicode_arrow", False): - return - - def _nemo_flow_mangle_signature(sig: str, *args, **kwargs) -> str: - normalized = sig.replace(" \u2192 ", " -> ") - return original_mangle_signature(normalized, *args, **kwargs) - - _nemo_flow_mangle_signature._nemo_flow_normalizes_unicode_arrow = True - autoapi_directives.mangle_signature = _nemo_flow_mangle_signature - - -def _skip_imported_type_aliases(_app, what, _name, obj, skip, _options): - if what == "module" and getattr(obj, "id", None) == "nemo_flow._native": - return False - - if skip: - return skip - - is_type_alias = getattr(obj, "is_type_alias", lambda: False) - if what == "data" and getattr(obj, "imported", False) and is_type_alias(): - return True - - return None - - -def _run_node_docs_artifact_builder() -> None: - subprocess.run( - ("node", str(CONFIG_REPO_ROOT / "scripts" / "docs" / "build_node_docs_artifacts.mjs")), - check=True, - cwd=CONFIG_REPO_ROOT, - env={ - **os.environ, - "NEMO_FLOW_DOCS_REPO_ROOT": str(REPO_ROOT), - "NEMO_FLOW_DOCS_DIR": str(DOCS_DIR), - }, - ) - - -def _ensure_rustdoc_mod_entry(crate_dir: Path) -> None: - # `sphinxcontrib-rust` is happier when the crate entrypoint looks like a - # module tree rooted at `src/mod.rs` instead of `src/lib.rs`. - lib_rs = crate_dir / "src" / "lib.rs" - if not lib_rs.exists(): - return - - mod_rs = crate_dir / "src" / "mod.rs" - _write_text(mod_rs, _read_text(lib_rs)) - lib_rs.unlink() - - cargo_toml = crate_dir / "Cargo.toml" - cargo_text = _read_text(cargo_toml) - if "\n[lib]\n" not in cargo_text: - insert_at = -1 - for header in _CARGO_SECTION_HEADERS: - insert_at = cargo_text.find(header) - if insert_at != -1: - break - if insert_at == -1: - cargo_text += '\n[lib]\npath = "src/mod.rs"\n' - else: - cargo_text = cargo_text[:insert_at] + '\n[lib]\npath = "src/mod.rs"\n' + cargo_text[insert_at:] - elif 'path = "src/mod.rs"' not in cargo_text: - cargo_text = cargo_text.replace("\n[lib]\n", '\n[lib]\npath = "src/mod.rs"\n', 1) - _write_text(cargo_toml, cargo_text) - - -def _rust_attr_excludes_default_docs(stripped_line: str) -> bool: - if stripped_line == "#[doc(hidden)]": - return True - if stripped_line.startswith(("#[cfg(test", "#[cfg(all(test", '#[cfg(target_arch = "wasm32"')): - return True - - for feature in _EXCLUDED_RUST_DOC_FEATURES: - if f'feature = "{feature}"' in stripped_line and not stripped_line.startswith("#[cfg(not("): - return True - - return False - - -def _rust_skip_item_continues( - line: str, - saw_brace: bool, - brace_depth: int, - paren_depth: int, -) -> tuple[bool, int, int, bool]: - stripped = line.strip() - if not stripped: - return True, brace_depth, paren_depth, saw_brace - if stripped.startswith(("#[", "///", "//!")): - return True, brace_depth, paren_depth, saw_brace - - open_count = line.count("{") - close_count = line.count("}") - if open_count: - saw_brace = True - brace_depth += open_count - close_count - paren_depth += line.count("(") - line.count(")") - - if saw_brace: - return brace_depth > 0, brace_depth, paren_depth, saw_brace - - item_ended = stripped.endswith(";") or (stripped.endswith(",") and paren_depth <= 0) - return not item_ended, brace_depth, paren_depth, saw_brace - - -def _drop_trailing_rust_doc_comments(lines: list[str]) -> None: - while lines and lines[-1].lstrip().startswith("///"): - lines.pop() - - -def _strip_rustdoc_hostile_lines(crate_dir: Path) -> None: - # Strip attributes and local test modules from the staged copy only. This - # avoids rustdoc/plugin parse issues without touching real source files. - # Items hidden from rustdoc or gated out of the documented default target are - # removed with their following item so generated reference pages do not - # expose unavailable public APIs. - for rust_file in crate_dir.rglob("*.rs"): - stripped = [] - skip_item = False - skip_saw_brace = False - skip_brace_depth = 0 - skip_paren_depth = 0 - - for line in _read_text(rust_file).splitlines(): - line_stripped = line.strip() - - if skip_item: - skip_item, skip_brace_depth, skip_paren_depth, skip_saw_brace = _rust_skip_item_continues( - line, - skip_saw_brace, - skip_brace_depth, - skip_paren_depth, - ) - continue - - if _rust_attr_excludes_default_docs(line_stripped): - _drop_trailing_rust_doc_comments(stripped) - skip_item = True - skip_saw_brace = False - skip_brace_depth = 0 - skip_paren_depth = 0 - continue - - if ( - line.lstrip().startswith("#[") - or line_stripped in _REMOVED_RUST_LINES - or _TEST_MODULE_DECL.fullmatch(line_stripped) is not None - ): - continue - - stripped.append(line) - _write_text(rust_file, "\n".join(stripped) + "\n") - - -def _promote_reexported_modules_for_docs(crate_dir: Path) -> None: - # `sphinxcontrib-rust` only generates child module pages for public modules. - # Some FFI surfaces flatten submodules with `pub use foo::*;` while keeping - # the modules themselves private. In the staged docs copy, promote only - # those re-exported modules so generated docs reflect the public surface. - for rust_file in crate_dir.rglob("*.rs"): - lines = _read_text(rust_file).splitlines() - reexported = {match.group("name") for line in lines if (match := _PUBLIC_GLOB_REEXPORT.match(line)) is not None} - if not reexported: - continue - - updated = [] - changed = False - for line in lines: - match = _PRIVATE_MODULE_DECL.match(line) - if match is not None and match.group("name") in reexported: - updated.append(f"{match.group('indent')}pub mod {match.group('name')};") - changed = True - else: - updated.append(line) - - if changed: - _write_text(rust_file, "\n".join(updated) + "\n") - - -def _stage_rust_crate(crate_name: str) -> None: - source_dir = REPO_ROOT / "crates" / crate_name - dest_dir = RUST_API_SOURCE_DIR / crate_name - shutil.rmtree(dest_dir, ignore_errors=True) - shutil.copytree(source_dir, dest_dir, ignore=shutil.ignore_patterns("tests", "target")) - _ensure_rustdoc_mod_entry(dest_dir) - _strip_rustdoc_hostile_lines(dest_dir) - _promote_reexported_modules_for_docs(dest_dir) - - -def _stage_rust_sources() -> None: - for crate_name in RUST_CRATE_NAMES: - _stage_rust_crate(crate_name) - - -def _rewrite_generated_rust_toctrees() -> None: - for doc_path in RUST_API_GENERATED_DIR.rglob("*.md"): - lines = _read_text(doc_path).splitlines() - updated: list[str] = [] - in_toctree = False - changed = False - - for line in lines: - stripped = line.strip() - if stripped == ":::{toctree}": - in_toctree = True - updated.append(line) - continue - - if in_toctree and stripped == ":::": # end of MyST directive block - in_toctree = False - updated.append(line) - continue - - if not in_toctree or not stripped or stripped.startswith(":"): - updated.append(line) - continue - - direct_target = doc_path.parent / f"{stripped}.md" - src_target = doc_path.parent / "src" / f"{stripped}.md" - if not direct_target.exists() and src_target.exists(): - indent = line[: len(line) - len(line.lstrip())] - updated.append(f"{indent}src/{stripped}") - changed = True - continue - - updated.append(line) - - if changed: - _write_text(doc_path, "\n".join(updated) + "\n") - - -def _postprocess_generated_rust_docs(_app) -> None: - _rewrite_generated_rust_toctrees() - - -def _prepare_api_sources(_app, _config) -> None: - _resolve_runtime_paths(Path(_app.srcdir)) - _wire_runtime_config(_config) - _ensure_runtime_node_modules() - _prepare_output_directories() - _require_node_modules() - _prepare_patched_sphinx_js_runtime() - _configure_sphinx_js_environment() - _run_node_docs_artifact_builder() - _stage_rust_sources() - - -def setup(app): - _patch_autoapi_summary_signature_normalization() - app.connect("autoapi-skip-member", _skip_imported_type_aliases) - # Generated sources must exist before Sphinx resolves toctrees, so this - # runs on `config-inited` rather than `builder-inited`. - app.connect("config-inited", _prepare_api_sources) - app.connect("builder-inited", _postprocess_generated_rust_docs) - app.connect("builder-inited", _register_version_template_helpers) diff --git a/docs/contribute/about.md b/docs/contribute/about.mdx similarity index 52% rename from docs/contribute/about.md rename to docs/contribute/about.mdx index 8bafa6b4..0046043d 100644 --- a/docs/contribute/about.md +++ b/docs/contribute/about.mdx @@ -1,9 +1,10 @@ - - -# About +--- +title: "About" +description: "" +position: 1 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this section when you want to contribute to NeMo Flow source code, bindings, documentation, examples, tests, or third-party integration patches. @@ -19,24 +20,24 @@ validated. Use these signals to decide whether this documentation path matches your current task. -- Setting up the repository for source development +- Setting up the repository for source dev - Choosing which language tests apply to a change - Updating docs or examples alongside behavior - Preparing a pull request for review - Looking for contribution workflow details beyond user-facing product docs -If you are only consuming NeMo Flow packages, start with [Getting Started](../getting-started/quick-start.md) instead. +If you are only consuming NeMo Flow packages, start with [Getting Started](/getting-started/quick-start) instead. ## Guides Use these guide links to move from the overview into task-specific instructions. -- [Development Setup](development-setup.md) covers package installation, source setup, branch naming, and code style. -- [Workflow and Reviews](workflow-and-reviews.md) covers pre-commit hooks, pull request expectations, release tag conventions, DCO sign-off, commit messages, and review rules. -- [Testing and Documentation](testing-and-docs.md) covers affected-language test selection, common build and test commands, documentation checks, and licensing expectations. +- [Development Setup](/contribute/development-setup) covers package installation, source setup, branch naming, and code style. +- [Workflow and Reviews](/contribute/workflow-and-reviews) covers pre-commit hooks, pull request expectations, release tag conventions, DCO sign-off, commit messages, and review rules. +- [Testing and Documentation](/contribute/testing-and-docs) covers affected-language test selection, common build and test commands, documentation checks, and licensing expectations. -Read [Development Setup](development-setup.md) before building locally. Use -[Testing and Documentation](testing-and-docs.md) to choose the smallest +Read [Development Setup](/contribute/development-setup) before building locally. Use +[Testing and Documentation](/contribute/testing-and-docs) to choose the smallest validation set that covers your change. Before opening a pull request, review -[Workflow and Reviews](workflow-and-reviews.md) and the repository root +[Workflow and Reviews](/contribute/workflow-and-reviews) and the repository root `CONTRIBUTING.md` guide. diff --git a/docs/contribute/development-setup.md b/docs/contribute/development-setup.mdx similarity index 87% rename from docs/contribute/development-setup.md rename to docs/contribute/development-setup.mdx index 9151b029..3eaba8db 100644 --- a/docs/contribute/development-setup.md +++ b/docs/contribute/development-setup.mdx @@ -1,9 +1,10 @@ - - -# Development Setup +--- +title: "Development Setup" +description: "" +position: 2 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} This section collects the setup steps needed before building, testing, or contributing changes. @@ -12,7 +13,7 @@ changes. If you are consuming NeMo Flow rather than developing this repository, install the published package for your language. Use -[Installation](../getting-started/installation.md) for package-manager commands +[Installation](/getting-started/installation) for package-manager commands covering the CLI, Python, Node.js, Rust, and supported integrations. Go, WebAssembly, and the raw FFI surface are currently experimental and remain diff --git a/docs/contribute/testing-and-docs.md b/docs/contribute/testing-and-docs.mdx similarity index 84% rename from docs/contribute/testing-and-docs.md rename to docs/contribute/testing-and-docs.mdx index a094c8a0..e563e522 100644 --- a/docs/contribute/testing-and-docs.md +++ b/docs/contribute/testing-and-docs.mdx @@ -1,9 +1,10 @@ - - -# Testing and Documentation +--- +title: "Testing and Documentation" +description: "" +position: 4 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} This page describes the validation and documentation checks expected for repository changes. @@ -86,7 +87,9 @@ Before opening a PR, confirm: ## Docs Verification -Use these commands to build and check the documentation site after docs changes. +Use these commands to validate the Fern documentation site after docs changes. +They regenerate the ignored Python, Node.js, and Rust API reference pages before +checking the Fern site. ```bash just docs diff --git a/docs/contribute/workflow-and-reviews.md b/docs/contribute/workflow-and-reviews.mdx similarity index 84% rename from docs/contribute/workflow-and-reviews.md rename to docs/contribute/workflow-and-reviews.mdx index 205c7225..bb9b1423 100644 --- a/docs/contribute/workflow-and-reviews.md +++ b/docs/contribute/workflow-and-reviews.mdx @@ -1,9 +1,10 @@ - - -# Workflow and Reviews +--- +title: "Workflow and Reviews" +description: "" +position: 3 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} This page describes the contribution workflow from local hooks through PR review. @@ -22,7 +23,7 @@ uv run pre-commit run --all-files ``` The configured hooks include a lightweight Markdown link check for -`README.md`, `CONTRIBUTING.md`, and files under `docs/`. +`README.md`, `CONTRIBUTING.md`, and files under `fern/`. ## Pull Request Process @@ -46,7 +47,7 @@ This keeps tags aligned with Cargo versions across the workspace. CI still rejects `v`-prefixed release tags. For the maintainer release process and release-notes policy, see -[`RELEASING.md`](../../RELEASING.md). +[`RELEASING.md`](https://github.com/NVIDIA/NeMo-Flow/blob/main/RELEASING.md). ## PR Description diff --git a/docs/getting-started/configuration.md b/docs/getting-started/configuration.mdx similarity index 73% rename from docs/getting-started/configuration.md rename to docs/getting-started/configuration.mdx index 23feda2c..f1ed6d64 100644 --- a/docs/getting-started/configuration.md +++ b/docs/getting-started/configuration.mdx @@ -1,9 +1,11 @@ - - -# Configuration +--- +title: "Configuration" +sidebar-title: "Configuration / Setup" +description: "" +position: 3 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} NeMo Flow runtime behavior is configured through API objects and registration calls rather than a global configuration file. @@ -26,10 +28,10 @@ Plugins use a structured plugin configuration with: - One or more component definitions - Optional component policy -Start with [Define a Plugin](../build-plugins/basic-guide.md) when you need reusable middleware, subscribers, or adaptive behavior. +Start with [Define a Plugin](/build-plugins/basic-guide) when you need reusable middleware, subscribers, or adaptive behavior. The `nemo-flow` CLI gateway reads plugin files named `plugins.toml`. See -[Plugin Configuration Files](../build-plugins/plugin-configuration-files.md) +[Plugin Configuration Files](/build-plugins/plugin-configuration-files) for file locations, precedence, merge behavior, editor controls, and validation rules. @@ -40,8 +42,8 @@ Interchange Format (ATIF) exporters, OpenTelemetry subscribers, and OpenInference subscribers can be configured directly through binding-native config objects. Use the built-in `observability` plugin when you want one plugin component to own standard exporter setup and teardown. See -[Observability Configuration](../plugins/observability/configuration.md) -and [Observability](../plugins/observability/about.md) +[Observability Configuration](/observability-plugin/configuration) +and [Observability](/observability-plugin/about) for the supported export paths. NeMo Flow does not require application-level environment variables for normal @@ -55,4 +57,4 @@ deployment manifests. ## Adaptive Setup -Adaptive optimization is enabled through the adaptive plugin component and binding helper APIs. See [Adaptive Configuration](../plugins/adaptive/configuration.md). +Adaptive optimization is enabled through the adaptive plugin component and binding helper APIs. See [Adaptive Configuration](/adaptive-plugin/configuration). diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.mdx similarity index 84% rename from docs/getting-started/installation.md rename to docs/getting-started/installation.mdx index 34ea54be..5d326ace 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.mdx @@ -1,16 +1,17 @@ - - -# Installation +--- +title: "Installation" +description: "" +position: 2 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this page when you are consuming a published NeMo Flow release from a package manager. If you are working from a source checkout, validating unpublished changes, or contributing to the repository, use -[Development Setup](../contribute/development-setup.md) instead. +[Development Setup](/contribute/development-setup) instead. ## CLI @@ -74,7 +75,7 @@ openclaw gateway restart Use the package name `nemo-flow-openclaw` for installation. Use the plugin ID `nemo-flow` in OpenClaw configuration, inspection, and gateway status commands. -See the [OpenClaw Plugin Guide](../integrations/openclaw-plugin.md) for +See the [OpenClaw Plugin Guide](/supported-integrations/openclaw-plugin) for configuration and verification steps. ### Python Framework Integrations @@ -88,5 +89,5 @@ uv add "nemo-flow[langchain,langgraph,deepagents]@0.3.0" The extras install the NeMo Flow Python package plus the dependencies needed by the maintained public integrations. See -[Supported Integrations](../integrations/about.md) for guide links and support +[Supported Integrations](/supported-integrations/about) for guide links and support levels. diff --git a/docs/getting-started/prerequisites.md b/docs/getting-started/prerequisites.mdx similarity index 50% rename from docs/getting-started/prerequisites.md rename to docs/getting-started/prerequisites.mdx index 0b707629..1347a6b9 100644 --- a/docs/getting-started/prerequisites.md +++ b/docs/getting-started/prerequisites.mdx @@ -1,9 +1,10 @@ - - -# Prerequisites +--- +title: "Prerequisites" +description: "" +position: 1 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Install the tooling for the binding you plan to use. @@ -11,9 +12,9 @@ Install the tooling for the binding you plan to use. |---|---|---| | Rust | 1.86 or newer | Rust builds, local workspace builds, and the Rust core runtime | | Python | 3.11 or newer | Python bindings, Python tests, and docs tooling | -| Node.js | 20 or newer | Node.js bindings and generated Node.js API docs | -| `uv` | see [Development Setup](../contribute/development-setup.md) | Python environments, docs builds, and repository setup | -| `just` | see [Development Setup](../contribute/development-setup.md) | Repository development, test, build, and docs task aliases | +| Node.js | 20 or newer | Node.js bindings and local package builds | +| `uv` | see [Development Setup](/contribute/development-setup) | Python environments, docs builds, and repository setup | +| `just` | see [Development Setup](/contribute/development-setup) | Repository dev, test, build, and docs task aliases | The primary documentation track covers Rust, Python, and Node.js. Go, WebAssembly, and the raw FFI surface are experimental and source-first. @@ -26,13 +27,13 @@ git clone https://github.com/NVIDIA/NeMo-Flow.git cd NeMo-Flow ``` -Install development dependencies for Python and docs workflows: +Install dev dependencies for Python and docs workflows: ```bash uv sync ``` -Install Node.js dependencies when you need Node.js builds or generated Node.js API documentation: +Install Node.js dependencies when you need Node.js builds or local package validation: ```bash npm install --ignore-scripts diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md deleted file mode 100644 index 39842504..00000000 --- a/docs/getting-started/quick-start.md +++ /dev/null @@ -1,16 +0,0 @@ - - -# Quick Start - -Choose the Quick Start guide for the primary binding that you plan to use. - -```{toctree} -:maxdepth: 1 - -Python Quick Start -Node.js Quick Start -Rust Quick Start -``` diff --git a/docs/getting-started/quick-start/index.mdx b/docs/getting-started/quick-start/index.mdx new file mode 100644 index 00000000..ba9b9630 --- /dev/null +++ b/docs/getting-started/quick-start/index.mdx @@ -0,0 +1,9 @@ +--- +title: "Quick Start" +description: "" +position: 4 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} + +Choose the Quick Start guide for the primary binding that you plan to use. diff --git a/docs/getting-started/nodejs.md b/docs/getting-started/quick-start/nodejs.mdx similarity index 83% rename from docs/getting-started/nodejs.md rename to docs/getting-started/quick-start/nodejs.mdx index 0279dc2f..ff003ff0 100644 --- a/docs/getting-started/nodejs.md +++ b/docs/getting-started/quick-start/nodejs.mdx @@ -1,9 +1,10 @@ - - -# Node.js Quick Start +--- +title: "Node.js Quick Start" +description: "" +position: 2 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} This quick start shows the smallest Node.js workflow that emits scope, tool, and LLM events. @@ -15,7 +16,7 @@ local checkout. ### Install from a Package Manager -Use this path when you want the published package for application development. +Use this path when you want the published package for application dev. ```bash npm install nemo-flow-node @@ -31,7 +32,7 @@ npm install --ignore-scripts npm run build --workspace=nemo-flow-node ``` -This path is for local source development when you need to build the binding from the repository checkout. +This path is for local source dev when you need to build the binding from the repository checkout. ## Run One Scope, One Tool Call, and One LLM Call @@ -116,6 +117,6 @@ integrations. Use these links to continue from the quick start into the core runtime concepts. -- [Instrument Applications Code Examples](../instrument-applications/code-examples.md) -- [Subscribers](../about/concepts/subscribers.md) -- [Using Codecs](../integrate-frameworks/using-codecs.md) +- [Instrument Applications Code Examples](/instrument-applications/code-examples) +- [Subscribers](/about-nemo-flow/concepts/subscribers) +- [Using Codecs](/integrate-into-frameworks/using-codecs) diff --git a/docs/getting-started/python/index.md b/docs/getting-started/quick-start/python.mdx similarity index 84% rename from docs/getting-started/python/index.md rename to docs/getting-started/quick-start/python.mdx index 9145c0fb..8eabd21a 100644 --- a/docs/getting-started/python/index.md +++ b/docs/getting-started/quick-start/python.mdx @@ -1,13 +1,14 @@ - - -# Python Quick Start +--- +title: "Python Quick Start" +description: "" +position: 1 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} This quick start shows the smallest Python workflow that emits scope, tool, and LLM events. -[LangChain](https://www.langchain.com/langchain), [LangGraph](https://www.langchain.com/langgraph), and [Deep Agents](https://www.langchain.com/deep-agents) users should start with the [LangChain integration](../../integrations/langchain.md), [LangGraph integration](../../integrations/langgraph.md), and [Deep Agents integration](../../integrations/deepagents.md) guides for the best experience in those frameworks. +[LangChain](https://www.langchain.com/langchain), [LangGraph](https://www.langchain.com/langgraph), and [Deep Agents](https://www.langchain.com/deep-agents) users should start with the [LangChain integration](/supported-integrations/langchain), [LangGraph integration](/supported-integrations/langgraph), and [Deep Agents integration](/supported-integrations/deepagents) guides for the best experience in those frameworks. ## Choose an Install Path @@ -16,7 +17,7 @@ local checkout. ### Install from a Package Manager -Use this path when you want the published package for application development. +Use this path when you want the published package for application dev. ```bash uv add nemo-flow@0.3.0 @@ -57,22 +58,18 @@ import asyncio import nemo_flow - def on_event(event) -> None: print(f"event={event.kind} name={event.name}") - async def search(args): return {"echo": args["query"]} - async def model(request): return { "messages": request.content["messages"], "ok": True, } - async def main(): nemo_flow.subscribers.register("quickstart-printer", on_event) @@ -92,7 +89,6 @@ async def main(): nemo_flow.subscribers.deregister("quickstart-printer") - asyncio.run(main()) ``` @@ -127,7 +123,7 @@ These modules are the main Python APIs to use from applications and integrations Use these links to continue from the quick start into the core runtime concepts. -- [Supported Integrations](../../integrations/about.md) -- [Scopes](../../about/concepts/scopes.md) -- [Middleware](../../about/concepts/middleware.md) -- [Plugins](../../about/concepts/plugins.md) +- [Supported Integrations](/supported-integrations/about) +- [Scopes](/about-nemo-flow/concepts/scopes) +- [Middleware](/about-nemo-flow/concepts/middleware) +- [Plugins](/about-nemo-flow/concepts/plugins) diff --git a/docs/getting-started/rust.md b/docs/getting-started/quick-start/rust.mdx similarity index 86% rename from docs/getting-started/rust.md rename to docs/getting-started/quick-start/rust.mdx index fcbbe355..8e307782 100644 --- a/docs/getting-started/rust.md +++ b/docs/getting-started/quick-start/rust.mdx @@ -1,9 +1,10 @@ - - -# Rust Quick Start +--- +title: "Rust Quick Start" +description: "" +position: 3 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} This quick start shows the smallest Rust workflow that emits scope and mark events. @@ -102,4 +103,4 @@ That tells you two things: Use these links to continue from the quick start into the core runtime concepts. -- Use [Scopes](../about/concepts/scopes.md), [Middleware](../about/concepts/middleware.md), [Subscribers](../about/concepts/subscribers.md), and [Plugins](../about/concepts/plugins.md) for the runtime model. +- Use [Scopes](/about-nemo-flow/concepts/scopes), [Middleware](/about-nemo-flow/concepts/middleware), [Subscribers](/about-nemo-flow/concepts/subscribers), and [Plugins](/about-nemo-flow/concepts/plugins) for the runtime model. diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index a51f42b8..00000000 --- a/docs/index.md +++ /dev/null @@ -1,282 +0,0 @@ - - -# Overview - -NeMo Flow is a portable execution runtime for agent systems that already have a -framework, model provider, policy layer, or observability backend. It gives those -systems one consistent way to describe what is happening when an agent crosses a -request, tool, or LLM boundary. - -That layer is useful because agent applications rarely live inside one clean -abstraction. A production stack might combine NeMo Agent Toolkit, LangChain, -LangGraph, provider SDKs, custom harness code, NeMo Guardrails, tracing systems, -and evaluation pipelines. NeMo Flow sits underneath those choices as the shared -runtime contract for scopes, middleware, plugins, lifecycle events, adaptive -behavior, and observability. Under the NeMo Flow scope stack and middleware, the scoped execution path is referred to as work. - -The result is a framework-neutral substrate for agent execution. Applications -keep their orchestration model, providers keep their native clients, and -middleware authors get one place to package policy, interception, telemetry, and -adaptive behavior across Rust, Python, and Node.js. - -## Benefits - -NeMo Flow is designed for teams that need agent runtime behavior to stay -consistent as applications grow across frameworks, languages, and deployment -targets. - -- **Instrument once at the execution boundary**: Managed tool and LLM helpers - attach work to the active scope, emit lifecycle events, and run the same - middleware pipeline without scattering custom wrappers through every call site. -- **Keep concurrent agents isolated**: Hierarchical scopes preserve parent-child - event relationships, expose request-local middleware and subscribers, and - clean up scope-owned registrations when work finishes. -- **Turn policy into reusable runtime components**: Guardrails and intercepts can - block work, sanitize observability payloads, transform requests, or wrap - execution. Plugins package that behavior so applications and framework - integrations can install it from configuration. -- **Export one event stream to many backends**: Subscribers consume the canonical - lifecycle stream in-process or translate it to Agent Trajectory Interchange - Format (ATIF) trajectories, OpenTelemetry traces, and OpenInference-compatible - traces for debugging, evaluation, and production observability. -- **Adopt without replacing the stack**: NeMo Flow can sit below NeMo ecosystem - components, third-party agent frameworks, provider adapters, or direct - application code, so teams can add shared runtime semantics without a - framework migration. -- **Share semantics across primary bindings**: The Rust core, Python wrapper, - and Node.js binding expose the same execution model, which helps framework - authors, plugin authors, and application teams reason about behavior - consistently. - -## What Should I Read First? - -Use the reading path that matches your task: - -| Task | Start With | -|---|---| -| Run a minimal example | [Quick Start](getting-started/quick-start.md) | -| Install packages | [Installation](getting-started/installation.md) | -| Develop from source | [Development Setup](contribute/development-setup.md) | -| Understand the runtime model | [Concepts](about/concepts/index.md) | -| Instrument an application | [Instrument Applications](instrument-applications/about.md) | -| Use a maintained integration | [Supported Integrations](integrations/about.md) | -| Integrate a framework | [Integrate into Frameworks](integrate-frameworks/about.md) | -| Observe a local coding-agent CLI | [NeMo Flow CLI](nemo-flow-cli/about.md) | -| Package reusable behavior | [Build Plugins](build-plugins/about.md) | -| Export traces or trajectories | [Observability](plugins/observability/about.md) | -| Configure adaptive behavior | [Adaptive](plugins/adaptive/about.md) | -| Look up symbols | [APIs](reference/api/index.md) | - -## Conceptual Diagram - -The diagram below shows how applications, runtime components, and exporters -relate to each other. Scopes define where work belongs, middleware registries -define what runs around that work, and subscribers consume the lifecycle events -that the core emits. - -```{mermaid} -flowchart TB - Plugin[Plugin] - App[Application Code / Agent Harness / Agent Framework] - Framework[Framework Integration] - - subgraph Runtime[Runtime] - PluginSystem[Plugin System] - Bindings[Language Bindings] - Core[Rust Core Runtime] - Events[Lifecycle Events] - - subgraph RuntimeState[Runtime State] - Registry[Middleware Registries
    what runs around work] - Scope[Scope Stack
    where work belongs] - end - - Subs[Subscribers / Exporters] - - PluginSystem --->|installs| Registry - PluginSystem ----->|installs| Subs - Bindings --> Core - Core -->|emits| Events -->|consumed by| Subs - Core -->|updates| Scope - Core -->|resolves| Registry - end - - App -->|registers| Plugin - App -->|uses| Framework - App -->|configures/initializes| PluginSystem - App -->|uses| Bindings - Framework -->|calls| Bindings - Plugin -->|registers with| PluginSystem - - class Runtime grey-lightest; - class RuntimeState grey-lightest; - class App purple-lightest; - class Framework yellow-lightest; - class Plugin blue-lightest; - class Bindings green-lightest; - class PluginSystem green-light; - class Core green-light; - class Scope green-light; - class Registry green-light; - class Events green-light; - class Subs green-light; -``` - - -```{toctree} -:hidden: -:caption: About NeMo Flow -:maxdepth: 2 - -Overview -Architecture -Ecosystem -about/concepts/index -about/release-notes/index -``` - -```{toctree} -:hidden: -:caption: Getting Started -:maxdepth: 2 - -getting-started/prerequisites -getting-started/installation -Configuration / Setup -Quick Start -``` - -```{toctree} -:hidden: -:caption: NeMo Flow CLI -:maxdepth: 2 - -About -Basic Usage -Claude Code -Codex -Cursor -Hermes Agent -``` - -```{toctree} -:hidden: -:caption: Supported Integrations -:maxdepth: 2 - -About -OpenClaw Plugin Guide -LangChain Integration Guide -LangGraph Integration Guide -Deep Agents Integration Guide -``` - -```{toctree} -:hidden: -:caption: Instrument Applications -:maxdepth: 2 - -About -Adding Scopes and Marks -Instrument a Tool Call -Instrument an LLM Call -Add Middleware -Code Examples -``` - -```{toctree} -:hidden: -:caption: Observability Plugin -:maxdepth: 2 - -About -Configuration -Agent Trajectory Interchange Format (ATIF) -Agent Trajectory Observability Format (ATOF) -OpenTelemetry -OpenInference -``` - -```{toctree} -:hidden: -:caption: Adaptive Plugin -:maxdepth: 2 - -About -Configuration -Adaptive Cache Governor (ACG) -Adaptive Hints -``` - -```{toctree} -:hidden: -:caption: Integrate into Frameworks -:maxdepth: 2 - -About -Adding Scopes -Wrap Tool Calls -Wrap LLM Calls -Handle Non-Serializable Data -Using Codecs -Provider Codecs -Provider Response Codecs -Code Examples -``` - -```{toctree} -:hidden: -:caption: Build Plugins -:maxdepth: 2 - -About -Define a Plugin -Validate Plugin Configuration -Plugin Configuration Files -Register Plugin Behavior -Design Plugin Configuration -NeMo Guardrails Example Plugin -Code Examples -``` - -```{toctree} -:hidden: -:caption: Contribute -:maxdepth: 2 - -About -Development Setup -Workflow and Reviews -Testing and Documentation -``` - -```{toctree} -:hidden: -:caption: Reference -:maxdepth: 2 - -APIs -reference/performance -``` - -```{toctree} -:hidden: -:caption: Troubleshooting -:maxdepth: 2 - -Troubleshooting Guide -``` - -```{toctree} -:hidden: -:caption: Resources -:maxdepth: 2 - -Support and FAQs -resources/glossary -resources/community -resources/legal/index -``` diff --git a/docs/index.yml b/docs/index.yml new file mode 100644 index 00000000..25349dcf --- /dev/null +++ b/docs/index.yml @@ -0,0 +1,52 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +navigation: + - folder: ./about + title: "About NeMo Flow" + slug: about-nemo-flow + title-source: frontmatter + - folder: ./getting-started + title: "Getting Started" + slug: getting-started + title-source: frontmatter + - folder: ./nemo-flow-cli + title: "NeMo Flow CLI" + slug: nemo-flow-cli + title-source: frontmatter + - folder: ./integrations + title: "Supported Integrations" + slug: supported-integrations + title-source: frontmatter + - folder: ./instrument-applications + title: "Instrument Applications" + slug: instrument-applications + title-source: frontmatter + - folder: ./plugins/observability + title: "Observability Plugin" + slug: observability-plugin + title-source: frontmatter + - folder: ./plugins/adaptive + title: "Adaptive Plugin" + slug: adaptive-plugin + title-source: frontmatter + - folder: ./integrate-frameworks + title: "Integrate into Frameworks" + slug: integrate-into-frameworks + title-source: frontmatter + - folder: ./build-plugins + title: "Build Plugins" + slug: build-plugins + title-source: frontmatter + - folder: ./contribute + title: "Contribute" + slug: contribute + title-source: frontmatter + - folder: ./reference + title: "Reference" + slug: reference + title-source: frontmatter + - folder: ./resources + title: "Resources" + slug: resources + title-source: frontmatter diff --git a/docs/instrument-applications/about.md b/docs/instrument-applications/about.mdx similarity index 58% rename from docs/instrument-applications/about.md rename to docs/instrument-applications/about.mdx index da65adcf..bbe4569a 100644 --- a/docs/instrument-applications/about.md +++ b/docs/instrument-applications/about.mdx @@ -1,9 +1,10 @@ - - -# About +--- +title: "About" +description: "" +position: 1 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this section when you own an application, agent harness, or workflow and can route tool and LLM calls through NeMo Flow directly. @@ -23,17 +24,17 @@ Use this guide when you need to: - Wrap calls with timing, routing, retries, or fallback behavior - Isolate request-specific middleware and subscribers -If the tool or LLM boundary is owned by a framework, use [Integrate into Frameworks](../integrate-frameworks/about.md) instead. +If the tool or LLM boundary is owned by a framework, use [Integrate into Frameworks](/integrate-into-frameworks/about) instead. ## Guides These guides show how to instrument applications with scopes, tool calls, LLM calls, middleware, and direct API examples. -- [Adding Scopes and Marks](adding-scopes-and-marks.md) shows how to create ownership boundaries and checkpoint events before adding call instrumentation. -- [Instrument a Tool Call](instrument-tool-call.md) shows the smallest managed tool wrapper with event validation. -- [Instrument an LLM Call](instrument-llm-call.md) shows the smallest managed model-provider wrapper with event validation. -- [Add Middleware](advanced-guide.md) shows how to add guardrails, request intercepts, execution intercepts, and scope-local behavior. -- [Code Examples](code-examples.md) collects direct API examples for tools, LLMs, streaming calls, scopes, and partial middleware helpers. +- [Adding Scopes and Marks](/instrument-applications/adding-scopes-and-marks) shows how to create ownership boundaries and checkpoint events before adding call instrumentation. +- [Instrument a Tool Call](/instrument-applications/instrument-tool-call) shows the smallest managed tool wrapper with event validation. +- [Instrument an LLM Call](/instrument-applications/instrument-llm-call) shows the smallest managed model-provider wrapper with event validation. +- [Add Middleware](/instrument-applications/advanced-guide) shows how to add guardrails, request intercepts, execution intercepts, and scope-local behavior. +- [Code Examples](/instrument-applications/code-examples) collects direct API examples for tools, LLMs, streaming calls, scopes, and partial middleware helpers. Start with scopes and marks, then instrument the call boundaries your application owns. Add one middleware behavior at a time after the tool or LLM diff --git a/docs/instrument-applications/adding-scopes-and-marks.md b/docs/instrument-applications/adding-scopes-and-marks.mdx similarity index 86% rename from docs/instrument-applications/adding-scopes-and-marks.md rename to docs/instrument-applications/adding-scopes-and-marks.mdx index e0d964b0..27174b82 100644 --- a/docs/instrument-applications/adding-scopes-and-marks.md +++ b/docs/instrument-applications/adding-scopes-and-marks.mdx @@ -1,9 +1,10 @@ - - -# Adding Scopes and Marks +--- +title: "Adding Scopes and Marks" +description: "" +position: 2 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this guide when you want NeMo Flow to identify one agent run, request, workflow, or operation before you instrument individual tool and LLM calls. @@ -17,9 +18,9 @@ Scopes give emitted work ownership. Marks record point-in-time checkpoints insid Complete one binding Quick Start guide first: -- [Python Quick Start](../getting-started/python/index.md) -- [Node.js Quick Start](../getting-started/nodejs.md) -- [Rust Quick Start](../getting-started/rust.md) +- [Python Quick Start](/getting-started/quick-start/python) +- [Node.js Quick Start](/getting-started/quick-start/nodejs) +- [Rust Quick Start](/getting-started/quick-start/rust) You should know which application boundary should own the trace. Common scope boundaries include: @@ -44,20 +45,14 @@ Follow this sequence to keep framework work attached to the expected runtime con The examples below create one `agent-run` scope and emit two marks. -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" import nemo_flow - def log_event(event) -> None: print(f"{event.kind} {event.name}") - nemo_flow.subscribers.register("scope-check", log_event) try: @@ -71,12 +66,8 @@ try: finally: nemo_flow.subscribers.deregister("scope-check") ``` -::: - -:::{tab-item} Node.js -:sync: node -```js +```js title="Node.js" for="node" const { ScopeType, deregisterSubscriber, @@ -114,12 +105,8 @@ main().catch((error) => { process.exitCode = 1; }); ``` -::: - -:::{tab-item} Rust -:sync: rust -```rust +```rust title="Rust" for="rust" use nemo_flow::api::scope::{ self, EmitMarkEventParams, PopScopeParams, PushScopeParams, ScopeAttributes, ScopeType, }; @@ -164,9 +151,8 @@ fn main() -> Result<(), Box> { Ok(()) } ``` -::: -:::: + ## When to Add Marks @@ -206,6 +192,6 @@ Use this checklist before running the pattern in production traffic. Use these links to continue from this workflow into the next related task. -- Add tool instrumentation with [Instrument a Tool Call](instrument-tool-call.md). -- Add model-provider instrumentation with [Instrument an LLM Call](instrument-llm-call.md). -- Use [Code Examples](code-examples.md#scope-and-context-helpers) for explicit scope-stack propagation helpers. +- Add tool instrumentation with [Instrument a Tool Call](/instrument-applications/instrument-tool-call). +- Add model-provider instrumentation with [Instrument an LLM Call](/instrument-applications/instrument-llm-call). +- Use [Code Examples](/instrument-applications/code-examples#scope-and-context-helpers) for explicit scope-stack propagation helpers. diff --git a/docs/instrument-applications/advanced-guide.md b/docs/instrument-applications/advanced-guide.mdx similarity index 89% rename from docs/instrument-applications/advanced-guide.md rename to docs/instrument-applications/advanced-guide.mdx index a68cd111..91293c50 100644 --- a/docs/instrument-applications/advanced-guide.md +++ b/docs/instrument-applications/advanced-guide.mdx @@ -1,9 +1,10 @@ - - -# Add Middleware +--- +title: "Add Middleware" +description: "" +position: 5 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this guide when instrumentation is working and you want NeMo Flow to enforce policy, transform requests, wrap execution, or sanitize observability payloads around tool and LLM calls. @@ -18,7 +19,7 @@ You will add middleware to an instrumented application and verify that it runs i ## Before You Start -Complete [Instrument a Tool Call](instrument-tool-call.md) or [Instrument an LLM Call](instrument-llm-call.md). Middleware only runs when the call goes through a NeMo Flow managed lifecycle API. +Complete [Instrument a Tool Call](/instrument-applications/instrument-tool-call) or [Instrument an LLM Call](/instrument-applications/instrument-llm-call). Middleware only runs when the call goes through a NeMo Flow managed lifecycle API. ## Choose the Middleware Type @@ -42,31 +43,24 @@ This example adds three behaviors around a `search` tool: - Reject empty queries before execution. - Measure execution duration. -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" import time import nemo_flow - def redact_api_key(tool_name, args): safe_args = dict(args) if "api_key" in safe_args: safe_args["api_key"] = "" return safe_args - def require_query(tool_name, args): if not args.get("query"): return "search.query is required" return None - async def measure_tool(tool_name, args, next_call): started = time.perf_counter() try: @@ -75,17 +69,12 @@ async def measure_tool(tool_name, args, next_call): elapsed_ms = round((time.perf_counter() - started) * 1000, 2) print(f"{tool_name} completed in {elapsed_ms} ms") - nemo_flow.guardrails.register_tool_sanitize_request("search.redact_api_key", 10, redact_api_key) nemo_flow.guardrails.register_tool_conditional_execution("search.require_query", 20, require_query) nemo_flow.intercepts.register_tool_execution("search.measure", 30, measure_tool) ``` -::: -:::{tab-item} Node.js -:sync: node - -```js +```js title="Node.js" for="node" const { registerToolConditionalExecutionGuardrail, registerToolExecutionIntercept, @@ -112,12 +101,8 @@ registerToolExecutionIntercept("search.measure", 30, async (args, next) => { } }); ``` -::: - -:::{tab-item} Rust -:sync: rust -```rust +```rust title="Rust" for="rust" use nemo_flow::api::registry::{ register_tool_conditional_execution_guardrail, register_tool_execution_intercept, @@ -164,9 +149,8 @@ register_tool_execution_intercept( }), )?; ``` -::: -:::: + ## Scope Middleware to One Request @@ -230,6 +214,6 @@ Check these symptoms first when the workflow does not behave as expected. Use these links to continue from this workflow into the next related task. -- Use [Middleware](../about/concepts/middleware.md) to review execution order. -- Use [Code Examples](code-examples.md) for direct registration and partial-execution examples. -- Use [Handle Non-Serializable Data](../integrate-frameworks/non-serializable-data.md) if middleware needs to work with framework objects. +- Use [Middleware](/about-nemo-flow/concepts/middleware) to review execution order. +- Use [Code Examples](/instrument-applications/code-examples) for direct registration and partial-execution examples. +- Use [Handle Non-Serializable Data](/integrate-into-frameworks/non-serializable-data) if middleware needs to work with framework objects. diff --git a/docs/instrument-applications/code-examples.md b/docs/instrument-applications/code-examples.mdx similarity index 89% rename from docs/instrument-applications/code-examples.md rename to docs/instrument-applications/code-examples.mdx index 7b138b59..5996dc50 100644 --- a/docs/instrument-applications/code-examples.md +++ b/docs/instrument-applications/code-examples.mdx @@ -1,9 +1,10 @@ - - -# Code Examples +--- +title: "Code Examples" +description: "" +position: 6 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use these examples when you need the direct runtime surfaces behind the application instrumentation guides. @@ -26,13 +27,9 @@ Use manual lifecycle calls only when the surrounding code owns the real tool inv If you are replaying events or bridging a framework clock, pass an explicit timestamp to the manual start, end, or mark helpers. Python accepts timezone-aware `datetime` values, Node.js and WebAssembly accept Unix microseconds since epoch, Rust accepts `DateTime`, and Go accepts `time.Time`. -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" import nemo_flow handle = nemo_flow.tools.call("search", {"query": "weather"}, data={"attempt": 1}) @@ -41,24 +38,16 @@ try: finally: nemo_flow.tools.call_end(handle, result) ``` -::: - -:::{tab-item} Node.js -:sync: node -```ts +```ts title="Node.js" for="node" import { toolCall, toolCallEnd } from 'nemo-flow-node'; const handle = toolCall('search', { query: 'weather' }, null, null, { attempt: 1 }, null, null); const result = { hits: 2 }; toolCallEnd(handle, result, null, null); ``` -::: -:::{tab-item} Rust -:sync: rust - -```rust +```rust title="Rust" for="rust" use nemo_flow::api::tool::{tool_call, tool_call_end, ToolCallEndParams, ToolCallParams}; use serde_json::json; @@ -77,31 +66,24 @@ tool_call_end( .build(), )?; ``` -::: -:::: + ## Managed LLM Execution Use managed execution when NeMo Flow should run the full middleware pipeline around the provider call. -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" import nemo_flow from nemo_flow import LLMRequest request = LLMRequest({}, {"messages": [{"role": "user", "content": "hello"}]}) - async def invoke(req: LLMRequest): return {"text": "hi", "request": req.content} - response = await nemo_flow.llm.execute( "demo-provider", request, @@ -109,12 +91,8 @@ response = await nemo_flow.llm.execute( model_name="demo-model", ) ``` -::: - -:::{tab-item} Node.js -:sync: node -```ts +```ts title="Node.js" for="node" import { LlmRequest, llmCallExecute } from 'nemo-flow-node'; const request = new LlmRequest({}, { messages: [{ role: 'user', content: 'hello' }] }); @@ -130,12 +108,8 @@ const response = await llmCallExecute( 'demo-model', ); ``` -::: - -:::{tab-item} Rust -:sync: rust -```rust +```rust title="Rust" for="rust" use nemo_flow::api::llm::{llm_call_execute, LlmCallExecuteParams, LlmRequest}; use serde_json::json; use std::sync::Arc; @@ -156,45 +130,35 @@ let response = llm_call_execute( .build(), ).await?; ``` -::: -:::: + ## Streaming LLM Execution Use the streaming helper when subscribers need chunk collection plus one final response payload. -::::{tab-set} -:sync-group: language + -:::{tab-item} Python -:sync: python - -```python +```python title="Python" for="python" from dataclasses import dataclass from nemo_flow import LLMRequest from nemo_flow.typed import DataclassCodec, llm_stream_execute - @dataclass class Chunk: delta: str - @dataclass class FinalResponse: text: str - request = LLMRequest({}, {"messages": [{"role": "user", "content": "hello"}]}) collected: list[Chunk] = [] - async def stream_impl(_request: LLMRequest): yield Chunk(delta="hi") - stream = await llm_stream_execute( "demo-provider", request, @@ -205,12 +169,8 @@ stream = await llm_stream_execute( response_json_codec=DataclassCodec(FinalResponse), ) ``` -::: -:::{tab-item} Node.js -:sync: node - -```ts +```ts title="Node.js" for="node" import { LlmRequest } from 'nemo-flow-node'; import { typedLlmStreamExecute, type Codec } from 'nemo-flow-node/typed'; @@ -241,12 +201,8 @@ const stream = await typedLlmStreamExecute( responseCodec, ); ``` -::: - -:::{tab-item} Rust -:sync: rust -```rust +```rust title="Rust" for="rust" use nemo_flow::api::llm::{ llm_stream_call_execute, LlmAttributes, LlmRequest, LlmStreamCallExecuteParams, }; @@ -271,21 +227,16 @@ let stream = llm_stream_call_execute( .build(), ).await?; ``` -::: -:::: + ## Partial Middleware Calls These helpers are useful when framework code cannot use managed execution but still wants a request rewrite or block decision. -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" import nemo_flow from nemo_flow import LLMRequest @@ -296,12 +247,8 @@ llm_request = LLMRequest({}, {"messages": [{"role": "user", "content": "hello"}] llm_request = nemo_flow.llm.request_intercepts("demo-provider", llm_request) nemo_flow.llm.conditional_execution(llm_request) ``` -::: -:::{tab-item} Node.js -:sync: node - -```ts +```ts title="Node.js" for="node" import { LlmRequest, llmConditionalExecution, @@ -317,12 +264,8 @@ const request = new LlmRequest({}, { messages: [{ role: 'user', content: 'hello' const rewritten = await llmRequestIntercepts('demo-provider', request); await llmConditionalExecution(rewritten); ``` -::: - -:::{tab-item} Rust -:sync: rust -```rust +```rust title="Rust" for="rust" use nemo_flow::api::llm::{llm_conditional_execution, llm_request_intercepts, LlmRequest}; use nemo_flow::api::tool::{tool_conditional_execution, tool_request_intercepts}; use serde_json::json; @@ -337,21 +280,16 @@ let request = LlmRequest { let rewritten = llm_request_intercepts("demo-provider", request)?; llm_conditional_execution(&rewritten)?; ``` -::: -:::: + ## Scope and Context Helpers Use normal scope helpers first. Reach for explicit stack helpers only when work crosses thread, task, worker, or request boundaries. -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" from concurrent.futures import ThreadPoolExecutor import nemo_flow @@ -367,12 +305,8 @@ with nemo_flow.scope.scope("request", nemo_flow.ScopeType.Agent): with ThreadPoolExecutor() as pool: pool.submit(worker).result() ``` -::: -:::{tab-item} Node.js -:sync: node - -```ts +```ts title="Node.js" for="node" import { ScopeType, createScopeStack, event, setThreadScopeStack, withScope } from 'nemo-flow-node'; const workerStack = createScopeStack(); @@ -382,12 +316,8 @@ await withScope('request', ScopeType.Agent, async (handle) => { event('started', handle, { ok: true }, null); }); ``` -::: - -:::{tab-item} Rust -:sync: rust -```rust +```rust title="Rust" for="rust" use nemo_flow::api::runtime::{create_scope_stack, set_thread_scope_stack, TASK_SCOPE_STACK}; use nemo_flow::api::scope::{event, EmitMarkEventParams}; use serde_json::json; @@ -406,9 +336,8 @@ std::thread::spawn(move || { .join() .unwrap(); ``` -::: -:::: + ## Middleware Registration Families @@ -429,4 +358,4 @@ Every family also has a scope-local surface: `nemo_flow::api::registry`; subscriber scope registration under `nemo_flow::api::subscriber` -Use [Add Middleware](advanced-guide.md) for an end-to-end policy example and [API Reference](../reference/api/index.md) for symbol-level details. +Use [Add Middleware](/instrument-applications/advanced-guide) for an end-to-end policy example and [API Reference](/reference/api) for symbol-level details. diff --git a/docs/instrument-applications/instrument-llm-call.md b/docs/instrument-applications/instrument-llm-call.mdx similarity index 88% rename from docs/instrument-applications/instrument-llm-call.md rename to docs/instrument-applications/instrument-llm-call.mdx index 5129c69f..4ff9d991 100644 --- a/docs/instrument-applications/instrument-llm-call.md +++ b/docs/instrument-applications/instrument-llm-call.mdx @@ -1,9 +1,10 @@ - - -# Instrument an LLM Call +--- +title: "Instrument an LLM Call" +description: "" +position: 4 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this guide when you own the model-provider callback and want NeMo Flow to emit lifecycle events, apply LLM middleware, and preserve the active agent scope around the call. @@ -22,11 +23,11 @@ You will wrap one existing LLM provider invocation with the managed LLM executio Complete one binding Quick Start guide first: -- [Python Quick Start](../getting-started/python/index.md) -- [Node.js Quick Start](../getting-started/nodejs.md) -- [Rust Quick Start](../getting-started/rust.md) +- [Python Quick Start](/getting-started/quick-start/python) +- [Node.js Quick Start](/getting-started/quick-start/nodejs) +- [Rust Quick Start](/getting-started/quick-start/rust) -Create a scope for the active request or agent run before adding LLM instrumentation. If you have not done that yet, start with [Adding Scopes and Marks](adding-scopes-and-marks.md). +Create a scope for the active request or agent run before adding LLM instrumentation. If you have not done that yet, start with [Adding Scopes and Marks](/instrument-applications/adding-scopes-and-marks). The request and response payloads must be JSON-compatible. If your provider SDK uses clients, streams, callbacks, or other opaque objects, keep those objects in the provider callback and pass only a serializable request projection into NeMo Flow. @@ -46,29 +47,22 @@ Follow these steps to route the provider invocation through NeMo Flow: The examples below wrap a demo provider callback and print emitted events. -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" import asyncio import nemo_flow - def log_event(event) -> None: print(f"{event.kind} {event.name}") - async def call_provider(request: nemo_flow.LLMRequest): return { "text": "hello", "messages": request.content["messages"], } - async def main() -> None: nemo_flow.subscribers.register("llm-check", log_event) @@ -89,16 +83,10 @@ async def main() -> None: finally: nemo_flow.subscribers.deregister("llm-check") - asyncio.run(main()) ``` -::: - -:::{tab-item} Node.js -:sync: node - -```js +```js title="Node.js" for="node" const { LlmRequest, ScopeType, @@ -146,12 +134,7 @@ main().catch((error) => { }); ``` -::: - -:::{tab-item} Rust -:sync: rust - -```rust +```rust title="Rust" for="rust" use nemo_flow::api::llm::{llm_call_execute, LlmCallExecuteParams, LlmRequest}; use nemo_flow::api::scope::{ self, PopScopeParams, PushScopeParams, ScopeAttributes, ScopeType, @@ -207,9 +190,7 @@ async fn main() -> Result<(), Box> { } ``` -::: - -:::: + ## Validate the Integration @@ -248,7 +229,7 @@ Check these symptoms first when the workflow does not behave as expected. Use these links to continue from this workflow into the next related task. -- Instrument tools with [Instrument a Tool Call](instrument-tool-call.md). -- Add policy or transformation with [Add Middleware](advanced-guide.md). -- Use [Provider Codecs](../integrate-frameworks/provider-codecs.md) when middleware needs normalized LLM request and response data. -- Export events with [Observability](../plugins/observability/about.md). +- Instrument tools with [Instrument a Tool Call](/instrument-applications/instrument-tool-call). +- Add policy or transformation with [Add Middleware](/instrument-applications/advanced-guide). +- Use [Provider Codecs](/integrate-into-frameworks/provider-codecs) when middleware needs normalized LLM request and response data. +- Export events with [Observability](/observability-plugin/about). diff --git a/docs/instrument-applications/instrument-tool-call.md b/docs/instrument-applications/instrument-tool-call.mdx similarity index 84% rename from docs/instrument-applications/instrument-tool-call.md rename to docs/instrument-applications/instrument-tool-call.mdx index 76d286aa..7d78933a 100644 --- a/docs/instrument-applications/instrument-tool-call.md +++ b/docs/instrument-applications/instrument-tool-call.mdx @@ -1,9 +1,10 @@ - - -# Instrument a Tool Call +--- +title: "Instrument a Tool Call" +description: "" +position: 3 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this guide when you have an application tool callback and want NeMo Flow to emit lifecycle events, apply middleware, and preserve the active agent scope around the call. @@ -21,13 +22,13 @@ You will wrap one existing tool callback with the managed tool execution API. Th Complete one binding Quick Start guide first: -- [Python Quick Start](../getting-started/python/index.md) -- [Node.js Quick Start](../getting-started/nodejs.md) -- [Rust Quick Start](../getting-started/rust.md) +- [Python Quick Start](/getting-started/quick-start/python) +- [Node.js Quick Start](/getting-started/quick-start/nodejs) +- [Rust Quick Start](/getting-started/quick-start/rust) -Create a scope for the active request or agent run before adding tool instrumentation. If you have not done that yet, start with [Adding Scopes and Marks](adding-scopes-and-marks.md). +Create a scope for the active request or agent run before adding tool instrumentation. If you have not done that yet, start with [Adding Scopes and Marks](/instrument-applications/adding-scopes-and-marks). -The tool arguments and result must be JSON-compatible. If your framework passes clients, sockets, streams, callbacks, or other opaque objects, use [Handle Non-Serializable Data](../integrate-frameworks/non-serializable-data.md) before you instrument the callback. +The tool arguments and result must be JSON-compatible. If your framework passes clients, sockets, streams, callbacks, or other opaque objects, use [Handle Non-Serializable Data](/integrate-into-frameworks/non-serializable-data) before you instrument the callback. ## Integration Pattern @@ -44,29 +45,22 @@ Follow this sequence to keep framework work attached to the expected runtime con The examples below wrap a `search` callback and print emitted events. -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" import asyncio import nemo_flow - def log_event(event) -> None: print(f"{event.kind} {event.name}") - async def search(args): return { "query": args["query"], "hits": [{"title": "NeMo Flow"}], } - async def main() -> None: nemo_flow.subscribers.register("instrumentation-check", log_event) @@ -82,15 +76,10 @@ async def main() -> None: finally: nemo_flow.subscribers.deregister("instrumentation-check") - asyncio.run(main()) ``` -::: -:::{tab-item} Node.js -:sync: node - -```js +```js title="Node.js" for="node" const { ScopeType, deregisterSubscriber, @@ -131,12 +120,8 @@ main().catch((error) => { process.exitCode = 1; }); ``` -::: - -:::{tab-item} Rust -:sync: rust -```rust +```rust title="Rust" for="rust" use nemo_flow::api::scope::{ self, PopScopeParams, PushScopeParams, ScopeAttributes, ScopeType, }; @@ -187,9 +172,8 @@ async fn main() -> Result<(), Box> { Ok(()) } ``` -::: -:::: + ## Validate the Integration @@ -209,7 +193,7 @@ Use this checklist before running the pattern in production traffic. - Keep tool names stable. Subscribers and downstream exporters use names for filtering and dashboards. - Keep tool arguments and results JSON-compatible. -- Register temporary debugging subscribers only in development or test environments. +- Register temporary debugging subscribers only in dev or test environments. - Pass the parent scope handle when the tool is part of a larger agent, request, or workflow. - Use middleware names that describe ownership, such as `search.redact_args` or `retrieval.timeout`. @@ -226,7 +210,7 @@ Check these symptoms first when the workflow does not behave as expected. Use these links to continue from this workflow into the next related task. -- Add model-provider instrumentation with [Instrument an LLM Call](instrument-llm-call.md). -- Add policy or transformation with [Add Middleware](advanced-guide.md). -- Export events with [Observability](../plugins/observability/about.md). -- Use [Code Examples](code-examples.md) for manual lifecycle, streaming, scope, and partial middleware API examples. +- Add model-provider instrumentation with [Instrument an LLM Call](/instrument-applications/instrument-llm-call). +- Add policy or transformation with [Add Middleware](/instrument-applications/advanced-guide). +- Export events with [Observability](/observability-plugin/about). +- Use [Code Examples](/instrument-applications/code-examples) for manual lifecycle, streaming, scope, and partial middleware API examples. diff --git a/docs/integrate-frameworks/about.md b/docs/integrate-frameworks/about.mdx similarity index 56% rename from docs/integrate-frameworks/about.md rename to docs/integrate-frameworks/about.mdx index c131928b..3b5a0237 100644 --- a/docs/integrate-frameworks/about.md +++ b/docs/integrate-frameworks/about.mdx @@ -1,9 +1,10 @@ - - -# About +--- +title: "About" +description: "" +position: 1 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this section when an agent framework, orchestration layer, SDK, or provider adapter owns the tool and LLM call sites that need NeMo Flow instrumentation. @@ -28,26 +29,26 @@ Use these signals to decide whether this documentation path matches your current - Need to keep non-serializable framework objects outside NeMo Flow payloads - Are building or reviewing third-party integration patches -If you own the application call sites directly, use [Instrument Applications](../instrument-applications/about.md) first. +If you own the application call sites directly, use [Instrument Applications](/instrument-applications/about) first. If your application uses a maintained public integration such as LangChain, LangGraph, Deep Agents, or OpenClaw, start with -[Supported Integrations](../integrations/about.md). +[Supported Integrations](/supported-integrations/about). ## Guides Use these guide links to move from the overview into task-specific instructions. -- [Adding Scopes](adding-scopes.md) shows how framework request and run hooks become NeMo Flow ownership boundaries. -- [Wrap Tool Calls](wrap-tool-calls.md) explains where to place managed tool wrappers and tool lifecycle fallbacks. -- [Wrap LLM Calls](wrap-llm-calls.md) explains where to place managed provider wrappers, model names, streaming behavior, and LLM lifecycle fallbacks. -- [Handle Non-Serializable Data](non-serializable-data.md) shows how to keep clients, streams, callbacks, and SDK objects outside JSON payloads. -- [Using Codecs](using-codecs.md) explains typed value codecs for framework-facing wrappers. -- [Provider Codecs](provider-codecs.md) explains provider request and response codecs for normalized middleware and event annotations. -- [Provider Response Codecs](provider-response-codecs.md) focuses on response-only annotations for subscribers and exporters. -- [Code Examples](code-examples.md) collects fallback APIs, mark events, and repository patch workflow examples. +- [Adding Scopes](/integrate-into-frameworks/adding-scopes) shows how framework request and run hooks become NeMo Flow ownership boundaries. +- [Wrap Tool Calls](/integrate-into-frameworks/wrap-tool-calls) explains where to place managed tool wrappers and tool lifecycle fallbacks. +- [Wrap LLM Calls](/integrate-into-frameworks/wrap-llm-calls) explains where to place managed provider wrappers, model names, streaming behavior, and LLM lifecycle fallbacks. +- [Handle Non-Serializable Data](/integrate-into-frameworks/non-serializable-data) shows how to keep clients, streams, callbacks, and SDK objects outside JSON payloads. +- [Using Codecs](/integrate-into-frameworks/using-codecs) explains typed value codecs for framework-facing wrappers. +- [Provider Codecs](/integrate-into-frameworks/provider-codecs) explains provider request and response codecs for normalized middleware and event annotations. +- [Provider Response Codecs](/integrate-into-frameworks/provider-response-codecs) focuses on response-only annotations for subscribers and exporters. +- [Code Examples](/integrate-into-frameworks/code-examples) collects fallback APIs, mark events, and repository patch workflow examples. For coding-agent hook and LLM gateway observability, use -[NeMo Flow CLI](../nemo-flow-cli/about.md). That section covers Claude Code, +[NeMo Flow CLI](/nemo-flow-cli/about). That section covers Claude Code, Codex, Cursor, and Hermes Agent support. Start by identifying the framework's stable tool and LLM boundaries. Prefer diff --git a/docs/integrate-frameworks/adding-scopes.md b/docs/integrate-frameworks/adding-scopes.mdx similarity index 90% rename from docs/integrate-frameworks/adding-scopes.md rename to docs/integrate-frameworks/adding-scopes.mdx index 5254b429..823a25b5 100644 --- a/docs/integrate-frameworks/adding-scopes.md +++ b/docs/integrate-frameworks/adding-scopes.mdx @@ -1,9 +1,10 @@ - - -# Adding Scopes +--- +title: "Adding Scopes" +description: "" +position: 2 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this guide when a framework needs a durable NeMo Flow ownership boundary for one request, agent run, workflow, or framework task. @@ -40,16 +41,11 @@ The scope end hook should: - Include only safe summary output - Clear any framework request state used for handle lookup -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" import nemo_flow - def on_request_start(request_state, request_id: str) -> None: request_state.nemo_flow_scope = nemo_flow.scope.push( "framework-request", @@ -57,7 +53,6 @@ def on_request_start(request_state, request_id: str) -> None: input={"request_id": request_id}, ) - def on_request_end(request_state, status: str) -> None: handle = request_state.nemo_flow_scope try: @@ -65,12 +60,8 @@ def on_request_end(request_state, status: str) -> None: finally: request_state.nemo_flow_scope = None ``` -::: - -:::{tab-item} Node.js -:sync: node -```ts +```ts title="Node.js" for="node" import { popScope, pushScope, ScopeType, type ScopeHandle } from 'nemo-flow-node'; type RequestState = { @@ -102,12 +93,8 @@ export function onRequestEnd(state: RequestState, status: string): void { } } ``` -::: - -:::{tab-item} Rust -:sync: rust -```rust +```rust title="Rust" for="rust" use nemo_flow::api::scope::{ self, PopScopeParams, PushScopeParams, ScopeAttributes, ScopeHandle, ScopeType, }; @@ -142,9 +129,8 @@ fn on_request_end(state: &mut RequestState, status: &str) -> anyhow::Result<()> Ok(()) } ``` -::: -:::: + ## Attach Child Calls to the Scope @@ -188,6 +174,6 @@ Check these symptoms first when the workflow does not behave as expected. Use these links to continue from this workflow into the next related task. -- Wrap tools with [Wrap Tool Calls](wrap-tool-calls.md). -- Wrap model providers with [Wrap LLM Calls](wrap-llm-calls.md). -- Use [Code Examples](../instrument-applications/code-examples.md#scope-and-context-helpers) for explicit scope-stack propagation helpers. +- Wrap tools with [Wrap Tool Calls](/integrate-into-frameworks/wrap-tool-calls). +- Wrap model providers with [Wrap LLM Calls](/integrate-into-frameworks/wrap-llm-calls). +- Use [Code Examples](/instrument-applications/code-examples#scope-and-context-helpers) for explicit scope-stack propagation helpers. diff --git a/docs/integrate-frameworks/code-examples.md b/docs/integrate-frameworks/code-examples.mdx similarity index 85% rename from docs/integrate-frameworks/code-examples.md rename to docs/integrate-frameworks/code-examples.mdx index 9703c208..715f98c1 100644 --- a/docs/integrate-frameworks/code-examples.md +++ b/docs/integrate-frameworks/code-examples.mdx @@ -1,19 +1,20 @@ - - -# Code Examples +--- +title: "Code Examples" +description: "" +position: 9 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use these examples for implementation surfaces: -- [Adding Scopes](adding-scopes.md) -- [Wrap Tool Calls](wrap-tool-calls.md) -- [Wrap LLM Calls](wrap-llm-calls.md) -- [Non-Serializable Data](non-serializable-data.md) -- [Using Codecs](using-codecs.md) -- [Provider Codecs](provider-codecs.md) -- [Provider Response Codecs](provider-response-codecs.md) +- [Adding Scopes](/integrate-into-frameworks/adding-scopes) +- [Wrap Tool Calls](/integrate-into-frameworks/wrap-tool-calls) +- [Wrap LLM Calls](/integrate-into-frameworks/wrap-llm-calls) +- [Non-Serializable Data](/integrate-into-frameworks/non-serializable-data) +- [Using Codecs](/integrate-into-frameworks/using-codecs) +- [Provider Codecs](/integrate-into-frameworks/provider-codecs) +- [Provider Response Codecs](/integrate-into-frameworks/provider-response-codecs) ## Preferred Integration Order @@ -48,39 +49,27 @@ What you lose from managed execution wrappers: - Request intercepts and conditional execution must be invoked explicitly if you still need them. - Error paths need deliberate end-event or mark-event handling. -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" import nemo_flow from nemo_flow import LLMRequest - def framework_tool_started(name: str, args: dict): return nemo_flow.tools.call(name, args) - def framework_tool_finished(handle, result: dict) -> None: nemo_flow.tools.call_end(handle, result) - def framework_llm_started(provider: str, payload: dict): request = LLMRequest({}, payload) return nemo_flow.llm.call(provider, request, model_name=payload.get("model")) - def framework_llm_finished(handle, response: dict) -> None: nemo_flow.llm.call_end(handle, response) ``` -::: - -:::{tab-item} Node.js -:sync: node -```ts +```ts title="Node.js" for="node" import { LlmRequest, llmCall, llmCallEnd, toolCall, toolCallEnd } from 'nemo-flow-node'; export function frameworkToolStarted(name: string, args: unknown) { @@ -100,12 +89,8 @@ export function frameworkLlmFinished(handle: unknown, response: unknown): void { llmCallEnd(handle, response, null, null); } ``` -::: -:::{tab-item} Rust -:sync: rust - -```rust +```rust title="Rust" for="rust" use nemo_flow::api::llm::{llm_call, llm_call_end, LlmCallEndParams, LlmCallParams, LlmRequest}; use nemo_flow::api::tool::{tool_call, tool_call_end, ToolCallEndParams, ToolCallParams}; use serde_json::{json, Value as Json}; @@ -141,44 +126,31 @@ llm_call_end( .build(), )?; ``` -::: -:::: + ## Conditional Execution Use conditional-execution helpers when the framework needs an allow-or-block decision before it continues down its own invocation path. -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" import nemo_flow from nemo_flow import LLMRequest nemo_flow.tools.conditional_execution("search", {"query": "weather"}) nemo_flow.llm.conditional_execution(LLMRequest({}, {"messages": []})) ``` -::: -:::{tab-item} Node.js -:sync: node - -```ts +```ts title="Node.js" for="node" import { LlmRequest, llmConditionalExecution, toolConditionalExecution } from 'nemo-flow-node'; await toolConditionalExecution('search', { query: 'weather' }); await llmConditionalExecution(new LlmRequest({}, { messages: [] })); ``` -::: - -:::{tab-item} Rust -:sync: rust -```rust +```rust title="Rust" for="rust" use nemo_flow::api::llm::{llm_conditional_execution, LlmRequest}; use nemo_flow::api::tool::tool_conditional_execution; use serde_json::json; @@ -187,21 +159,16 @@ tool_conditional_execution("search", &json!({"query": "weather"}))?; let request = LlmRequest { headers: Default::default(), content: json!({"messages": []}) }; llm_conditional_execution(&request)?; ``` -::: -:::: + ## Request Intercepts Use request-intercept helpers when the framework wants NeMo Flow to rewrite arguments or provider requests before the framework invokes its own downstream code. -::::{tab-set} -:sync-group: language + -:::{tab-item} Python -:sync: python - -```python +```python title="Python" for="python" import nemo_flow from nemo_flow import LLMRequest @@ -211,23 +178,15 @@ rewritten_request = nemo_flow.llm.request_intercepts( LLMRequest({}, {"messages": []}), ) ``` -::: - -:::{tab-item} Node.js -:sync: node -```ts +```ts title="Node.js" for="node" import { LlmRequest, llmRequestIntercepts, toolRequestIntercepts } from 'nemo-flow-node'; const rewrittenArgs = await toolRequestIntercepts('search', { query: 'weather' }); const rewrittenRequest = await llmRequestIntercepts('demo-provider', new LlmRequest({}, { messages: [] })); ``` -::: -:::{tab-item} Rust -:sync: rust - -```rust +```rust title="Rust" for="rust" use nemo_flow::api::llm::{llm_request_intercepts, LlmRequest}; use nemo_flow::api::tool::tool_request_intercepts; use serde_json::json; @@ -236,41 +195,28 @@ let rewritten_args = tool_request_intercepts("search", json!({"query": "weather" let request = LlmRequest { headers: Default::default(), content: json!({"messages": []}) }; let rewritten_request = llm_request_intercepts("demo-provider", request)?; ``` -::: -:::: + ## Mark Events Use mark events when the framework exposes important milestones but not a full lifecycle boundary. -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" import nemo_flow nemo_flow.scope.event("scheduler.retry", data={"attempt": 2}) ``` -::: -:::{tab-item} Node.js -:sync: node - -```ts +```ts title="Node.js" for="node" import { event } from 'nemo-flow-node'; event('scheduler.retry', null, { attempt: 2 }, null); ``` -::: - -:::{tab-item} Rust -:sync: rust -```rust +```rust title="Rust" for="rust" use nemo_flow::api::scope::{event, EmitMarkEventParams}; use serde_json::json; @@ -281,16 +227,15 @@ event( .build(), )?; ``` -::: -:::: + ## Sample Third-Party Patch Integrations NeMo Flow keeps sample third-party integrations as patch sets under `patches/` and pinned upstream checkouts under `third_party/`. For the current OpenClaw end-user integration, use the -[OpenClaw Plugin Guide](../integrations/openclaw-plugin.md). +[OpenClaw Plugin Guide](/supported-integrations/openclaw-plugin). The following table lists maintained patch checkouts: @@ -314,7 +259,7 @@ NeMo Flow patches applied to the pinned third-party checkouts: | `./scripts/apply-patches.sh` | Apply NeMo Flow integration patches to third-party checkouts. | | `./scripts/apply-patches.sh --check` | Ensure the patches apply cleanly to all third-party checkouts. | | `./scripts/generate-patches.sh` | Regenerate patch files from local third-party checkout changes. | -| `./scripts/build-docs.sh` | Build the documentation site after integration docs change. | +| `./scripts/build-docs.sh` | Validate the Fern documentation site after integration docs change. | The dry run checks that patches apply cleanly before modifying the local checkouts. Use manual `git clone`, `git checkout`, and `git apply` commands only diff --git a/docs/integrate-frameworks/non-serializable-data.md b/docs/integrate-frameworks/non-serializable-data.mdx similarity index 86% rename from docs/integrate-frameworks/non-serializable-data.md rename to docs/integrate-frameworks/non-serializable-data.mdx index 76e745bf..52928e85 100644 --- a/docs/integrate-frameworks/non-serializable-data.md +++ b/docs/integrate-frameworks/non-serializable-data.mdx @@ -1,9 +1,10 @@ - - -# Handle Non-Serializable Data +--- +title: "Handle Non-Serializable Data" +description: "" +position: 5 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this guide when a framework exposes SDK clients, streams, callbacks, file handles, or custom classes at the same boundary where you need NeMo Flow instrumentation. @@ -37,49 +38,36 @@ Flow. Keep framework objects in your own map, but send only the JSON projection through NeMo Flow. -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" from typing import TypedDict import nemo_flow - class SearchArgs(TypedDict): client_id: str query: str - class SearchResult(TypedDict): hits: int - framework_clients: dict[str, object] = {} framework_clients["client-1"] = object() - async def invoke(args: SearchArgs) -> SearchResult: client = framework_clients[args["client_id"]] _ = client # framework-owned object stays outside NeMo Flow payloads return {"hits": 2} - result = await nemo_flow.tools.execute( "search", SearchArgs(client_id="client-1", query="weather"), invoke, ) ``` -::: - -:::{tab-item} Node.js -:sync: node -```ts +```ts title="Node.js" for="node" import { toolCallExecute } from 'nemo-flow-node'; type SearchArgs = { clientId: string; query: string }; @@ -100,12 +88,8 @@ const result = await toolCallExecute( }, ) as SearchResult; ``` -::: -:::{tab-item} Rust -:sync: rust - -```rust +```rust title="Rust" for="rust" use nemo_flow::api::tool::{ToolCallExecuteParams, tool_call_execute}; use serde_json::json; use std::collections::HashMap; @@ -141,8 +125,8 @@ let result = tool_call_execute( .build(), ).await?; ``` -::: -:::: + + ## Codec Pattern For Provider Payloads @@ -196,7 +180,7 @@ contract. Use these links to continue from this workflow into the next related task. -- Wrap the framework boundary with [Wrap Tool Calls](wrap-tool-calls.md) or [Wrap LLM Calls](wrap-llm-calls.md). -- Use [Provider Codecs](provider-codecs.md) when provider payloads need normalized request or response annotations. -- Use the typed value codec examples in [Using Codecs](using-codecs.md#typed-value-codecs) for structured conversion helpers. -- Use [Add Middleware](../instrument-applications/advanced-guide.md) before adding request transforms. +- Wrap the framework boundary with [Wrap Tool Calls](/integrate-into-frameworks/wrap-tool-calls) or [Wrap LLM Calls](/integrate-into-frameworks/wrap-llm-calls). +- Use [Provider Codecs](/integrate-into-frameworks/provider-codecs) when provider payloads need normalized request or response annotations. +- Use the typed value codec examples in [Using Codecs](/integrate-into-frameworks/using-codecs#typed-value-codecs) for structured conversion helpers. +- Use [Add Middleware](/instrument-applications/advanced-guide) before adding request transforms. diff --git a/docs/integrate-frameworks/provider-codecs.md b/docs/integrate-frameworks/provider-codecs.mdx similarity index 91% rename from docs/integrate-frameworks/provider-codecs.md rename to docs/integrate-frameworks/provider-codecs.mdx index b1ebc31f..754ced9b 100644 --- a/docs/integrate-frameworks/provider-codecs.md +++ b/docs/integrate-frameworks/provider-codecs.mdx @@ -1,9 +1,10 @@ - - -# Provider Codecs +--- +title: "Provider Codecs" +description: "" +position: 7 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this guide when a framework integration needs NeMo Flow middleware, intercepts, or subscribers to reason about provider-specific LLM payloads through a stable annotated shape. @@ -31,7 +32,7 @@ A provider codec is a pure data translator at the NeMo Flow LLM boundary. - An LLM request codec converts a raw provider request into a normalized annotated request, then encodes any annotated edits back into the original provider request. - An LLM response codec converts a raw provider response into a normalized response annotation for lifecycle events. -Provider codecs let framework code keep using provider-native payloads while NeMo Flow middleware works against a shared annotated model. For application-facing type conversion, use [Using Codecs](using-codecs.md). +Provider codecs let framework code keep using provider-native payloads while NeMo Flow middleware works against a shared annotated model. For application-facing type conversion, use [Using Codecs](/integrate-into-frameworks/using-codecs). ## How Provider Codecs Work @@ -43,7 +44,7 @@ When a managed LLM call has a request codec: 4. NeMo Flow calls `encode` to merge the annotated request back into the original raw request. 5. Execution intercepts and the provider callback receive the encoded provider request. -When a managed LLM call has a response codec, NeMo Flow decodes the raw provider response for observability and attaches the result to the emitted LLM end event. The response codec does not rewrite the value returned to the application. Use [Provider Response Codecs](provider-response-codecs.md) for response-only behavior and custom response codec examples. +When a managed LLM call has a response codec, NeMo Flow decodes the raw provider response for observability and attaches the result to the emitted LLM end event. The response codec does not rewrite the value returned to the application. Use [Provider Response Codecs](/integrate-into-frameworks/provider-response-codecs) for response-only behavior and custom response codec examples. Codec implementations should preserve fields they do not understand. Treat `encode` as a merge operation over the original provider payload, not as a full replacement. @@ -76,18 +77,13 @@ Choose the provider codec that matches the payload shape the framework already s This example uses a request intercept to edit the normalized request. The codec writes the edited messages back into the provider payload before the provider callback runs. -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" import nemo_flow from nemo_flow import LLMRequest from nemo_flow.codecs import OpenAIChatCodec - def add_system_message(_name, request, annotated): if annotated is None: return request, annotated @@ -98,7 +94,6 @@ def add_system_message(_name, request, annotated): ] return request, annotated - nemo_flow.intercepts.register_llm_request( "framework.add_system_message", 10, @@ -106,7 +101,6 @@ nemo_flow.intercepts.register_llm_request( add_system_message, ) - async def invoke_provider(request: LLMRequest): return { "id": "chatcmpl-demo", @@ -116,7 +110,6 @@ async def invoke_provider(request: LLMRequest): ], } - codec = OpenAIChatCodec() request = LLMRequest( {}, @@ -136,12 +129,8 @@ response = await nemo_flow.llm.execute( response_codec=codec, ) ``` -::: -:::{tab-item} Node.js -:sync: node - -```ts +```ts title="Node.js" for="node" import { OpenAIChatCodec, registerLlmRequestIntercept, @@ -201,12 +190,8 @@ const response = await typedLlmExecute( }, ); ``` -::: - -:::{tab-item} Rust -:sync: rust -```rust +```rust title="Rust" for="rust" use nemo_flow::api::llm::{llm_call_execute, LlmCallExecuteParams, LlmRequest}; use nemo_flow::codec::openai_chat::OpenAIChatCodec; use nemo_flow::codec::traits::{LlmCodec, LlmResponseCodec}; @@ -248,25 +233,19 @@ let response = llm_call_execute( ) .await?; ``` -::: -:::: + ## Example: Write a Custom Framework Codec Use a custom codec when a framework uses a payload shape that does not directly match a built-in provider format. The codec decodes the framework shape into `AnnotatedLLMRequest`, and encodes edits back into the framework shape. -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" from nemo_flow import AnnotatedLLMRequest, LLMRequest from nemo_flow.codecs import LlmCodec - class FrameworkChatCodec(LlmCodec): def decode(self, request: LLMRequest) -> AnnotatedLLMRequest: content = request.content @@ -295,12 +274,8 @@ class FrameworkChatCodec(LlmCodec): content["tool_specs"] = annotated.tools return LLMRequest(original.headers, content) ``` -::: - -:::{tab-item} Node.js -:sync: node -```ts +```ts title="Node.js" for="node" import type { JsonValue, LlmCodec } from 'nemo-flow-node/typed'; type FrameworkRequest = { @@ -366,9 +341,8 @@ const frameworkChatCodec: LlmCodec = { }, }; ``` -::: -:::: + ## Validation Checklist @@ -385,7 +359,7 @@ contract. Use these links to continue from this workflow into the next related task. -- Use [Using Codecs](using-codecs.md) for typed value codecs. -- Use [Provider Response Codecs](provider-response-codecs.md) for response-only annotations and subscriber examples. -- Use [Add Middleware](../instrument-applications/advanced-guide.md) before adding request transforms. -- Use [Handle Non-Serializable Data](non-serializable-data.md) when the framework boundary includes SDK objects or streams that cannot pass through JSON payloads. +- Use [Using Codecs](/integrate-into-frameworks/using-codecs) for typed value codecs. +- Use [Provider Response Codecs](/integrate-into-frameworks/provider-response-codecs) for response-only annotations and subscriber examples. +- Use [Add Middleware](/instrument-applications/advanced-guide) before adding request transforms. +- Use [Handle Non-Serializable Data](/integrate-into-frameworks/non-serializable-data) when the framework boundary includes SDK objects or streams that cannot pass through JSON payloads. diff --git a/docs/integrate-frameworks/provider-response-codecs.md b/docs/integrate-frameworks/provider-response-codecs.mdx similarity index 92% rename from docs/integrate-frameworks/provider-response-codecs.md rename to docs/integrate-frameworks/provider-response-codecs.mdx index 81d865ae..7a86fb18 100644 --- a/docs/integrate-frameworks/provider-response-codecs.md +++ b/docs/integrate-frameworks/provider-response-codecs.mdx @@ -1,9 +1,10 @@ - - -# Provider Response Codecs +--- +title: "Provider Response Codecs" +description: "" +position: 8 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this guide when subscribers, exporters, or diagnostics need a provider-neutral view of raw LLM responses. @@ -22,7 +23,7 @@ Response codecs are observability-only: You need: -- A managed LLM boundary from [Wrap LLM Calls](wrap-llm-calls.md). +- A managed LLM boundary from [Wrap LLM Calls](/integrate-into-frameworks/wrap-llm-calls). - A raw provider response that is JSON-compatible. - A built-in response codec or a custom response codec for the provider response shape. - A subscriber or exporter that consumes `annotated_response` from LLM end events. @@ -59,18 +60,13 @@ Choose the codec that matches the actual provider response shape. For example, d The examples below attach built-in response codecs for supported provider response shapes. -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" import nemo_flow from nemo_flow import LLMRequest from nemo_flow.codecs import OpenAIChatCodec - async def invoke_provider(request: LLMRequest): return { "id": "chatcmpl-demo", @@ -84,7 +80,6 @@ async def invoke_provider(request: LLMRequest): "usage": {"prompt_tokens": 8, "completion_tokens": 5, "total_tokens": 13}, } - codec = OpenAIChatCodec() response = await nemo_flow.llm.execute( "openai-chat", @@ -94,12 +89,8 @@ response = await nemo_flow.llm.execute( response_codec=codec, ) ``` -::: - -:::{tab-item} Node.js -:sync: node -```ts +```ts title="Node.js" for="node" import { OpenAIChatCodec } from 'nemo-flow-node'; import { JsonPassthrough, typedLlmExecute } from 'nemo-flow-node/typed'; @@ -126,12 +117,8 @@ const response = await typedLlmExecute( }, ); ``` -::: - -:::{tab-item} Rust -:sync: rust -```rust +```rust title="Rust" for="rust" use nemo_flow::api::llm::{llm_call_execute, LlmCallExecuteParams, LlmRequest}; use nemo_flow::codec::openai_chat::OpenAIChatCodec; use nemo_flow::codec::traits::LlmResponseCodec; @@ -172,24 +159,18 @@ let response = llm_call_execute( ) .await?; ``` -::: -:::: + ## Read Annotated Responses Subscribers can inspect `annotated_response` on LLM end events. The exact event category fields are binding-provided, so defensive checks should confirm the annotation exists before reading it. -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" import nemo_flow - def on_event(event): annotated = getattr(event, "annotated_response", None) if annotated is None: @@ -199,15 +180,10 @@ def on_event(event): print("text", annotated.response_text()) print("usage", annotated.usage) - nemo_flow.subscribers.register("response-debugger", on_event) ``` -::: - -:::{tab-item} Node.js -:sync: node -```ts +```ts title="Node.js" for="node" import { registerSubscriber } from 'nemo-flow-node'; registerSubscriber('response-debugger', (event) => { @@ -221,9 +197,8 @@ registerSubscriber('response-debugger', (event) => { console.log('usage', annotated.usage); }); ``` -::: -:::: + ## Custom Response Codecs @@ -234,7 +209,6 @@ In Python, a custom response codec can route to built-in codecs and return their ```python from nemo_flow.codecs import OpenAIChatCodec, OpenAIResponsesCodec - class OpenAIRoutingResponseCodec: def __init__(self): self.chat = OpenAIChatCodec() @@ -362,6 +336,6 @@ Check these symptoms first when the workflow does not behave as expected. Use these links to continue from this workflow into the next related task. -- Use [Provider Codecs](provider-codecs.md) for request-side provider codecs and full request/response examples. -- Use [Wrap LLM Calls](wrap-llm-calls.md) to add the managed LLM boundary first. -- Use [Observability](../plugins/observability/about.md) after annotations are visible in local subscribers. +- Use [Provider Codecs](/integrate-into-frameworks/provider-codecs) for request-side provider codecs and full request/response examples. +- Use [Wrap LLM Calls](/integrate-into-frameworks/wrap-llm-calls) to add the managed LLM boundary first. +- Use [Observability](/observability-plugin/about) after annotations are visible in local subscribers. diff --git a/docs/integrate-frameworks/using-codecs.md b/docs/integrate-frameworks/using-codecs.mdx similarity index 82% rename from docs/integrate-frameworks/using-codecs.md rename to docs/integrate-frameworks/using-codecs.mdx index df30adb2..09098aea 100644 --- a/docs/integrate-frameworks/using-codecs.md +++ b/docs/integrate-frameworks/using-codecs.mdx @@ -1,9 +1,10 @@ - - -# Using Codecs +--- +title: "Using Codecs" +description: "" +position: 6 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this guide when a framework integration needs typed application values at its public boundary while NeMo Flow still records JSON-compatible payloads. @@ -16,7 +17,7 @@ You will choose typed value codecs for framework-facing wrappers so that: - Middleware and subscribers receive predictable serialized values - The framework callback still receives the application type it expects -For provider-native LLM payload normalization, use [Provider Codecs](provider-codecs.md). +For provider-native LLM payload normalization, use [Provider Codecs](/integrate-into-frameworks/provider-codecs). ## Before You Start @@ -38,7 +39,7 @@ Typed value codecs are different from provider codecs: | Typed value codec | Converts application values to and from JSON. | Dataclasses, Pydantic models, TypeScript object shapes, custom framework types. | | Provider codec | Converts provider-specific LLM requests and responses to annotated NeMo Flow request or response data. | OpenAI Chat, OpenAI Responses, Anthropic Messages, custom provider payloads. | -Use this page for typed value codecs. Use [Provider Codecs](provider-codecs.md) when middleware needs normalized LLM messages, tools, model names, generation parameters, or provider response annotations. +Use this page for typed value codecs. Use [Provider Codecs](/integrate-into-frameworks/provider-codecs) when middleware needs normalized LLM messages, tools, model names, generation parameters, or provider response annotations. ## How Typed Value Codecs Work @@ -62,39 +63,28 @@ Python exposes: Node.js exposes `JsonPassthrough` and custom `Codec` implementations. -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" from dataclasses import dataclass from pydantic import BaseModel from nemo_flow.typed import DataclassCodec, JsonPassthrough, PydanticCodec - @dataclass class SearchArgs: query: str - class SearchResult(BaseModel): hits: int - args_codec = DataclassCodec(SearchArgs) result_codec = PydanticCodec(SearchResult) passthrough = JsonPassthrough() ``` -::: - -:::{tab-item} Node.js -:sync: node -```ts +```ts title="Node.js" for="node" import { JsonPassthrough, type Codec, type JsonValue } from 'nemo-flow-node/typed'; type SearchArgs = { query: string }; @@ -106,9 +96,8 @@ const argsCodec: Codec = { const passthrough = new JsonPassthrough(); ``` -::: -:::: + Use `BestEffortAnyCodec` only at boundary code where strict schemas are unavailable. Prefer dataclass, Pydantic, or explicit Node.js codecs when the framework owns a stable schema. @@ -116,28 +105,21 @@ Use `BestEffortAnyCodec` only at boundary code where strict schemas are unavaila Use typed value codecs when the framework wants native objects but NeMo Flow should emit JSON payloads. -::::{tab-set} -:sync-group: language + -:::{tab-item} Python -:sync: python - -```python +```python title="Python" for="python" from dataclasses import dataclass import nemo_flow from nemo_flow.typed import DataclassCodec, JsonPassthrough, tool_execute - @dataclass class SearchArgs: query: str - async def invoke(args: SearchArgs) -> dict[str, str]: return {"echo": args.query} - result = await tool_execute( "search", SearchArgs("weather"), @@ -146,12 +128,8 @@ result = await tool_execute( result_codec=JsonPassthrough(), ) ``` -::: - -:::{tab-item} Node.js -:sync: node -```ts +```ts title="Node.js" for="node" import { JsonPassthrough, typedToolExecute, type Codec, type JsonValue } from 'nemo-flow-node/typed'; type SearchArgs = { query: string }; @@ -170,9 +148,8 @@ const result = await typedToolExecute( new JsonPassthrough(), ); ``` -::: -:::: + ## Validation Checklist @@ -189,6 +166,6 @@ contract. Use these links to continue from this workflow into the next related task. -- Use [Provider Codecs](provider-codecs.md) when provider payloads need normalized request or response annotations. -- Use [Handle Non-Serializable Data](non-serializable-data.md) when framework objects cannot pass through JSON payloads. -- Use [Integrate into Frameworks Code Examples](code-examples.md) for explicit fallback APIs. +- Use [Provider Codecs](/integrate-into-frameworks/provider-codecs) when provider payloads need normalized request or response annotations. +- Use [Handle Non-Serializable Data](/integrate-into-frameworks/non-serializable-data) when framework objects cannot pass through JSON payloads. +- Use [Integrate into Frameworks Code Examples](/integrate-into-frameworks/code-examples) for explicit fallback APIs. diff --git a/docs/integrate-frameworks/wrap-llm-calls.md b/docs/integrate-frameworks/wrap-llm-calls.mdx similarity index 86% rename from docs/integrate-frameworks/wrap-llm-calls.md rename to docs/integrate-frameworks/wrap-llm-calls.mdx index 86b327a4..8f512a92 100644 --- a/docs/integrate-frameworks/wrap-llm-calls.md +++ b/docs/integrate-frameworks/wrap-llm-calls.mdx @@ -1,9 +1,10 @@ - - -# Wrap LLM Calls +--- +title: "Wrap LLM Calls" +description: "" +position: 4 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this guide when a framework, SDK, or provider adapter owns model invocation and you need NeMo Flow to observe and control those provider calls. @@ -15,7 +16,7 @@ You will place a managed NeMo Flow LLM execution wrapper at the provider boundar You need: -- A framework request or run scope. If the framework does not create one yet, start with [Adding Scopes](adding-scopes.md). +- A framework request or run scope. If the framework does not create one yet, start with [Adding Scopes](/integrate-into-frameworks/adding-scopes). - A stable model-provider boundary, such as a provider adapter or client dispatch method. - A JSON-compatible request projection inside `LLMRequest`. - A JSON-compatible response projection for subscribers and exporters. @@ -30,30 +31,24 @@ Follow this sequence to keep framework work attached to the expected runtime con 4. Pass a stable provider name and `model_name`. 5. Keep provider clients, streams, callbacks, and retry state outside emitted JSON payloads. -Use a request or response codec when provider payloads need normalization before middleware or events see them. Use [Provider Codecs](provider-codecs.md) for those cases. +Use a request or response codec when provider payloads need normalization before middleware or events see them. Use [Provider Codecs](/integrate-into-frameworks/provider-codecs) for those cases. ## Concrete LLM Example The examples below wrap one provider call and attach it to the active parent scope. -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" from typing import TypedDict import nemo_flow from nemo_flow import LLMRequest - class LlmResponse(TypedDict): text: str request: object - async def framework_llm(provider_name: str, payload: object) -> LlmResponse: parent = nemo_flow.scope.get_handle() request = LLMRequest({}, payload) @@ -69,12 +64,8 @@ async def framework_llm(provider_name: str, payload: object) -> LlmResponse: model_name="demo-model", ) ``` -::: - -:::{tab-item} Node.js -:sync: node -```ts +```ts title="Node.js" for="node" import { getHandle, LlmRequest, llmCallExecute, type ScopeHandle } from 'nemo-flow-node'; type LlmResponse = { text: string; request: unknown }; @@ -95,12 +86,8 @@ export async function frameworkLlm(providerName: string, payload: unknown): Prom ) as Promise; } ``` -::: - -:::{tab-item} Rust -:sync: rust -```rust +```rust title="Rust" for="rust" use nemo_flow::api::llm::{llm_call_execute, LlmCallExecuteParams, LlmRequest}; use nemo_flow::api::scope::get_handle; use serde_json::json; @@ -129,9 +116,8 @@ async fn run_provider_call() -> anyhow::Result { Ok(response) } ``` -::: -:::: + ## Streaming Providers @@ -162,6 +148,6 @@ Check these symptoms first when the workflow does not behave as expected. Use these links to continue from this workflow into the next related task. -- Add tool integration with [Wrap Tool Calls](wrap-tool-calls.md). -- Normalize provider payloads with [Provider Codecs](provider-codecs.md). -- Use [Handle Non-Serializable Data](non-serializable-data.md) for provider clients, streams, and callback objects. +- Add tool integration with [Wrap Tool Calls](/integrate-into-frameworks/wrap-tool-calls). +- Normalize provider payloads with [Provider Codecs](/integrate-into-frameworks/provider-codecs). +- Use [Handle Non-Serializable Data](/integrate-into-frameworks/non-serializable-data) for provider clients, streams, and callback objects. diff --git a/docs/integrate-frameworks/wrap-tool-calls.md b/docs/integrate-frameworks/wrap-tool-calls.mdx similarity index 85% rename from docs/integrate-frameworks/wrap-tool-calls.md rename to docs/integrate-frameworks/wrap-tool-calls.mdx index a1264077..c9dca59c 100644 --- a/docs/integrate-frameworks/wrap-tool-calls.md +++ b/docs/integrate-frameworks/wrap-tool-calls.mdx @@ -1,9 +1,10 @@ - - -# Wrap Tool Calls +--- +title: "Wrap Tool Calls" +description: "" +position: 3 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this guide when a framework, SDK, or orchestration layer owns tool invocation and you need NeMo Flow to observe and control those calls without changing the framework's public behavior. @@ -15,7 +16,7 @@ You will place a managed NeMo Flow tool execution wrapper at the framework's sta You need: -- A framework request or run scope. If the framework does not create one yet, start with [Adding Scopes](adding-scopes.md). +- A framework request or run scope. If the framework does not create one yet, start with [Adding Scopes](/integrate-into-frameworks/adding-scopes). - A stable tool invocation boundary, such as a callback dispatcher, tool registry, or tool adapter. - A JSON-compatible projection of tool arguments and results. - A subscriber or exporter that can verify emitted tool events. @@ -36,27 +37,20 @@ Managed wrappers are the first choice because NeMo Flow owns the full call bound The examples below wrap one framework tool callback and attach it to the active parent scope. -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" from typing import TypedDict import nemo_flow - class SearchArgs(TypedDict): query: str - class SearchResult(TypedDict): hits: int echo: SearchArgs - async def framework_tool(tool_name: str, raw_args: SearchArgs) -> SearchResult: parent = nemo_flow.scope.get_handle() @@ -70,12 +64,8 @@ async def framework_tool(tool_name: str, raw_args: SearchArgs) -> SearchResult: handle=parent, ) ``` -::: - -:::{tab-item} Node.js -:sync: node -```ts +```ts title="Node.js" for="node" import { getHandle, toolCallExecute, type ScopeHandle } from 'nemo-flow-node'; type SearchArgs = { query: string }; @@ -95,12 +85,8 @@ export async function frameworkTool(toolName: string, rawArgs: SearchArgs): Prom ) as Promise; } ``` -::: - -:::{tab-item} Rust -:sync: rust -```rust +```rust title="Rust" for="rust" use nemo_flow::api::scope::get_handle; use nemo_flow::api::tool::{tool_call_execute, ToolCallExecuteParams}; use serde_json::json; @@ -125,15 +111,14 @@ async fn run_framework_tool() -> anyhow::Result { Ok(result) } ``` -::: -:::: + ## When to Use Fallback APIs Use explicit lifecycle APIs only when the framework owns the real tool invocation internally and exposes only start and finish hooks. In that case, the integration must preserve the returned handle and call the matching end helper on every success and failure path. -Use standalone request-intercept or conditional-execution helpers when the framework needs only partial middleware behavior before it continues down its own invocation path. See [Code Examples](code-examples.md#fallback-explicit-api-calls) for those fallback surfaces. +Use standalone request-intercept or conditional-execution helpers when the framework needs only partial middleware behavior before it continues down its own invocation path. See [Code Examples](/integrate-into-frameworks/code-examples#fallback-explicit-api-calls) for those fallback surfaces. ## Validate the Tool Wrapper @@ -158,6 +143,6 @@ Check these symptoms first when the workflow does not behave as expected. Use these links to continue from this workflow into the next related task. -- Add model-provider integration with [Wrap LLM Calls](wrap-llm-calls.md). -- Add request ownership with [Adding Scopes](adding-scopes.md). -- Use [Handle Non-Serializable Data](non-serializable-data.md) when framework objects need ID-based lookup. +- Add model-provider integration with [Wrap LLM Calls](/integrate-into-frameworks/wrap-llm-calls). +- Add request ownership with [Adding Scopes](/integrate-into-frameworks/adding-scopes). +- Use [Handle Non-Serializable Data](/integrate-into-frameworks/non-serializable-data) when framework objects need ID-based lookup. diff --git a/docs/integrations/about.md b/docs/integrations/about.mdx similarity index 68% rename from docs/integrations/about.md rename to docs/integrations/about.mdx index dc615cd6..11d5fc7d 100644 --- a/docs/integrations/about.md +++ b/docs/integrations/about.mdx @@ -1,9 +1,10 @@ - - -# About +--- +title: "About" +description: "" +position: 1 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this section when your application already uses a supported framework or agent harness and you want the maintained NeMo Flow integration path for that @@ -27,16 +28,16 @@ security middleware, and adaptive optimization. Use these guide links to move from the support matrix into setup and usage instructions. -- [OpenClaw Plugin Guide](openclaw-plugin.md) covers configuring the OpenClaw +- [OpenClaw Plugin Guide](/supported-integrations/openclaw-plugin) covers configuring the OpenClaw plugin, mapping OpenClaw hooks to NeMo Flow telemetry, and understanding current LLM replay fidelity boundaries. -- [LangChain Integration Guide](langchain.md) covers installing the LangChain +- [LangChain Integration Guide](/supported-integrations/langchain) covers installing the LangChain extra and adding NeMo Flow middleware and callbacks to LangChain agents. -- [LangGraph Integration Guide](langgraph.md) covers installing the LangGraph +- [LangGraph Integration Guide](/supported-integrations/langgraph) covers installing the LangGraph extra and adding NeMo Flow callbacks to LangGraph workflows. -- [Deep Agents Integration Guide](deepagents.md) covers installing the Deep +- [Deep Agents Integration Guide](/supported-integrations/deepagents) covers installing the Deep Agents extra and capturing Deep Agents-specific marks, skills, subagents, and human-in-the-loop lifecycle events. If you are building a new framework integration or patching framework internals, -use [Integrate into Frameworks](../integrate-frameworks/about.md) instead. +use [Integrate into Frameworks](/integrate-into-frameworks/about) instead. diff --git a/docs/integrations/deepagents.md b/docs/integrations/deepagents.mdx similarity index 81% rename from docs/integrations/deepagents.md rename to docs/integrations/deepagents.mdx index 9fd34f75..643e4729 100644 --- a/docs/integrations/deepagents.md +++ b/docs/integrations/deepagents.mdx @@ -1,9 +1,11 @@ - - -# NeMo Flow Deep Agents Integration +--- +title: "NeMo Flow Deep Agents Integration" +sidebar-title: "Deep Agents Integration Guide" +description: "" +position: 5 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use the `nemo_flow.integrations.deepagents` package to add NeMo Flow observability to Deep Agents applications through the LangChain and LangGraph @@ -13,52 +15,32 @@ integration surfaces that Deep Agents builds on. Install the Deep Agents integration extra in your application environment. -::::{tab-set} -:sync-group: install-tool - -:::{tab-item} uv -:selected: -:sync: uv + -```bash +```bash title="uv" for="uv" uv add "nemo-flow[deepagents]" ``` -::: - -:::{tab-item} pip -:sync: pip -```bash +```bash title="pip" for="pip" pip install "nemo-flow[deepagents]" ``` -::: -:::: + The example below uses the NVIDIA LangChain provider. Install that provider extra too if you want to run the example as written: -::::{tab-set} -:sync-group: install-tool + -:::{tab-item} uv -:selected: -:sync: uv - -```bash +```bash title="uv" for="uv" uv add "nemo-flow[deepagents,langchain-nvidia]" ``` -::: - -:::{tab-item} pip -:sync: pip -```bash +```bash title="pip" for="pip" pip install "nemo-flow[deepagents,langchain-nvidia]" ``` -::: -:::: + ## Usage Example @@ -116,5 +98,5 @@ It captures: Remote graphs or processes still need NeMo Flow instrumentation in that graph or process to capture their internal model and tool calls. -Refer to [Observability](../plugins/observability/about.md) +Refer to [Observability](/observability-plugin/about) for details on exporting NeMo Flow observability data to third-party systems. diff --git a/docs/integrations/langchain.md b/docs/integrations/langchain.mdx similarity index 73% rename from docs/integrations/langchain.md rename to docs/integrations/langchain.mdx index b8437ed2..c16c4ed8 100644 --- a/docs/integrations/langchain.md +++ b/docs/integrations/langchain.mdx @@ -1,9 +1,11 @@ - - -# NeMo Flow LangChain Integration +--- +title: "NeMo Flow LangChain Integration" +sidebar-title: "LangChain Integration Guide" +description: "" +position: 3 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use the `nemo_flow.integrations.langchain` package to add NeMo Flow observability to [LangChain](https://www.langchain.com/langchain) agents. @@ -12,52 +14,32 @@ observability to [LangChain](https://www.langchain.com/langchain) agents. Install the LangChain integration extra in your application environment. -::::{tab-set} -:sync-group: install-tool - -:::{tab-item} uv -:selected: -:sync: uv + -```bash +```bash title="uv" for="uv" uv add "nemo-flow[langchain]" ``` -::: -:::{tab-item} pip -:sync: pip - -```bash +```bash title="pip" for="pip" pip install "nemo-flow[langchain]" ``` -::: -:::: + The example below uses the NVIDIA LangChain provider. Install that provider extra too if you want to run the example as written: -::::{tab-set} -:sync-group: install-tool - -:::{tab-item} uv -:selected: -:sync: uv + -```bash +```bash title="uv" for="uv" uv add "nemo-flow[langchain,langchain-nvidia]" ``` -::: -:::{tab-item} pip -:sync: pip - -```bash +```bash title="pip" for="pip" pip install "nemo-flow[langchain,langchain-nvidia]" ``` -::: -:::: + ## Usage Example @@ -69,13 +51,11 @@ from langchain.agents import create_agent from langchain_core.tools import tool from nemo_flow.integrations.langchain import NemoFlowCallbackHandler, NemoFlowMiddleware - @tool def get_weather(location: str) -> str: """Get the current weather for a location.""" return f"The weather in {location} is sunny and 72 degrees." - agent = create_agent( model="nvidia:nvidia/nemotron-3-nano-30b-a3b", tools=[get_weather], @@ -103,4 +83,4 @@ print(f"Final response: {final_message.content}") ## Observability -Refer to [Observability](../plugins/observability/about.md) for details on exporting NeMo Flow observability data to third-party systems. +Refer to [Observability](/observability-plugin/about) for details on exporting NeMo Flow observability data to third-party systems. diff --git a/docs/integrations/langgraph.md b/docs/integrations/langgraph.mdx similarity index 76% rename from docs/integrations/langgraph.md rename to docs/integrations/langgraph.mdx index f68834ec..2f1365f7 100644 --- a/docs/integrations/langgraph.md +++ b/docs/integrations/langgraph.mdx @@ -1,9 +1,11 @@ - - -# NeMo Flow LangGraph Integration +--- +title: "NeMo Flow LangGraph Integration" +sidebar-title: "LangGraph Integration Guide" +description: "" +position: 4 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use the `nemo_flow.integrations.langgraph` package to add NeMo Flow observability to [LangGraph](https://www.langchain.com/langgraph) workflows through public LangGraph APIs. @@ -12,27 +14,17 @@ observability to [LangGraph](https://www.langchain.com/langgraph) workflows thro Install the LangGraph integration extra in your application environment. -::::{tab-set} -:sync-group: install-tool - -:::{tab-item} uv -:selected: -:sync: uv + -```bash +```bash title="uv" for="uv" uv add "nemo-flow[langgraph]" ``` -::: - -:::{tab-item} pip -:sync: pip -```bash +```bash title="pip" for="pip" pip install "nemo-flow[langgraph]" ``` -::: -:::: + Installing the `langgraph` extra also installs the LangChain integration dependencies. @@ -46,15 +38,12 @@ import nemo_flow from langgraph.graph import END, START, StateGraph from nemo_flow.integrations.langgraph import NemoFlowCallbackHandler - class State(TypedDict): value: int - def increment(state: State) -> State: return {"value": state["value"] + 1} - builder = StateGraph(State) builder.add_node("increment", increment) builder.add_edge(START, "increment") @@ -86,7 +75,6 @@ agent = create_agent( middleware=[NemoFlowMiddleware()], ) - def agent_node(state: dict, config: RunnableConfig) -> dict: return agent.invoke({"messages": state["messages"]}, config=config) ``` @@ -94,28 +82,18 @@ def agent_node(state: dict, config: RunnableConfig) -> dict: Install the NVIDIA LangChain provider if you want to run the nested agent example as written: -::::{tab-set} -:sync-group: install-tool + -:::{tab-item} uv -:selected: -:sync: uv - -```bash +```bash title="uv" for="uv" uv add "nemo-flow[langgraph,langchain-nvidia]" ``` -::: - -:::{tab-item} pip -:sync: pip -```bash +```bash title="pip" for="pip" pip install "nemo-flow[langgraph,langchain-nvidia]" ``` -::: -:::: + ## Observability -Refer to [Observability](../plugins/observability/about.md) for details on exporting NeMo Flow observability data to third-party systems. +Refer to [Observability](/observability-plugin/about) for details on exporting NeMo Flow observability data to third-party systems. diff --git a/docs/integrations/openclaw-plugin.md b/docs/integrations/openclaw-plugin.mdx similarity index 97% rename from docs/integrations/openclaw-plugin.md rename to docs/integrations/openclaw-plugin.mdx index 2548ba42..f8400fef 100644 --- a/docs/integrations/openclaw-plugin.md +++ b/docs/integrations/openclaw-plugin.mdx @@ -1,9 +1,10 @@ - - -# OpenClaw Plugin Guide +--- +title: "OpenClaw Plugin Guide" +description: "" +position: 2 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use the OpenClaw plugin when OpenClaw owns the agent, tool, and LLM lifecycle that needs NeMo Flow observability. The plugin observes supported OpenClaw @@ -166,17 +167,18 @@ The OpenClaw wrapper owns `enabled`, `backend`, `capture`, and `correlation`. The top-level `plugins` object inside the wrapper is the generic NeMo Flow plugin configuration document. -:::{note} + OpenClaw wrapper fields such as `includePrompts` and `llmOutputGraceMs` follow the OpenClaw plugin schema. Fields inside `config.plugins` are NeMo Flow generic plugin configuration, so they use `snake_case` regardless of language. -::: + + Missing observability sections are disabled. Plugin-host validation or initialization errors degrade the NeMo Flow runtime as a whole, and the status method reports configured output health from the generic observability component. See -[Observability Configuration](../plugins/observability/configuration.md) +[Observability Configuration](/observability-plugin/configuration) for the complete `observability` component schema and exporter-specific fields. ## Verify the Integration diff --git a/docs/nemo-flow-cli/about.md b/docs/nemo-flow-cli/about.mdx similarity index 72% rename from docs/nemo-flow-cli/about.md rename to docs/nemo-flow-cli/about.mdx index c2e4d30f..3f49de34 100644 --- a/docs/nemo-flow-cli/about.md +++ b/docs/nemo-flow-cli/about.mdx @@ -1,9 +1,10 @@ - - -# About +--- +title: "About" +description: "" +position: 1 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this section when you want the `nemo-flow` binary to observe local coding agent sessions through hooks, a passthrough LLM gateway, and NeMo Flow @@ -28,8 +29,8 @@ Use these guides when you need to: - Diagnose hook loading, gateway routing, and exporter output. If you are instrumenting an application or framework directly, use -[Instrument Applications](../instrument-applications/about.md) or -[Integrate into Frameworks](../integrate-frameworks/about.md) instead. +[Instrument Applications](/instrument-applications/about) or +[Integrate into Frameworks](/integrate-into-frameworks/about) instead. ## Agent Harness Support @@ -46,18 +47,18 @@ NeMo Flow CLI support is experimental and observability-focused. Use these guide links to move from CLI setup into agent-specific instructions. -- [Basic Usage](basic-usage.md) explains gateway routes, transparent runs, +- [Basic Usage](/nemo-flow-cli/basic-usage) explains gateway routes, transparent runs, shared configuration, hook forwarding, and runtime mapping. -- [Claude Code](claude-code.md) covers transparent Claude Code +- [Claude Code](/nemo-flow-cli/claude-code) covers transparent Claude Code runs, Anthropic gateway routing, ATIF verification, and unsupported Claude application modes. -- [Codex](codex.md) covers transparent Codex CLI runs, local +- [Codex](/nemo-flow-cli/codex) covers transparent Codex CLI runs, local GUI/app caveats, model provider routing, and remote-task limits. -- [Cursor](cursor.md) covers transparent Cursor runs, temporary +- [Cursor](/nemo-flow-cli/cursor) covers transparent Cursor runs, temporary hook patching, GUI and CLI smoke tests, and gateway routing limits. -- [Hermes Agent](hermes.md) covers Hermes shell hook installation, +- [Hermes Agent](/nemo-flow-cli/hermes) covers Hermes shell hook installation, dynamic gateway URL handling, session-finalize behavior, and hook consent caveats. -Start with [Basic Usage](basic-usage.md), then use the guide for the coding +Start with [Basic Usage](/nemo-flow-cli/basic-usage), then use the guide for the coding agent that you want to observe. diff --git a/docs/nemo-flow-cli/basic-usage.md b/docs/nemo-flow-cli/basic-usage.mdx similarity index 96% rename from docs/nemo-flow-cli/basic-usage.md rename to docs/nemo-flow-cli/basic-usage.mdx index da95f8e4..8d23ad82 100644 --- a/docs/nemo-flow-cli/basic-usage.md +++ b/docs/nemo-flow-cli/basic-usage.mdx @@ -1,9 +1,10 @@ - - -# Basic Usage +--- +title: "Basic Usage" +description: "" +position: 2 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} The `nemo-flow` binary observes coding agents that do not expose every LLM call site directly. It combines agent-specific hook endpoints with a @@ -257,10 +258,10 @@ Optional flags map to gateway headers: Use the per-agent guide for end-to-end setup, smoke tests, and GUI or application-mode caveats. -- [Claude Code](claude-code.md) -- [Codex](codex.md) -- [Cursor](cursor.md) -- [Hermes Agent](hermes.md) +- [Claude Code](/nemo-flow-cli/claude-code) +- [Codex](/nemo-flow-cli/codex) +- [Cursor](/nemo-flow-cli/cursor) +- [Hermes Agent](/nemo-flow-cli/hermes) Each guide covers transparent run setup, gateway routing, hook smoke tests, Agent Trajectory Interchange Format (ATIF) export verification on session end, diff --git a/docs/nemo-flow-cli/claude-code.md b/docs/nemo-flow-cli/claude-code.mdx similarity index 95% rename from docs/nemo-flow-cli/claude-code.md rename to docs/nemo-flow-cli/claude-code.mdx index 8789e6f2..85a6197e 100644 --- a/docs/nemo-flow-cli/claude-code.md +++ b/docs/nemo-flow-cli/claude-code.mdx @@ -1,9 +1,10 @@ - - -# Claude Code +--- +title: "Claude Code" +description: "" +position: 3 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this guide to observe Claude Code sessions with NeMo Flow. Claude Code is the supported integration target. The Claude application, Claude web, and Claude diff --git a/docs/nemo-flow-cli/codex.md b/docs/nemo-flow-cli/codex.mdx similarity index 96% rename from docs/nemo-flow-cli/codex.md rename to docs/nemo-flow-cli/codex.mdx index 462d9f8e..d05aca87 100644 --- a/docs/nemo-flow-cli/codex.md +++ b/docs/nemo-flow-cli/codex.mdx @@ -1,9 +1,10 @@ - - -# Codex +--- +title: "Codex" +description: "" +position: 4 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this guide to observe local Codex CLI sessions and local Codex GUI or app sessions that honor the same local config and gateway routing. Cloud or remote @@ -17,13 +18,14 @@ local gateway cannot observe provider traffic that never reaches the machine. versions either reject the provider override or do not recognize the hooks feature flag. -```{warning} + As of Codex 0.129, Codex requires hooks to be manually reviewed and activated before they run. Generated NeMo Flow hook configuration is not enough on its own if Codex leaves those hooks inactive. Review and activate the installed or injected hooks in Codex before expecting NeMo Flow events. This is being tracked upstream as [openai/codex#21639](https://github.com/openai/codex/issues/21639). -``` + + ## Transparent Run diff --git a/docs/nemo-flow-cli/cursor.md b/docs/nemo-flow-cli/cursor.mdx similarity index 96% rename from docs/nemo-flow-cli/cursor.md rename to docs/nemo-flow-cli/cursor.mdx index d5fe3d5f..fb70904b 100644 --- a/docs/nemo-flow-cli/cursor.md +++ b/docs/nemo-flow-cli/cursor.mdx @@ -1,9 +1,10 @@ - - -# Cursor +--- +title: "Cursor" +description: "" +position: 5 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this guide to observe Cursor hook lifecycle events with NeMo Flow. The repository ships a Cursor hook bundle under `integrations/coding-agents/cursor/` @@ -24,12 +25,13 @@ does not fire in Cursor CLI. If CLI hooks still do not fire with direct versioned entries, treat that Cursor CLI version as hook-limited and gateway-only where model routing is configurable. -```{warning} + Cursor CLI hook coverage is not the same as Cursor IDE hook coverage. Current headless CLI builds can emit fewer hook events than Cursor IDE sessions. Treat missing CLI hook events as a Cursor CLI limitation after `nemo-flow doctor cursor` confirms the hook file uses the direct versioned shape. -``` + + ## Transparent Run diff --git a/docs/nemo-flow-cli/hermes.md b/docs/nemo-flow-cli/hermes.mdx similarity index 95% rename from docs/nemo-flow-cli/hermes.md rename to docs/nemo-flow-cli/hermes.mdx index b0edf331..3c2b7de7 100644 --- a/docs/nemo-flow-cli/hermes.md +++ b/docs/nemo-flow-cli/hermes.mdx @@ -1,9 +1,10 @@ - - -# Hermes Agent +--- +title: "Hermes Agent" +description: "" +position: 6 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this guide to observe local Hermes Agent sessions with NeMo Flow through Hermes shell hooks and the `nemo-flow` gateway. This gateway path is diff --git a/docs/plugins/adaptive/about.md b/docs/plugins/adaptive/about.mdx similarity index 69% rename from docs/plugins/adaptive/about.md rename to docs/plugins/adaptive/about.mdx index 3aec4a3c..284e6374 100644 --- a/docs/plugins/adaptive/about.md +++ b/docs/plugins/adaptive/about.mdx @@ -1,9 +1,11 @@ - - -# Adaptive +--- +title: "Adaptive" +sidebar-title: "About" +description: "" +position: 1 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use the Adaptive plugin when you want NeMo Flow to collect runtime signals and activate measured adaptive behavior through the shared plugin system. @@ -38,18 +40,18 @@ Start here when you need to: - Roll out optimization as a configuration change. If instrumentation is not in place yet, start with -[Instrument Applications](../../instrument-applications/about.md) or -[Integrate into Frameworks](../../integrate-frameworks/about.md). +[Instrument Applications](/instrument-applications/about) or +[Integrate into Frameworks](/integrate-into-frameworks/about). ## Pages -- [Adaptive Configuration](configuration.md) documents the full plugin +- [Adaptive Configuration](/adaptive-plugin/configuration) documents the full plugin component shape, validation, activation, teardown, and whole-plugin settings. -- [ACG](acg.md) explains Adaptive Cache Governor configuration and what prompt +- [ACG](/adaptive-plugin/acg) explains Adaptive Cache Governor configuration and what prompt cache planning accomplishes. -- [Adaptive Hints](adaptive-hints.md) explains request hint injection and how +- [Adaptive Hints](/adaptive-plugin/adaptive-hints) explains request hint injection and how downstream model paths can consume the hints. State, telemetry, tool parallelism, and policy are whole-plugin configuration -areas. They are documented on [Adaptive Configuration](configuration.md) rather +areas. They are documented on [Adaptive Configuration](/adaptive-plugin/configuration) rather than as separate area pages. diff --git a/docs/plugins/adaptive/acg.md b/docs/plugins/adaptive/acg.mdx similarity index 92% rename from docs/plugins/adaptive/acg.md rename to docs/plugins/adaptive/acg.mdx index 558ebd0f..82fda4f2 100644 --- a/docs/plugins/adaptive/acg.md +++ b/docs/plugins/adaptive/acg.mdx @@ -1,9 +1,10 @@ - - -# Adaptive Cache Governor (ACG) +--- +title: "Adaptive Cache Governor (ACG)" +description: "" +position: 3 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use the Adaptive Cache Governor (ACG) when repeated LLM requests contain stable prompt sections that can benefit from provider prompt caching. @@ -52,13 +53,9 @@ prompt samples. Use plugin configuration when the application should let NeMo Flow own the Adaptive Cache Governor (ACG) runtime lifecycle. -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" import nemo_flow adaptive_config = nemo_flow.adaptive.AdaptiveConfig( @@ -85,12 +82,8 @@ try: finally: nemo_flow.plugin.clear() ``` -::: -:::{tab-item} Node.js -:sync: node - -```js +```js title="Node.js" for="node" const adaptive = require("nemo-flow-node/adaptive"); const plugin = require("nemo-flow-node/plugin"); @@ -115,12 +108,8 @@ try { plugin.clear(); } ``` -::: - -:::{tab-item} Rust -:sync: rust -```rust +```rust title="Rust" for="rust" use nemo_flow::plugin::{initialize_plugins, validate_plugin_config, PluginConfig}; use nemo_flow_adaptive::plugin_component::ComponentSpec; use nemo_flow_adaptive::{ @@ -149,22 +138,17 @@ assert!(!report.has_errors()); let active = initialize_plugins(plugin_config).await?; ``` -::: -:::: + ## Manual API Use the manual runtime API when an integration needs to own adaptive lifecycle directly instead of activating the top-level plugin component. -::::{tab-set} -:sync-group: language + -:::{tab-item} Python -:sync: python - -```python +```python title="Python" for="python" import nemo_flow adaptive_config = nemo_flow.adaptive.AdaptiveConfig( @@ -184,19 +168,8 @@ try: finally: await runtime.shutdown() ``` -::: - -:::{tab-item} Node.js -:sync: node -The Node.js binding exposes ACG through the adaptive plugin component helpers. -Use the Plugin Configuration example above when activating ACG from Node.js. -::: - -:::{tab-item} Rust -:sync: rust - -```rust +```rust title="Rust" for="rust" use nemo_flow_adaptive::{ AcgComponentConfig, AdaptiveConfig, AdaptiveRuntime, BackendSpec, StateConfig, TelemetryComponentConfig, @@ -224,9 +197,11 @@ runtime.register().await?; runtime.wait_for_idle(); runtime.shutdown().await?; ``` -::: -:::: + + +The Node.js binding exposes ACG through the adaptive plugin component helpers. +Use the Plugin Configuration example above when activating ACG from Node.js. ## Fields diff --git a/docs/plugins/adaptive/adaptive-hints.md b/docs/plugins/adaptive/adaptive-hints.mdx similarity index 92% rename from docs/plugins/adaptive/adaptive-hints.md rename to docs/plugins/adaptive/adaptive-hints.mdx index 64fe9044..22cffc22 100644 --- a/docs/plugins/adaptive/adaptive-hints.md +++ b/docs/plugins/adaptive/adaptive-hints.mdx @@ -1,9 +1,10 @@ - - -# Adaptive Hints +--- +title: "Adaptive Hints" +description: "" +position: 4 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use Adaptive Hints when downstream model calls or provider adapters can safely receive guidance metadata from the adaptive runtime. @@ -47,13 +48,9 @@ allowing later request intercepts to continue running. Use plugin configuration when the application should let NeMo Flow own the Adaptive Hints request-intercept lifecycle. -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" import nemo_flow adaptive_config = nemo_flow.adaptive.AdaptiveConfig( @@ -82,12 +79,8 @@ try: finally: nemo_flow.plugin.clear() ``` -::: -:::{tab-item} Node.js -:sync: node - -```js +```js title="Node.js" for="node" const adaptive = require("nemo-flow-node/adaptive"); const plugin = require("nemo-flow-node/plugin"); @@ -114,12 +107,8 @@ try { plugin.clear(); } ``` -::: - -:::{tab-item} Rust -:sync: rust -```rust +```rust title="Rust" for="rust" use nemo_flow::plugin::{initialize_plugins, validate_plugin_config, PluginConfig}; use nemo_flow_adaptive::plugin_component::ComponentSpec; use nemo_flow_adaptive::{ @@ -148,22 +137,17 @@ assert!(!report.has_errors()); let active = initialize_plugins(plugin_config).await?; ``` -::: -:::: + ## Manual API Use the manual runtime API when an integration needs to own adaptive lifecycle directly instead of activating the top-level plugin component. -::::{tab-set} -:sync-group: language + -:::{tab-item} Python -:sync: python - -```python +```python title="Python" for="python" import nemo_flow adaptive_config = nemo_flow.adaptive.AdaptiveConfig( @@ -185,20 +169,8 @@ try: finally: await runtime.shutdown() ``` -::: - -:::{tab-item} Node.js -:sync: node -The Node.js binding exposes Adaptive Hints through the adaptive plugin component -helpers. Use the Plugin Configuration example above when activating Adaptive -Hints from Node.js. -::: - -:::{tab-item} Rust -:sync: rust - -```rust +```rust title="Rust" for="rust" use nemo_flow_adaptive::{ set_latency_sensitivity, AdaptiveConfig, AdaptiveHintsComponentConfig, AdaptiveRuntime, BackendSpec, StateConfig, TelemetryComponentConfig, @@ -226,9 +198,12 @@ set_latency_sensitivity(8).ok(); runtime.shutdown().await?; ``` -::: -:::: + + +The Node.js binding exposes Adaptive Hints through the adaptive plugin component +helpers. Use the Plugin Configuration example above when activating Adaptive +Hints from Node.js. ## Fields diff --git a/docs/plugins/adaptive/configuration.md b/docs/plugins/adaptive/configuration.mdx similarity index 91% rename from docs/plugins/adaptive/configuration.md rename to docs/plugins/adaptive/configuration.mdx index 69491a51..625cd143 100644 --- a/docs/plugins/adaptive/configuration.md +++ b/docs/plugins/adaptive/configuration.mdx @@ -1,9 +1,11 @@ - - -# Adaptive Configuration +--- +title: "Adaptive Configuration" +sidebar-title: "Configuration" +description: "" +position: 2 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this page when you want to configure the built-in Adaptive plugin component as a whole. The component kind is `adaptive`. @@ -14,7 +16,7 @@ language helper functions use language-native naming conventions. For plugin file discovery, precedence, merge behavior, editor controls, and gateway conflict rules, see -[Plugin Configuration Files](../../build-plugins/plugin-configuration-files.md). +[Plugin Configuration Files](/build-plugins/plugin-configuration-files). ## Component Shape @@ -31,8 +33,8 @@ The top-level adaptive object contains: | `acg` | Adaptive Cache Governor prompt-cache planning. | | `policy` | Adaptive-local handling for unknown fields and unsupported values. | -The requested area pages cover [Adaptive Cache Governor (ACG)](acg.md) and -[Adaptive Hints](adaptive-hints.md). State, telemetry, tool parallelism, and +The requested area pages cover [Adaptive Cache Governor (ACG)](/adaptive-plugin/acg) and +[Adaptive Hints](/adaptive-plugin/adaptive-hints). State, telemetry, tool parallelism, and policy remain whole-plugin settings: - Use `state.backend.kind = "in_memory"` for local experiments. @@ -95,13 +97,9 @@ requests can be observed without provider-specific cache translation. ## Per-Language Plugin Configuration -::::{tab-set} -:sync-group: language - -:::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" import nemo_flow adaptive_config = nemo_flow.adaptive.AdaptiveConfig( @@ -130,12 +128,8 @@ if any(diagnostic["level"] == "error" for diagnostic in report["diagnostics"]): active = await nemo_flow.plugin.initialize(plugin_config) ``` -::: -:::{tab-item} Node.js -:sync: node - -```js +```js title="Node.js" for="node" const adaptive = require("nemo-flow-node/adaptive"); const plugin = require("nemo-flow-node/plugin"); @@ -162,12 +156,8 @@ if (report.diagnostics.some((diagnostic) => diagnostic.level === "error")) { const active = await plugin.initialize(pluginConfig); ``` -::: - -:::{tab-item} Rust -:sync: rust -```rust +```rust title="Rust" for="rust" use nemo_flow::plugin::{initialize_plugins, validate_plugin_config, PluginConfig}; use nemo_flow_adaptive::plugin_component::ComponentSpec; use nemo_flow_adaptive::{ @@ -207,22 +197,17 @@ assert!(!report.has_errors()); let active = initialize_plugins(plugin_config).await?; ``` -::: -:::: + ## Manual API Use the manual runtime API when an integration needs to own adaptive lifecycle directly instead of activating the top-level plugin component. -::::{tab-set} -:sync-group: language + -:::{tab-item} Python -:sync: python - -```python +```python title="Python" for="python" import nemo_flow adaptive_config = nemo_flow.adaptive.AdaptiveConfig( @@ -249,20 +234,8 @@ try: finally: await runtime.shutdown() ``` -::: - -:::{tab-item} Node.js -:sync: node -The Node.js binding exposes the built-in adaptive runtime through the adaptive -plugin component helpers. Use the Plugin Configuration example above when -activating adaptive behavior from Node.js. -::: - -:::{tab-item} Rust -:sync: rust - -```rust +```rust title="Rust" for="rust" use nemo_flow_adaptive::{ AcgComponentConfig, AdaptiveConfig, AdaptiveHintsComponentConfig, AdaptiveRuntime, BackendSpec, StateConfig, TelemetryComponentConfig, ToolParallelismComponentConfig, @@ -295,9 +268,12 @@ runtime.register().await?; runtime.wait_for_idle(); runtime.shutdown().await?; ``` -::: -:::: + + +The Node.js binding exposes the built-in adaptive runtime through the adaptive +plugin component helpers. Use the Plugin Configuration example above when +activating adaptive behavior from Node.js. ## Validation And Teardown @@ -318,7 +294,7 @@ plugin runtime. ## Rollout Guidance -Start by enabling state and telemetry in a development environment. Run +Start by enabling state and telemetry in a dev environment. Run representative instrumented workflows, inspect emitted events and adaptive reports, and then enable active behavior one area at a time. Keep rollback as a configuration change. diff --git a/docs/plugins/observability/about.md b/docs/plugins/observability/about.mdx similarity index 67% rename from docs/plugins/observability/about.md rename to docs/plugins/observability/about.mdx index 2bbbd659..99a6d4bd 100644 --- a/docs/plugins/observability/about.md +++ b/docs/plugins/observability/about.mdx @@ -1,9 +1,11 @@ - - -# Observability +--- +title: "Observability" +sidebar-title: "About" +description: "" +position: 1 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use the Observability plugin when you need to inspect NeMo Flow lifecycle events in process or export agent activity to tracing, trajectory, or analysis @@ -44,7 +46,7 @@ Start here when you need to: - Produce trajectory data for analysis, replay, or evaluation workflows. If you have not instrumented scopes, tools, or LLM calls yet, start with -[Instrument Applications](../../instrument-applications/about.md). +[Instrument Applications](/instrument-applications/about). ## Exporter Selection @@ -52,20 +54,20 @@ Choose the exporter based on the downstream system: | Need | Use | |---|---| -| Raw canonical event stream | [Agent Trajectory Observability Format (ATOF)](atof.md) | -| Offline analysis, replay, or evaluation trajectories | [Agent Trajectory Interchange Format (ATIF)](atif.md) | -| Generic OTLP traces | [OpenTelemetry](opentelemetry.md) | -| OpenInference-oriented agent and LLM spans | [OpenInference](openinference.md) | +| Raw canonical event stream | [Agent Trajectory Observability Format (ATOF)](/observability-plugin/atof) | +| Offline analysis, replay, or evaluation trajectories | [Agent Trajectory Interchange Format (ATIF)](/observability-plugin/atif) | +| Generic OTLP traces | [OpenTelemetry](/observability-plugin/opentelemetry) | +| OpenInference-oriented agent and LLM spans | [OpenInference](/observability-plugin/openinference) | Start with local event inspection before production export. Add sanitize guardrails before exporters receive sensitive payloads. ## Pages -- [Observability Configuration](configuration.md) documents the whole plugin +- [Observability Configuration](/observability-plugin/configuration) documents the whole plugin component shape, activation, validation, and teardown. -- [Agent Trajectory Observability Format (ATOF)](atof.md) covers raw JSONL event stream export. -- [Agent Trajectory Interchange Format (ATIF)](atif.md) covers per-agent trajectory export. -- [OpenTelemetry](opentelemetry.md) covers generic OTLP trace export. -- [OpenInference](openinference.md) covers OpenInference-oriented OTLP trace +- [Agent Trajectory Observability Format (ATOF)](/observability-plugin/atof) covers raw JSONL event stream export. +- [Agent Trajectory Interchange Format (ATIF)](/observability-plugin/atif) covers per-agent trajectory export. +- [OpenTelemetry](/observability-plugin/opentelemetry) covers generic OTLP trace export. +- [OpenInference](/observability-plugin/openinference) covers OpenInference-oriented OTLP trace export. diff --git a/docs/plugins/observability/atif.md b/docs/plugins/observability/atif.mdx similarity index 91% rename from docs/plugins/observability/atif.md rename to docs/plugins/observability/atif.mdx index c9bad9f0..2349c850 100644 --- a/docs/plugins/observability/atif.md +++ b/docs/plugins/observability/atif.mdx @@ -1,9 +1,10 @@ - - -# Agent Trajectory Interchange Format (ATIF) +--- +title: "Agent Trajectory Interchange Format (ATIF)" +description: "" +position: 3 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use the `atif` section when you want one Agent Trajectory Interchange Format (ATIF) trajectory artifact per top-level agent run. @@ -65,13 +66,9 @@ trajectory. Use plugin configuration when the application should let NeMo Flow own the ATIF dispatcher lifecycle. -:::::{tab-set} -:sync-group: language - -::::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" from nemo_flow import plugin from nemo_flow.observability import AtifConfig, ComponentSpec, ObservabilityConfig @@ -104,12 +101,7 @@ finally: plugin.clear() ``` -:::: - -::::{tab-item} Node.js -:sync: node - -```js +```js title="Node.js" for="node" const plugin = require("nemo-flow-node/plugin"); const observability = require("nemo-flow-node/observability"); @@ -137,12 +129,7 @@ try { } ``` -:::: - -::::{tab-item} Rust -:sync: rust - -```rust +```rust title="Rust" for="rust" use nemo_flow::observability::plugin_component::{ AtifSectionConfig, ComponentSpec, ObservabilityConfig, }; @@ -173,22 +160,16 @@ assert!(!report.has_errors()); let active = initialize_plugins(config).await?; ``` -:::: - -::::: + ## Manual API Use the manual `AtifExporter` API when you need explicit collection boundaries or one exporter object per run. -:::::{tab-set} -:sync-group: language + -::::{tab-item} Python -:sync: python - -```python +```python title="Python" for="python" from nemo_flow import AtifExporter exporter = AtifExporter("session-1", "agent", "1.0.0", model_name="demo-model") @@ -201,12 +182,7 @@ exporter.deregister("atif-exporter") exporter.clear() ``` -:::: - -::::{tab-item} Node.js -:sync: node - -```js +```js title="Node.js" for="node" const { AtifExporter } = require("nemo-flow-node"); const exporter = new AtifExporter("session-1", "agent", "1.0.0", "demo-model"); @@ -223,12 +199,7 @@ try { } ``` -:::: - -::::{tab-item} Rust -:sync: rust - -```rust +```rust title="Rust" for="rust" use nemo_flow::api::subscriber::{deregister_subscriber, register_subscriber}; use nemo_flow::observability::atif::{AtifAgentInfo, AtifExporter}; @@ -254,9 +225,7 @@ let _ = deregister_subscriber("atif-exporter")?; exporter.clear(); ``` -:::: - -::::: + ## Common Validation Failures diff --git a/docs/plugins/observability/atof.md b/docs/plugins/observability/atof.mdx similarity index 88% rename from docs/plugins/observability/atof.md rename to docs/plugins/observability/atof.mdx index 9e9f8c18..80c37a6d 100644 --- a/docs/plugins/observability/atof.md +++ b/docs/plugins/observability/atof.mdx @@ -1,9 +1,10 @@ - - -# Agent Trajectory Observability Format (ATOF) +--- +title: "Agent Trajectory Observability Format (ATOF)" +description: "" +position: 4 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use the `atof` section when you want the raw Agent Trajectory Observability Format (ATOF) `0.1` event stream written as JSONL. @@ -47,7 +48,7 @@ JSON object per lifecycle event to `logs/events.jsonl`. Each emitted scope, tool, LLM, middleware, or mark event is written as one ATOF JSON object per line. For event field semantics, see -[Events](../../about/concepts/events.md). +[Events](/about-nemo-flow/concepts/events). Register the plugin before instrumented work starts and clear it during shutdown so file handles flush. @@ -57,13 +58,9 @@ shutdown so file handles flush. Use plugin configuration when the application should let NeMo Flow own the ATOF exporter lifecycle. -:::::{tab-set} -:sync-group: language - -::::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" from nemo_flow import plugin from nemo_flow.observability import AtofConfig, ComponentSpec, ObservabilityConfig @@ -94,12 +91,7 @@ finally: plugin.clear() ``` -:::: - -::::{tab-item} Node.js -:sync: node - -```js +```js title="Node.js" for="node" const plugin = require("nemo-flow-node/plugin"); const observability = require("nemo-flow-node/observability"); @@ -125,12 +117,7 @@ try { } ``` -:::: - -::::{tab-item} Rust -:sync: rust - -```rust +```rust title="Rust" for="rust" use nemo_flow::observability::plugin_component::{ AtofSectionConfig, ComponentSpec, ObservabilityConfig, }; @@ -158,22 +145,16 @@ assert!(!report.has_errors()); let active = initialize_plugins(config).await?; ``` -:::: - -::::: + ## Manual API Use the manual `AtofExporter` API when a test or script needs a custom subscriber name or explicit registration window. -:::::{tab-set} -:sync-group: language + -::::{tab-item} Python -:sync: python - -```python +```python title="Python" for="python" from nemo_flow import AtofExporter, AtofExporterConfig, AtofExporterMode config = AtofExporterConfig() @@ -191,12 +172,7 @@ exporter.deregister("atof-exporter") exporter.shutdown() ``` -:::: - -::::{tab-item} Node.js -:sync: node - -```js +```js title="Node.js" for="node" const { AtofExporter } = require("nemo-flow-node"); const exporter = new AtofExporter({ @@ -216,12 +192,7 @@ try { } ``` -:::: - -::::{tab-item} Rust -:sync: rust - -```rust +```rust title="Rust" for="rust" use nemo_flow::observability::atof::{ AtofExporter, AtofExporterConfig, AtofExporterMode, }; @@ -240,9 +211,7 @@ let _ = exporter.deregister("atof-exporter")?; exporter.shutdown()?; ``` -:::: - -::::: + ## Common Validation Failures diff --git a/docs/plugins/observability/configuration.md b/docs/plugins/observability/configuration.mdx similarity index 95% rename from docs/plugins/observability/configuration.md rename to docs/plugins/observability/configuration.mdx index 7dd7b9c4..ab673219 100644 --- a/docs/plugins/observability/configuration.md +++ b/docs/plugins/observability/configuration.mdx @@ -1,9 +1,11 @@ - - -# Observability Configuration +--- +title: "Observability Configuration" +sidebar-title: "Configuration" +description: "" +position: 2 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this page when an application should install standard observability exporters from one plugin configuration document instead of manually registering @@ -15,14 +17,15 @@ or initialization. For plugin file discovery, precedence, merge behavior, editor controls, and gateway conflict rules, see -[Plugin Configuration Files](../../build-plugins/plugin-configuration-files.md). +[Plugin Configuration Files](/build-plugins/plugin-configuration-files). -:::{note} + Observability plugin configuration uses the generic NeMo Flow plugin document shape, so field names are `snake_case` in every binding. This differs from Node.js runtime classes such as `OpenTelemetrySubscriber`, which use Node-native `camelCase` option names outside the plugin system. -::: + + ## What It Installs @@ -115,13 +118,9 @@ disable an inherited section. ## Per-Language Plugin Configuration -:::::{tab-set} -:sync-group: language + -::::{tab-item} Python -:sync: python - -```python +```python title="Python" for="python" from nemo_flow import plugin, scope, ScopeType from nemo_flow.observability import ( AtifConfig, @@ -181,12 +180,7 @@ finally: plugin.clear() ``` -:::: - -::::{tab-item} Node.js -:sync: node - -```js +```js title="Node.js" for="node" const plugin = require("nemo-flow-node/plugin"); const observability = require("nemo-flow-node/observability"); @@ -239,12 +233,7 @@ try { } ``` -:::: - -::::{tab-item} Rust -:sync: rust - -```rust +```rust title="Rust" for="rust" use nemo_flow::observability::plugin_component::{ AtifSectionConfig, AtofSectionConfig, ComponentSpec, ObservabilityConfig, OtlpSectionConfig, @@ -299,9 +288,7 @@ assert!(!report.has_errors()); let active = initialize_plugins(config).await?; ``` -:::: - -::::: + ## Validation And Teardown diff --git a/docs/plugins/observability/openinference.md b/docs/plugins/observability/openinference.mdx similarity index 92% rename from docs/plugins/observability/openinference.md rename to docs/plugins/observability/openinference.mdx index 0d574aaa..008c765a 100644 --- a/docs/plugins/observability/openinference.md +++ b/docs/plugins/observability/openinference.mdx @@ -1,9 +1,10 @@ - - -# OpenInference +--- +title: "OpenInference" +description: "" +position: 6 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use the `openinference` section when you want NeMo Flow lifecycle events exported as OTLP trace spans with OpenInference-oriented semantics. @@ -48,7 +49,7 @@ OpenInference-style OTLP spans to Phoenix or another compatible backend. ## Fields OpenInference uses the same OTLP section shape as -[OpenTelemetry](opentelemetry.md): +[OpenTelemetry](/observability-plugin/opentelemetry): | Field | Default | Notes | |---|---|---| @@ -77,13 +78,9 @@ export. Use plugin configuration when the application should let NeMo Flow own the OpenInference subscriber lifecycle. -:::::{tab-set} -:sync-group: language - -::::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" from nemo_flow import plugin from nemo_flow.observability import ComponentSpec, ObservabilityConfig, OtlpConfig @@ -119,12 +116,7 @@ finally: plugin.clear() ``` -:::: - -::::{tab-item} Node.js -:sync: node - -```js +```js title="Node.js" for="node" const plugin = require("nemo-flow-node/plugin"); const observability = require("nemo-flow-node/observability"); @@ -159,12 +151,7 @@ try { } ``` -:::: - -::::{tab-item} Rust -:sync: rust - -```rust +```rust title="Rust" for="rust" use nemo_flow::observability::plugin_component::{ ComponentSpec, ObservabilityConfig, OtlpSectionConfig, }; @@ -198,22 +185,16 @@ assert!(!report.has_errors()); let active = initialize_plugins(config).await?; ``` -:::: - -::::: + ## Manual API Use the manual subscriber API when you need an explicit subscriber name or direct `force_flush` control. -:::::{tab-set} -:sync-group: language + -::::{tab-item} Python -:sync: python - -```python +```python title="Python" for="python" from nemo_flow import OpenInferenceConfig, OpenInferenceSubscriber config = OpenInferenceConfig() @@ -232,12 +213,7 @@ subscriber.deregister("openinference-exporter") subscriber.shutdown() ``` -:::: - -::::{tab-item} Node.js -:sync: node - -```js +```js title="Node.js" for="node" const { OpenInferenceSubscriber } = require("nemo-flow-node"); const subscriber = new OpenInferenceSubscriber({ @@ -260,12 +236,7 @@ try { } ``` -:::: - -::::{tab-item} Rust -:sync: rust - -```rust +```rust title="Rust" for="rust" use nemo_flow::observability::openinference::{ OpenInferenceConfig, OpenInferenceSubscriber, }; @@ -284,9 +255,7 @@ let _ = subscriber.deregister("openinference-exporter")?; subscriber.shutdown()?; ``` -:::: - -::::: + ## Common Validation Failures diff --git a/docs/plugins/observability/opentelemetry.md b/docs/plugins/observability/opentelemetry.mdx similarity index 92% rename from docs/plugins/observability/opentelemetry.md rename to docs/plugins/observability/opentelemetry.mdx index 97f948fc..1e24c0a1 100644 --- a/docs/plugins/observability/opentelemetry.md +++ b/docs/plugins/observability/opentelemetry.mdx @@ -1,9 +1,10 @@ - - -# OpenTelemetry +--- +title: "OpenTelemetry" +description: "" +position: 5 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use the `opentelemetry` section when you want NeMo Flow lifecycle events exported as generic OpenTelemetry Protocol (OTLP) trace spans. @@ -74,13 +75,9 @@ graceful shutdown. Use plugin configuration when the application should let NeMo Flow own the OpenTelemetry subscriber lifecycle. -:::::{tab-set} -:sync-group: language - -::::{tab-item} Python -:sync: python + -```python +```python title="Python" for="python" from nemo_flow import plugin from nemo_flow.observability import ComponentSpec, ObservabilityConfig, OtlpConfig @@ -116,12 +113,7 @@ finally: plugin.clear() ``` -:::: - -::::{tab-item} Node.js -:sync: node - -```js +```js title="Node.js" for="node" const plugin = require("nemo-flow-node/plugin"); const observability = require("nemo-flow-node/observability"); @@ -156,12 +148,7 @@ try { } ``` -:::: - -::::{tab-item} Rust -:sync: rust - -```rust +```rust title="Rust" for="rust" use nemo_flow::observability::plugin_component::{ ComponentSpec, ObservabilityConfig, OtlpSectionConfig, }; @@ -195,22 +182,16 @@ assert!(!report.has_errors()); let active = initialize_plugins(config).await?; ``` -:::: - -::::: + ## Manual API Use the manual subscriber API when you need an explicit subscriber name or direct `force_flush` control. -:::::{tab-set} -:sync-group: language + -::::{tab-item} Python -:sync: python - -```python +```python title="Python" for="python" from nemo_flow import OpenTelemetryConfig, OpenTelemetrySubscriber config = OpenTelemetryConfig() @@ -229,12 +210,7 @@ subscriber.deregister("otel-exporter") subscriber.shutdown() ``` -:::: - -::::{tab-item} Node.js -:sync: node - -```js +```js title="Node.js" for="node" const { OpenTelemetrySubscriber } = require("nemo-flow-node"); const subscriber = new OpenTelemetrySubscriber({ @@ -257,12 +233,7 @@ try { } ``` -:::: - -::::{tab-item} Rust -:sync: rust - -```rust +```rust title="Rust" for="rust" use nemo_flow::observability::otel::{OpenTelemetryConfig, OpenTelemetrySubscriber}; let config = OpenTelemetryConfig::http_binary("agent-service") @@ -278,9 +249,7 @@ let _ = subscriber.deregister("otel-exporter")?; subscriber.shutdown()?; ``` -:::: - -::::: + ## Common Validation Failures diff --git a/docs/reference/api/index.md b/docs/reference/api/index.md deleted file mode 100644 index f36356a0..00000000 --- a/docs/reference/api/index.md +++ /dev/null @@ -1,17 +0,0 @@ - - -# APIs - -Use these pages for generated symbol-level API documentation across the -supported public language surfaces. - -```{toctree} -:maxdepth: 2 - -Python -Node.js -Rust -``` diff --git a/docs/reference/api/index.mdx b/docs/reference/api/index.mdx new file mode 100644 index 00000000..70fc3735 --- /dev/null +++ b/docs/reference/api/index.mdx @@ -0,0 +1,13 @@ +--- +title: "APIs" +description: "" +position: 1 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} + +Use these generated library references for symbol-level API documentation: + +- [Python Library Reference](/reference/api/python-library-reference) +- [Node.js Library Reference](/reference/api/nodejs-library-reference) +- [Rust Library Reference](/reference/api/rust-library-reference) diff --git a/docs/reference/api/nodejs/index.md b/docs/reference/api/nodejs/index.md deleted file mode 100644 index 0fa1d33e..00000000 --- a/docs/reference/api/nodejs/index.md +++ /dev/null @@ -1,74 +0,0 @@ - - -# Node.js API - -These pages are generated from the exported TypeScript declaration surfaces in `crates/node`, including the generated root `index.d.ts`. - -## Binding At A Glance - -This summary lists the package identity and support status for the binding. - -- Package name: `nemo-flow-node` -- Runtime requirement: Node.js `>=20` -- Local development path: `crates/node` - -The Node.js binding is built with `napi-rs`. The package root exports the core -runtime lifecycle APIs, and the package also publishes focused subpath exports -for typed helpers, plugin helpers, adaptive helpers, and observability helpers. - -## Main Binding Surfaces - -These entry points are the primary APIs to use from this binding. - -- Package root: scope stack, event, tool, LLM, middleware, and subscriber APIs -- `nemo-flow-node/typed`: typed wrappers and codec-aware execution helpers -- `nemo-flow-node/plugin`: plugin-facing helpers and configuration types -- `nemo-flow-node/adaptive`: adaptive helpers layered on top of the runtime -- `nemo-flow-node/observability`: built-in observability plugin helpers - -## How To Read The Generated Pages - -The generated pages are organized around the package export map: - -- `Runtime`: the package root declarations from `index.d.ts` -- `Typed Helpers`: the `./typed` export -- `Plugins`: the `./plugin` export -- `Adaptive`: the `./adaptive` export -- `Observability`: the `./observability` export - -Use the generated Node.js pages for symbol-level documentation: - -- {doc}`Runtime <_generated/runtime>` -- {doc}`Typed Helpers <_generated/typed>` -- {doc}`Plugins <_generated/plugin>` -- {doc}`Adaptive <_generated/adaptive>` -- {doc}`Observability <_generated/observability>` - -```{toctree} -:maxdepth: 1 - -runtime <_generated/runtime> -typed <_generated/typed> -plugin <_generated/plugin> -adaptive <_generated/adaptive> -observability <_generated/observability> -``` - -## Related Guides - -Use these links to continue from the API reference into task-focused guides. - -- [Quick Start](../../../getting-started/quick-start.md) -- [Node.js Quick Start](../../../getting-started/nodejs.md) -- [Scopes](../../../about/concepts/scopes.md) -- [Middleware](../../../about/concepts/middleware.md) -- [Subscribers](../../../about/concepts/subscribers.md) -- [Plugins](../../../about/concepts/plugins.md) -- [Adaptive Optimization](../../../plugins/adaptive/about.md) -- [Observability Configuration](../../../plugins/observability/configuration.md) -- [Instrument a Tool Call](../../../instrument-applications/instrument-tool-call.md) -- [Typed Wrappers and Codecs](../../../integrate-frameworks/using-codecs.md) -- [Framework Integration Surfaces](../../../integrate-frameworks/about.md) diff --git a/docs/reference/api/python/index.md b/docs/reference/api/python/index.md deleted file mode 100644 index 674eb495..00000000 --- a/docs/reference/api/python/index.md +++ /dev/null @@ -1,75 +0,0 @@ - - -# Python API - -These pages are generated from the `python/nemo_flow` package source. - -## Binding At A Glance - -This summary lists the package identity and support status for the binding. - -- Package name: `nemo-flow` -- Local development path: repository root `pyproject.toml` with `uv sync` -- Generated package root: `nemo_flow` - -The Python binding exposes the runtime through a public package layer in -`python/nemo_flow` and a compiled native extension exposed as `nemo_flow._native`. -Most users should work from the public package modules rather than the native -layer directly. - -## Main Binding Surfaces - -These entry points are the primary APIs to use from this binding. - -- `nemo_flow.scope`: create scopes, emit mark events, and manage scope handles -- `nemo_flow.tools` and `nemo_flow.llm`: run tool and LLM lifecycles from Python -- `nemo_flow.guardrails` and `nemo_flow.intercepts`: register global middleware -- `nemo_flow.scope_local`: register middleware against a specific scope hierarchy -- `nemo_flow.subscribers`: observe emitted runtime lifecycle events -- `nemo_flow.plugin`, `nemo_flow.adaptive`, and `nemo_flow.observability`: configure plugin-backed, adaptive, and exporter behavior -- `nemo_flow.typed` and `nemo_flow.codecs`: use typed wrappers and request/response codecs - -## How To Read The Generated Pages - -The generated `nemo_flow` package page is the package root. Under that page you -will find submodule pages for the public binding surface, including: - -- `llm` -- `tools` -- `scope` -- `scope_local` -- `guardrails` -- `intercepts` -- `subscribers` -- `plugin` -- `adaptive` -- `observability` -- `typed` -- `codecs` - -Use the {doc}`generated Python package index <_generated/nemo_flow/index>` -when you want the docstring-level details for a specific symbol or module. - -```{toctree} -:maxdepth: 1 - -nemo_flow <_generated/nemo_flow/index> -``` - -## Related Guides - -Use these links to continue from the API reference into task-focused guides. - -- [Quick Start](../../../getting-started/quick-start.md) -- [Python Quick Start](../../../getting-started/python/index.md) -- [Scopes](../../../about/concepts/scopes.md) -- [Middleware](../../../about/concepts/middleware.md) -- [Subscribers](../../../about/concepts/subscribers.md) -- [Plugins](../../../about/concepts/plugins.md) -- [Adaptive Optimization](../../../plugins/adaptive/about.md) -- [Observability Configuration](../../../plugins/observability/configuration.md) -- [Typed Wrappers and Codecs](../../../integrate-frameworks/using-codecs.md) -- [Framework Integration Surfaces](../../../integrate-frameworks/about.md) diff --git a/docs/reference/api/rust/index.md b/docs/reference/api/rust/index.md deleted file mode 100644 index 9d83cafc..00000000 --- a/docs/reference/api/rust/index.md +++ /dev/null @@ -1,82 +0,0 @@ - - -# Rust API - -These pages are generated from the public Rust crates that back the core runtime and adaptive components. - -## Binding At A Glance - -This summary lists the package identity and support status for the binding. - -- Published crates: `nemo-flow`, `nemo-flow-adaptive`, `nemo-flow-ffi`, and - `nemo-flow-cli` -- Local development paths: `crates/core`, `crates/adaptive`, `crates/ffi`, - and `crates/cli` -- Primary audience: Rust consumers who want the native runtime surface directly - -The Rust docs are organized by crate because the Rust binding is the source -implementation of the runtime. The generated pages mirror each crate's public -module tree. - -## Main Binding Surfaces - -These entry points are the primary APIs to use from this binding. - -- `nemo-flow`: core runtime APIs for scopes, tools, LLMs, registries, subscribers, codecs, streams, observability exporters, and the built-in observability plugin -- `nemo-flow-adaptive`: adaptive runtime helpers, learner implementations, storage backends, and adaptive configuration -- `nemo-flow-cli`: binary gateway for coding-agent hooks and passthrough LLM observability -- `nemo-flow-ffi`: raw C ABI used by downstream native bindings - -Within `nemo-flow`, most integrations start in `api`, especially the `scope`, -`tool`, `llm`, `registry`, and `subscriber` modules. Other important public -modules include `codec`, `observability`, `stream`, `error`, and `json`. The -`observability::plugin_component` module contains the built-in `observability` -plugin config types. - -Within `nemo-flow-adaptive`, the main surfaces include adaptive configuration, -plugin components, storage abstractions, learners, trie-backed data -structures, and optional Redis-backed helpers when the feature is enabled. -`nemo-flow-cli` is a binary crate, so its end-user surface is documented in -the NeMo Flow CLI guides rather than generated Rust API pages. - -## How To Read The Generated Pages - -Use the crate pages first, then expand into the public modules under each crate: - -- `nemo-flow` for core runtime behavior -- `nemo-flow-adaptive` for adaptive and learning-oriented behavior -- `nemo-flow-cli` for coding-agent observability through hooks and the - passthrough LLM gateway - -That structure matches how Rust consumers import items from the crates. - -Use the generated crate entry points when you need symbol-level detail: - -- {doc}`nemo_flow <_generated/nemo-flow/src>` -- {doc}`nemo_flow_adaptive <_generated/nemo-flow-adaptive/src>` - -```{toctree} -:maxdepth: 1 - -nemo-flow <_generated/nemo-flow/src> -nemo-flow-adaptive <_generated/nemo-flow-adaptive/src> -``` - -## Related Guides - -Use these links to continue from the API reference into task-focused guides. - -- [Quick Start](../../../getting-started/quick-start.md) -- [Rust Quick Start](../../../getting-started/rust.md) -- [Scopes](../../../about/concepts/scopes.md) -- [Middleware](../../../about/concepts/middleware.md) -- [Subscribers](../../../about/concepts/subscribers.md) -- [Plugins](../../../about/concepts/plugins.md) -- [Adaptive Optimization](../../../plugins/adaptive/about.md) -- [Observability Configuration](../../../plugins/observability/configuration.md) -- [Typed Wrappers and Codecs](../../../integrate-frameworks/using-codecs.md) -- [Framework Integration Surfaces](../../../integrate-frameworks/about.md) -- [NeMo Flow CLI Basic Usage](../../../nemo-flow-cli/basic-usage.md) diff --git a/docs/reference/performance.md b/docs/reference/performance.mdx similarity index 73% rename from docs/reference/performance.md rename to docs/reference/performance.mdx index ba644360..c6f3fc2b 100644 --- a/docs/reference/performance.md +++ b/docs/reference/performance.mdx @@ -1,9 +1,10 @@ - - -# Performance +--- +title: "Performance" +description: "" +position: 2 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} NeMo Flow keeps runtime overhead focused around the work that is active for the current scope and call. @@ -30,7 +31,7 @@ Use these practices when applying the concept in application or integration code Use these links to continue into adjacent concepts and workflows. -- [Architecture](../about/architecture.md) -- [Middleware](../about/concepts/middleware.md) -- [Subscribers](../about/concepts/subscribers.md) -- [Typed Wrappers And Codecs](../integrate-frameworks/using-codecs.md) +- [Architecture](/about-nemo-flow/architecture) +- [Middleware](/about-nemo-flow/concepts/middleware) +- [Subscribers](/about-nemo-flow/concepts/subscribers) +- [Typed Wrappers And Codecs](/integrate-into-frameworks/using-codecs) diff --git a/docs/resources/community.md b/docs/resources/community.md deleted file mode 100644 index fb011e4c..00000000 --- a/docs/resources/community.md +++ /dev/null @@ -1,21 +0,0 @@ - - -# Community - -Use the repository as the primary community and contribution entry point. - -## Contributors - -Start with the repository root `CONTRIBUTING.md`, then read: - -- [Contribute](../contribute/about.md) -- [Development Setup](../contribute/development-setup.md) -- [Workflow And Reviews](../contribute/workflow-and-reviews.md) -- [Testing And Documentation](../contribute/testing-and-docs.md) - -## Third-Party Integrations - -Use [Ecosystem](../about/ecosystem.md) to find the maintained sample integration patches and the scripts used to apply them. diff --git a/docs/resources/community.mdx b/docs/resources/community.mdx new file mode 100644 index 00000000..0e903f6c --- /dev/null +++ b/docs/resources/community.mdx @@ -0,0 +1,22 @@ +--- +title: "Community" +description: "" +position: 4 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} + +Use the repository as the primary community and contribution entry point. + +## Contributors + +Start with the repository root `CONTRIBUTING.md`, then read: + +- [Contribute](/contribute/about) +- [Development Setup](/contribute/development-setup) +- [Workflow and Reviews](/contribute/workflow-and-reviews) +- [Testing And Documentation](/contribute/testing-and-docs) + +## Third-Party Integrations + +Use [Ecosystem](/about-nemo-flow/ecosystem) to find the maintained sample integration patches and the scripts used to apply them. diff --git a/docs/resources/glossary.md b/docs/resources/glossary.md deleted file mode 100644 index 535fc381..00000000 --- a/docs/resources/glossary.md +++ /dev/null @@ -1,426 +0,0 @@ - - -# Glossary - -NeMo Flow uses specialized runtime, integration, plugin, adaptive, and -observability terms across bindings. This glossary defines the shared terms so -the rest of the documentation can use them consistently. - -```{glossary} -:sorted: - -Activation Report - An **activation report** records which plugin components validated, - initialized, or registered behavior successfully. Use it to distinguish - configuration problems from runtime behavior problems. - -Adaptive Cache Governor (ACG) - The **adaptive cache governor (ACG)** is the adaptive subsystem that analyzes - LLM prompt structure, tracks stable prompt blocks, and plans - provider-specific prompt-cache breakpoints. - -Adaptive Component - The **adaptive component** is the built-in plugin component with kind - ``adaptive``. It can register telemetry subscribers, adaptive hint - intercepts, tool-parallelism behavior, cache-governor behavior, and adaptive - state backends. - -Adaptive Hint - An **adaptive hint** is metadata injected into an outgoing model request by an - adaptive request intercept. Downstream code or provider adapters can use the - hint to adjust behavior when explicitly configured to do so. - -Adaptive Optimization - **Adaptive optimization** is the NeMo Flow runtime capability that observes - instrumented work and enables controlled behavior changes through the plugin - system. - -Adaptive State Backend - An **adaptive state backend** stores observations and learned state for - adaptive behavior. In-memory state is process-local; Redis-backed state can be - shared across workers or survive process restarts. - -Adaptive Telemetry - **Adaptive telemetry** is the subscriber path that observes lifecycle events - for adaptive learners without changing execution by itself. - -Agent Trajectory Interchange Format (ATIF) - **Agent Trajectory Interchange Format (ATIF)** is an external trajectory - format used for offline analysis, replay, or evaluation. The NeMo Flow ATIF - exporter collects lifecycle events and exports ATIF v1.6 trajectory data. - -Agent Trajectory Observability Format (ATOF) - **Agent Trajectory Observability Format (ATOF)** is the canonical event format - NeMo Flow emits for scope lifecycle events and mark events. Subscribers and - exporters consume ATOF events before translating them into downstream - observability formats such as ATIF trajectories, OpenTelemetry traces, or - OpenInference spans. - -Annotated Request And Response Data - **Annotated request and response data** is normalized provider information - created by LLM codecs. It lets request intercepts, subscribers, and exporters - reason about provider payloads through a shared model while preserving the raw - provider request or response shape. - -Binding - A **binding** is a language-specific public API surface for the NeMo Flow - runtime, such as Python, Node.js, Go, WebAssembly, Rust, or C FFI. - -Break Chain - ``break_chain`` is the request-intercept setting that stops later request - intercepts after the current intercept returns. Use it only when the current - request transform should be final. - -Callback - A **callback** is the application, framework, tool, or provider function that - does the real work. Managed execution passes this callback through NeMo Flow - so middleware and lifecycle events surround the invocation. - -Category Profile - A **category profile** is the event field that stores category-specific - semantic details. NeMo Flow uses it for values such as LLM ``model_name``, - tool ``tool_call_id``, and custom ``subtype``. - -Codec - A **codec** is a deterministic translator at a NeMo Flow boundary. Codecs let - framework or provider-native values remain convenient for application code - while NeMo Flow observes JSON-compatible or normalized data. - -Collection Window - A **collection window** is the period during which an in-process exporter, - such as the ATIF exporter, buffers events before export or clear. Bounded - collection windows prevent unrelated runs from mixing in one artifact. - -Collector - A **collector** is the callback used by streaming LLM helpers to observe each - streamed chunk and accumulate state for the final response. - -Conditional Execution - A **conditional-execution guardrail** decides whether the call is allowed to - run at all. - -Event - An **event** is the runtime record of something that happened. NeMo Flow emits - events for scope start and end, tool start and end, LLM start and end, and - named mark points. - - Events are the shared data model consumed by subscribers and exporters. - -Event Envelope - The **event envelope** is the shared set of fields carried by every ATOF - event, including identifiers, timestamps, names, data, data schema, metadata, - and parent linkage. - -Execution Intercept - An **execution intercept** wraps or replaces the real callback. - - Use this when behavior belongs around the invocation boundary itself, such as: - - - Retries - - Timing - - Routing - - Wrapper logic - - Framework integration - -Explicit Lifecycle API - An **explicit lifecycle API** is a manual start, end, or mark helper used when - a framework owns the real invocation internally. It preserves observability - but does not let execution intercepts wrap the real callback automatically. - -Exporter - An **exporter** is a subscriber-oriented component that translates NeMo Flow - events into an external artifact or backend format, such as an ATIF trajectory - or OTLP trace spans. - -FFI - **FFI** means foreign function interface. NeMo Flow's C FFI layer exposes core - runtime behavior to non-Rust languages and is used by the Go binding. - -Finalizer - A **finalizer** is the callback used by streaming LLM helpers when the stream - ends. It turns collected stream state into the response payload that - sanitize-response guardrails, subscribers, and exporters can observe. - -Global And Scope-Local Registration - NeMo Flow supports two main ownership levels for middleware and subscribers. - - - **Global registrations** stay active for the whole process until removed. - - **Scope-local registrations** are owned by one active scope and are cleaned - up automatically when that scope closes. - - This split lets process-wide defaults coexist with request-local policy or - instrumentation. - -Guardrail - A **guardrail** is middleware that either blocks execution or rewrites the - data recorded on emitted events. - - Sanitize guardrails are observability-oriented. They do not rewrite the real - arguments passed to the callback or the real value returned to the caller. - -Integration Boundary - An **integration boundary** is the stable point in an application, framework, - or provider adapter where NeMo Flow can wrap, observe, or transform a tool or - LLM invocation. - -Intercept - An **intercept** is middleware that changes the real request path or wraps the - real callback. - -JSON-Compatible Payload - A **JSON-compatible payload** is data that can be represented in NeMo Flow's - JSON model. Event data, middleware payloads, and codec output should be - JSON-compatible. - -Learner - A **learner** is an adaptive component that consumes observed event data and - derives reusable guidance, such as tool parallelism plans or cache stability - signals. - -Lifecycle Pair - A **lifecycle pair** is the matching start and end event for one scope, tool - call, or LLM call. Subscribers and exporters use lifecycle pairs to compute - durations, reconstruct boundaries, and preserve nesting. - -LLM Call - An **LLM call** is an instrumented model-provider invocation. Managed LLM - calls emit start and end events, run LLM middleware, and can carry a - normalized ``model_name`` for observability and trajectory export. - -LLM Stream - An **LLM stream** is a streaming model response managed across multiple chunks - rather than a single response object. NeMo Flow captures the originating scope - stack, runs stream execution intercepts, collects chunks, and finalizes the - stream into a response-side event payload. - -Managed Execution And Manual Lifecycle - NeMo Flow supports two main ways to model tool and LLM work. - - - **Managed execution** means NeMo Flow owns the middleware pipeline and - emitted lifecycle around the invocation. - - **Manual lifecycle** means some other framework or runtime owns the real - call boundary, and NeMo Flow only records the start and end points - explicitly. - - Managed execution is the default choice for application code. Manual - lifecycle exists mainly for framework integrations that cannot delegate the - real invocation to NeMo Flow. - -Managed Execution Wrapper - A **managed execution wrapper** is the integration pattern where a tool or LLM - provider callback is routed through NeMo Flow's managed execute helper. This - is the preferred pattern when NeMo Flow can own middleware ordering, lifecycle - pairing, and event emission around the real callback. - -Mark Event - A **mark event** is a point-in-time event for a named runtime checkpoint that - is not a full start/end lifecycle pair. Use marks for retries, checkpoints, - interrupts, state transitions, or framework milestones that do not represent - a complete nested invocation. - -Middleware - **Middleware** is the runtime behavior that runs around tool or LLM work. - Middleware can inspect, reject, transform, wrap, or sanitize execution at - well-defined lifecycle points. - - NeMo Flow has two major middleware families: - - - **Intercepts** affect the real execution path. - - **Guardrails** block work or rewrite the observability payload. - -Middleware Registry - A **middleware registry** stores named middleware entries for one runtime - surface, such as tool request intercepts or LLM sanitize-response guardrails. - The runtime combines global registry entries with visible scope-local entries - before managed execution. - -Next Function - The **next function** is the continuation passed to an execution intercept. - The intercept calls ``next`` to run the next intercept or the original - callback. An intercept that does not call ``next`` intentionally replaces or - short-circuits the rest of the invocation. - -Non-Serializable Data - **Non-serializable data** is framework or SDK state that cannot be represented - as JSON, such as clients, streams, callbacks, file handles, or class - instances. Keep those objects outside NeMo Flow payloads and pass only stable - identifiers or projections through events and middleware. - -OpenInference - **OpenInference** is an AI-observability semantic convention layered on trace - spans. NeMo Flow's OpenInference subscriber maps lifecycle payloads to - OpenInference-oriented attributes such as model inputs, outputs, and token - usage. - -OpenTelemetry - **OpenTelemetry** is a vendor-neutral observability ecosystem. NeMo Flow can - export lifecycle events as OpenTelemetry-compatible trace spans. - -OpenTelemetry Protocol (OTLP) - **OpenTelemetry Protocol (OTLP)** is the transport protocol used by the - OpenTelemetry and OpenInference subscribers to send trace data to a collector - or backend. - -Plugin - A **plugin** is a reusable runtime component that installs middleware, - subscribers, or related behavior from configuration rather than through - hand-written registration at every call site. - - Plugins let you package behavior such as: - - - Reusable policy bundles - - Observability components - - Adaptive behavior - -Plugin Component - A **plugin component** is one configured unit inside plugin configuration. - Each component has a kind and component-specific settings, such as the - built-in ``adaptive`` component. - -Plugin Configuration - **Plugin configuration** is the versioned document or object that describes - which plugin components should be validated, initialized, and activated. - -Plugin Context - A **plugin context** is the activation-time object that plugin code uses to - register middleware, subscribers, or other runtime behavior. - -Priority - **Priority** is the ordering value attached to middleware registrations. NeMo - Flow runs visible middleware in priority order after merging global and - scope-local registrations. - -Prompt IR - **Prompt IR** is the internal representation ACG uses to model an LLM request - as addressable prompt blocks for stability analysis and cache planning. - -Prompt-Cache Breakpoint - A **prompt-cache breakpoint** is a provider-specific location in a prompt - where the cache governor suggests or applies cache behavior for stable prompt - sections. - -Provider Adapter - A **provider adapter** is code that translates between a framework's - model-call surface and a provider-specific API shape. Provider adapters often - use codecs when middleware needs normalized request or response semantics. - -Provider Codec - A **provider codec** converts provider-specific LLM requests or responses - into normalized annotated data. Request codecs decode raw provider requests - before request intercepts run and encode edited annotations back into the - provider request before execution continues. - -Request Intercept - A **request intercept** rewrites the request before execution continues - downstream. - - Use this when the real provider or tool implementation should receive - modified input. - -Response Codec - A **response codec** decodes a raw provider response into annotated response - data for lifecycle events. It does not rewrite the value returned to the - application unless the wrapper's typed value codec also does so. - -Rollout Policy - A **rollout policy** is the configuration strategy for enabling adaptive - behavior gradually, such as starting in observation mode, then injecting - hints, then allowing scheduling or cache-planning behavior. - -Root Scope - The **root scope** is the implicit base scope in every scope stack. All other - scopes in that stack are descendants of the root. - -Root UUID - The **root UUID** is the identifier of the root scope for a scope stack. - Events carry this value as ``root_uuid`` so subscribers and exporters can - group or filter concurrent agent runs. - -Sanitize Request - A **sanitize-request guardrail** rewrites the payload recorded on the emitted - start event. - -Sanitize Response - A **sanitize-response guardrail** rewrites the payload recorded on the emitted - end event. - -Scope - A **scope** is a named unit of ownership in the runtime. Scopes create the - parent-child structure that all emitted work attaches to. - - Scopes answer questions such as: - - - Which request, task, or agent run does this work belong to? - - What is the parent of this tool or LLM call? - - Which scope-local middleware or subscribers are visible here? - -Scope Handle - A **scope handle** is the runtime identifier returned by scope, tool, or LLM - start helpers. Manual lifecycle APIs use handles to pair explicit start and - end calls. - -Scope Stack - A **scope stack** is the active stack of scopes for the current task, thread, - or request context. The stack always includes a root scope, and pushed scopes - form the current parent chain for tools, LLM calls, marks, middleware - visibility, and subscriber visibility. - - Use a fresh scope stack to isolate concurrent requests or agents. Propagate an - existing scope stack only when detached work should remain part of the same - logical trace. - -Scope Type - A **scope type** is the semantic category of a scope, such as ``Agent``, - ``Function``, ``Tool``, ``Llm``, ``Retriever``, ``Embedder``, ``Reranker``, - ``Guardrail``, ``Evaluator``, ``Custom``, or ``Unknown``. - -Stream Execution Intercept - A **stream execution intercept** is the streaming LLM variant of an execution - intercept. It wraps the real stream lifecycle rather than a single - request/response callback. - -Subscriber - A **subscriber** is a consumer of emitted events. Subscribers receive the - runtime event stream and can use it for in-process analytics, forwarding, or - export. - - Examples include: - - - Custom event consumers - - ATIF export - - OpenTelemetry export - - OpenInference export - -Third-Party Integration Patch - A **third-party integration patch** is a repository patch maintained for an - upstream framework under ``patches/`` and applied to the matching submodule - under ``third_party/``. - -Tool Call - A **tool call** is an instrumented invocation of a named tool or function-like - operation. Managed tool calls emit start and end events, run tool middleware, - and can carry an optional provider-specific ``tool_call_id``. - -Tool Parallelism - **Tool parallelism** is adaptive guidance about which tool calls may be run - concurrently or scheduled differently based on observed dependency patterns. - Supported modes include ``observe_only``, ``inject_hints``, and ``schedule``. - -Trace Span - A **trace span** is a timed observability record in a tracing backend. - Exported NeMo Flow scopes, tool calls, LLM calls, and marks appear as spans - when using OpenTelemetry or OpenInference export. - -Trajectory - A **trajectory** is an ordered record of an agent run. In ATIF export, LLM - events become agent steps, tool events become tool calls and observations, and - scope nesting becomes lineage metadata. - -Typed Value Codec - A **typed value codec** converts application-facing values to JSON before - NeMo Flow runs middleware or emits events, then converts JSON back into the - type expected by the framework callback or caller. -``` diff --git a/docs/resources/glossary.mdx b/docs/resources/glossary.mdx new file mode 100644 index 00000000..1f961ef0 --- /dev/null +++ b/docs/resources/glossary.mdx @@ -0,0 +1,301 @@ +--- +title: "Glossary" +description: "" +position: 2 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} + +NeMo Flow uses specialized runtime, integration, plugin, adaptive, and +observability terms across bindings. This glossary defines the shared terms so +the rest of the documentation can use them consistently. + +**:sorted:** + +**Activation Report** + +An **activation report** records which plugin components validated, initialized, or registered behavior successfully. Use it to distinguish configuration problems from runtime behavior problems. + +**Adaptive Cache Governor (ACG)** + +The **adaptive cache governor (ACG)** is the adaptive subsystem that analyzes LLM prompt structure, tracks stable prompt blocks, and plans provider-specific prompt-cache breakpoints. + +**Adaptive Component** + +The **adaptive component** is the built-in plugin component with kind `adaptive`. It can register telemetry subscribers, adaptive hint intercepts, tool-parallelism behavior, cache-governor behavior, and adaptive state backends. + +**Adaptive Hint** + +An **adaptive hint** is metadata injected into an outgoing model request by an adaptive request intercept. Downstream code or provider adapters can use the hint to adjust behavior when explicitly configured to do so. + +**Adaptive Optimization** + +**Adaptive optimization** is the NeMo Flow runtime capability that observes instrumented work and enables controlled behavior changes through the plugin system. + +**Adaptive State Backend** + +An **adaptive state backend** stores observations and learned state for adaptive behavior. In-memory state is process-local; Redis-backed state can be shared across workers or survive process restarts. + +**Adaptive Telemetry** + +**Adaptive telemetry** is the subscriber path that observes lifecycle events for adaptive learners without changing execution by itself. + +**Agent Trajectory Interchange Format (ATIF)** + +**Agent Trajectory Interchange Format (ATIF)** is an external trajectory format used for offline analysis, replay, or evaluation. The NeMo Flow ATIF exporter collects lifecycle events and exports ATIF v1.6 trajectory data. + +**Agent Trajectory Observability Format (ATOF)** + +**Agent Trajectory Observability Format (ATOF)** is the canonical event format NeMo Flow emits for scope lifecycle events and mark events. Subscribers and exporters consume ATOF events before translating them into downstream observability formats such as ATIF trajectories, OpenTelemetry traces, or OpenInference spans. + +**Annotated Request And Response Data** + +**Annotated request and response data** is normalized provider information created by LLM codecs. It lets request intercepts, subscribers, and exporters reason about provider payloads through a shared model while preserving the raw provider request or response shape. + +**Binding** + +A **binding** is a language-specific public API surface for the NeMo Flow runtime, such as Python, Node.js, Go, WebAssembly, Rust, or C FFI. + +**Break Chain** + +`break_chain` is the request-intercept setting that stops later request intercepts after the current intercept returns. Use it only when the current request transform should be final. + +**Callback** + +A **callback** is the application, framework, tool, or provider function that does the real work. Managed execution passes this callback through NeMo Flow so middleware and lifecycle events surround the invocation. + +**Category Profile** + +A **category profile** is the event field that stores category-specific semantic details. NeMo Flow uses it for values such as LLM `model_name`, tool `tool_call_id`, and custom `subtype`. + +**Codec** + +A **codec** is a deterministic translator at a NeMo Flow boundary. Codecs let framework or provider-native values remain convenient for application code while NeMo Flow observes JSON-compatible or normalized data. + +**Collection Window** + +A **collection window** is the period during which an in-process exporter, such as the ATIF exporter, buffers events before export or clear. Bounded collection windows prevent unrelated runs from mixing in one artifact. + +**Collector** + +A **collector** is the callback used by streaming LLM helpers to observe each streamed chunk and accumulate state for the final response. + +**Conditional Execution** + +A **conditional-execution guardrail** decides whether the call is allowed to run at all. + +**Event** + +An **event** is the runtime record of something that happened. NeMo Flow emits events for scope start and end, tool start and end, LLM start and end, and named mark points. Events are the shared data model consumed by subscribers and exporters. + +**Event Envelope** + +The **event envelope** is the shared set of fields carried by every ATOF event, including identifiers, timestamps, names, data, data schema, metadata, and parent linkage. + +**Execution Intercept** + +An **execution intercept** wraps or replaces the real callback. Use this when behavior belongs around the invocation boundary itself, such as: - Retries - Timing - Routing - Wrapper logic - Framework integration + +**Explicit Lifecycle API** + +An **explicit lifecycle API** is a manual start, end, or mark helper used when a framework owns the real invocation internally. It preserves observability but does not let execution intercepts wrap the real callback automatically. + +**Exporter** + +An **exporter** is a subscriber-oriented component that translates NeMo Flow events into an external artifact or backend format, such as an ATIF trajectory or OTLP trace spans. + +**FFI** + +**FFI** means foreign function interface. NeMo Flow's C FFI layer exposes core runtime behavior to non-Rust languages and is used by the Go binding. + +**Finalizer** + +A **finalizer** is the callback used by streaming LLM helpers when the stream ends. It turns collected stream state into the response payload that sanitize-response guardrails, subscribers, and exporters can observe. + +**Global And Scope-Local Registration** + +NeMo Flow supports two main ownership levels for middleware and subscribers. - **Global registrations** stay active for the whole process until removed. - **Scope-local registrations** are owned by one active scope and are cleaned up automatically when that scope closes. This split lets process-wide defaults coexist with request-local policy or instrumentation. + +**Guardrail** + +A **guardrail** is middleware that either blocks execution or rewrites the data recorded on emitted events. Sanitize guardrails are observability-oriented. They do not rewrite the real arguments passed to the callback or the real value returned to the caller. + +**Integration Boundary** + +An **integration boundary** is the stable point in an application, framework, or provider adapter where NeMo Flow can wrap, observe, or transform a tool or LLM invocation. + +**Intercept** + +An **intercept** is middleware that changes the real request path or wraps the real callback. + +**JSON-Compatible Payload** + +A **JSON-compatible payload** is data that can be represented in NeMo Flow's JSON model. Event data, middleware payloads, and codec output should be JSON-compatible. + +**Learner** + +A **learner** is an adaptive component that consumes observed event data and derives reusable guidance, such as tool parallelism plans or cache stability signals. + +**Lifecycle Pair** + +A **lifecycle pair** is the matching start and end event for one scope, tool call, or LLM call. Subscribers and exporters use lifecycle pairs to compute durations, reconstruct boundaries, and preserve nesting. + +**LLM Call** + +An **LLM call** is an instrumented model-provider invocation. Managed LLM calls emit start and end events, run LLM middleware, and can carry a normalized `model_name` for observability and trajectory export. + +**LLM Stream** + +An **LLM stream** is a streaming model response managed across multiple chunks rather than a single response object. NeMo Flow captures the originating scope stack, runs stream execution intercepts, collects chunks, and finalizes the stream into a response-side event payload. + +**Managed Execution And Manual Lifecycle** + +NeMo Flow supports two main ways to model tool and LLM work. - **Managed execution** means NeMo Flow owns the middleware pipeline and emitted lifecycle around the invocation. - **Manual lifecycle** means some other framework or runtime owns the real call boundary, and NeMo Flow only records the start and end points explicitly. Managed execution is the default choice for application code. Manual lifecycle exists mainly for framework integrations that cannot delegate the real invocation to NeMo Flow. + +**Managed Execution Wrapper** + +A **managed execution wrapper** is the integration pattern where a tool or LLM provider callback is routed through NeMo Flow's managed execute helper. This is the preferred pattern when NeMo Flow can own middleware ordering, lifecycle pairing, and event emission around the real callback. + +**Mark Event** + +A **mark event** is a point-in-time event for a named runtime checkpoint that is not a full start/end lifecycle pair. Use marks for retries, checkpoints, interrupts, state transitions, or framework milestones that do not represent a complete nested invocation. + +**Middleware** + +**Middleware** is the runtime behavior that runs around tool or LLM work. Middleware can inspect, reject, transform, wrap, or sanitize execution at well-defined lifecycle points. NeMo Flow has two major middleware families: - **Intercepts** affect the real execution path. - **Guardrails** block work or rewrite the observability payload. + +**Middleware Registry** + +A **middleware registry** stores named middleware entries for one runtime surface, such as tool request intercepts or LLM sanitize-response guardrails. The runtime combines global registry entries with visible scope-local entries before managed execution. + +**Next Function** + +The **next function** is the continuation passed to an execution intercept. The intercept calls `next` to run the next intercept or the original callback. An intercept that does not call `next` intentionally replaces or short-circuits the rest of the invocation. + +**Non-Serializable Data** + +**Non-serializable data** is framework or SDK state that cannot be represented as JSON, such as clients, streams, callbacks, file handles, or class instances. Keep those objects outside NeMo Flow payloads and pass only stable identifiers or projections through events and middleware. + +**OpenInference** + +**OpenInference** is an AI-observability semantic convention layered on trace spans. NeMo Flow's OpenInference subscriber maps lifecycle payloads to OpenInference-oriented attributes such as model inputs, outputs, and token usage. + +**OpenTelemetry** + +**OpenTelemetry** is a vendor-neutral observability ecosystem. NeMo Flow can export lifecycle events as OpenTelemetry-compatible trace spans. + +**OpenTelemetry Protocol (OTLP)** + +**OpenTelemetry Protocol (OTLP)** is the transport protocol used by the OpenTelemetry and OpenInference subscribers to send trace data to a collector or backend. + +**Plugin** + +A **plugin** is a reusable runtime component that installs middleware, subscribers, or related behavior from configuration rather than through hand-written registration at every call site. Plugins let you package behavior such as: - Reusable policy bundles - Observability components - Adaptive behavior + +**Plugin Component** + +A **plugin component** is one configured unit inside plugin configuration. Each component has a kind and component-specific settings, such as the built-in `adaptive` component. + +**Plugin Configuration** + +**Plugin configuration** is the versioned document or object that describes which plugin components should be validated, initialized, and activated. + +**Plugin Context** + +A **plugin context** is the activation-time object that plugin code uses to register middleware, subscribers, or other runtime behavior. + +**Priority** + +**Priority** is the ordering value attached to middleware registrations. NeMo Flow runs visible middleware in priority order after merging global and scope-local registrations. + +**Prompt IR** + +**Prompt IR** is the internal representation ACG uses to model an LLM request as addressable prompt blocks for stability analysis and cache planning. + +**Prompt-Cache Breakpoint** + +A **prompt-cache breakpoint** is a provider-specific location in a prompt where the cache governor suggests or applies cache behavior for stable prompt sections. + +**Provider Adapter** + +A **provider adapter** is code that translates between a framework's model-call surface and a provider-specific API shape. Provider adapters often use codecs when middleware needs normalized request or response semantics. + +**Provider Codec** + +A **provider codec** converts provider-specific LLM requests or responses into normalized annotated data. Request codecs decode raw provider requests before request intercepts run and encode edited annotations back into the provider request before execution continues. + +**Request Intercept** + +A **request intercept** rewrites the request before execution continues downstream. Use this when the real provider or tool implementation should receive modified input. + +**Response Codec** + +A **response codec** decodes a raw provider response into annotated response data for lifecycle events. It does not rewrite the value returned to the application unless the wrapper's typed value codec also does so. + +**Rollout Policy** + +A **rollout policy** is the configuration strategy for enabling adaptive behavior gradually, such as starting in observation mode, then injecting hints, then allowing scheduling or cache-planning behavior. + +**Root Scope** + +The **root scope** is the implicit base scope in every scope stack. All other scopes in that stack are descendants of the root. + +**Root UUID** + +The **root UUID** is the identifier of the root scope for a scope stack. Events carry this value as `root_uuid` so subscribers and exporters can group or filter concurrent agent runs. + +**Sanitize Request** + +A **sanitize-request guardrail** rewrites the payload recorded on the emitted start event. + +**Sanitize Response** + +A **sanitize-response guardrail** rewrites the payload recorded on the emitted end event. + +**Scope** + +A **scope** is a named unit of ownership in the runtime. Scopes create the parent-child structure that all emitted work attaches to. Scopes answer questions such as: - Which request, task, or agent run does this work belong to? - What is the parent of this tool or LLM call? - Which scope-local middleware or subscribers are visible here? + +**Scope Handle** + +A **scope handle** is the runtime identifier returned by scope, tool, or LLM start helpers. Manual lifecycle APIs use handles to pair explicit start and end calls. + +**Scope Stack** + +A **scope stack** is the active stack of scopes for the current task, thread, or request context. The stack always includes a root scope, and pushed scopes form the current parent chain for tools, LLM calls, marks, middleware visibility, and subscriber visibility. Use a fresh scope stack to isolate concurrent requests or agents. Propagate an existing scope stack only when detached work should remain part of the same logical trace. + +**Scope Type** + +A **scope type** is the semantic category of a scope, such as `Agent`, `Function`, `Tool`, `Llm`, `Retriever`, `Embedder`, `Reranker`, `Guardrail`, `Evaluator`, `Custom`, or `Unknown`. + +**Stream Execution Intercept** + +A **stream execution intercept** is the streaming LLM variant of an execution intercept. It wraps the real stream lifecycle rather than a single request/response callback. + +**Subscriber** + +A **subscriber** is a consumer of emitted events. Subscribers receive the runtime event stream and can use it for in-process analytics, forwarding, or export. Examples include: - Custom event consumers - ATIF export - OpenTelemetry export - OpenInference export + +**Third-Party Integration Patch** + +A **third-party integration patch** is a repository patch maintained for an upstream framework under `patches/` and applied to the matching submodule under `third_party/`. + +**Tool Call** + +A **tool call** is an instrumented invocation of a named tool or function-like operation. Managed tool calls emit start and end events, run tool middleware, and can carry an optional provider-specific `tool_call_id`. + +**Tool Parallelism** + +**Tool parallelism** is adaptive guidance about which tool calls may be run concurrently or scheduled differently based on observed dependency patterns. Supported modes include `observe_only`, `inject_hints`, and `schedule`. + +**Trace Span** + +A **trace span** is a timed observability record in a tracing backend. Exported NeMo Flow scopes, tool calls, LLM calls, and marks appear as spans when using OpenTelemetry or OpenInference export. + +**Trajectory** + +A **trajectory** is an ordered record of an agent run. In ATIF export, LLM events become agent steps, tool events become tool calls and observations, and scope nesting becomes lineage metadata. + +**Typed Value Codec** + +A **typed value codec** converts application-facing values to JSON before NeMo Flow runs middleware or emits events, then converts JSON back into the type expected by the framework callback or caller. diff --git a/docs/resources/legal/index.md b/docs/resources/legal/index.md deleted file mode 100644 index b642f57a..00000000 --- a/docs/resources/legal/index.md +++ /dev/null @@ -1,15 +0,0 @@ - - -# Legal - -Use these pages for open source software attribution and license information. - -```{toctree} -:maxdepth: 1 - -Open Source Software (OSS) -license-agreement -``` diff --git a/docs/resources/legal/index.mdx b/docs/resources/legal/index.mdx new file mode 100644 index 00000000..586323a6 --- /dev/null +++ b/docs/resources/legal/index.mdx @@ -0,0 +1,9 @@ +--- +title: "Legal" +description: "" +position: 5 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} + +Use these pages for open source software attribution and license information. diff --git a/docs/resources/legal/license-agreement.md b/docs/resources/legal/license-agreement.mdx similarity index 52% rename from docs/resources/legal/license-agreement.md rename to docs/resources/legal/license-agreement.mdx index 2eb3a5f2..917f4bfc 100644 --- a/docs/resources/legal/license-agreement.md +++ b/docs/resources/legal/license-agreement.mdx @@ -1,9 +1,10 @@ - - -# License Agreement +--- +title: "License Agreement" +description: "" +position: 2 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} NeMo Flow is licensed under the Apache License 2.0. diff --git a/docs/resources/legal/oss.md b/docs/resources/legal/oss.md deleted file mode 100644 index 77587091..00000000 --- a/docs/resources/legal/oss.md +++ /dev/null @@ -1,16 +0,0 @@ - - -# Open Source Software - -NeMo Flow includes open source dependencies across Rust, Python, and Node.js package surfaces. - -Dependency attribution files live at the repository root: - -- [`ATTRIBUTIONS-Rust.md`](../../../ATTRIBUTIONS-Rust.md) -- [`ATTRIBUTIONS-Python.md`](../../../ATTRIBUTIONS-Python.md) -- [`ATTRIBUTIONS-Node.md`](../../../ATTRIBUTIONS-Node.md) - -Use the repository root `LICENSE` file for the NeMo Flow project license. diff --git a/docs/resources/legal/oss.mdx b/docs/resources/legal/oss.mdx new file mode 100644 index 00000000..c15b30c9 --- /dev/null +++ b/docs/resources/legal/oss.mdx @@ -0,0 +1,18 @@ +--- +title: "Open Source Software" +sidebar-title: "Open Source Software (OSS)" +description: "" +position: 1 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} + +NeMo Flow includes open source dependencies across Rust, Python, and Node.js package surfaces. + +Dependency attribution files live at the repository root: + +- [`ATTRIBUTIONS-Rust.md`](https://github.com/NVIDIA/NeMo-Flow/blob/main/ATTRIBUTIONS-Rust.md) +- [`ATTRIBUTIONS-Python.md`](https://github.com/NVIDIA/NeMo-Flow/blob/main/ATTRIBUTIONS-Python.md) +- [`ATTRIBUTIONS-Node.md`](https://github.com/NVIDIA/NeMo-Flow/blob/main/ATTRIBUTIONS-Node.md) + +Use the repository root `LICENSE` file for the NeMo Flow project license. diff --git a/docs/resources/support-and-faqs.md b/docs/resources/support-and-faqs.mdx similarity index 77% rename from docs/resources/support-and-faqs.md rename to docs/resources/support-and-faqs.mdx index 7c535cb2..331b5597 100644 --- a/docs/resources/support-and-faqs.md +++ b/docs/resources/support-and-faqs.mdx @@ -1,9 +1,10 @@ - - -# Support and FAQs +--- +title: "Support and FAQs" +description: "" +position: 1 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this page to decide where to start, which runtime surface to use, and where to look when a NeMo Flow workflow does not behave as expected. @@ -120,11 +121,11 @@ Start with Python, Node.js, or Rust. These are the primary documented bindings and have the broadest getting-started, concept, guide, and generated API coverage. -- Use [Python Quick Start](../getting-started/python/index.md) when you are adding +- Use [Python Quick Start](/getting-started/quick-start/python) when you are adding NeMo Flow to Python application code or agent harnesses. -- Use [Node.js Quick Start](../getting-started/nodejs.md) when your application, +- Use [Node.js Quick Start](/getting-started/quick-start/nodejs) when your application, framework integration, or plugin-facing code runs in Node.js. -- Use [Rust Quick Start](../getting-started/rust.md) when you want the native +- Use [Rust Quick Start](/getting-started/quick-start/rust) when you want the native runtime surface or are building lower-level integrations. ### Are Go, WebAssembly, And FFI Supported? @@ -151,7 +152,7 @@ Use these questions to find the right first guide for your task. ### What Should I Read First? -Use the [What Should I Read First?](../index.md#what-should-i-read-first) +Use the [What Should I Read First?](/about-nemo-flow/overview#what-should-i-read-first) table on the documentation overview page to pick the right starting point for your task. @@ -167,8 +168,8 @@ workflow step, tool call group, LLM call group, evaluator, retriever, or custom operation that needs ownership in the event stream. Scopes establish parent-child relationships for events and define the lifetime -for scope-local middleware and subscribers. Refer to [Scopes](../about/concepts/scopes.md) -and [Adding Scopes and Marks](../instrument-applications/adding-scopes-and-marks.md). +for scope-local middleware and subscribers. Refer to [Scopes](/about-nemo-flow/concepts/scopes) +and [Adding Scopes and Marks](/instrument-applications/adding-scopes-and-marks). ### How Does NeMo Flow Handle Multiple Concurrent Agents Or Requests? @@ -176,8 +177,8 @@ Use an isolated scope stack for each concurrent request, tenant, worker, or agent run. The root scope identifies the run, and emitted events include root identity so subscribers and exporters can separate overlapping work. -Refer to [Scopes](../about/concepts/scopes.md#context-isolation) and the -[scope and context helper examples](../instrument-applications/code-examples.md#scope-and-context-helpers). +Refer to [Scopes](/about-nemo-flow/concepts/scopes#context-isolation) and the +[scope and context helper examples](/instrument-applications/code-examples#scope-and-context-helpers). ### When Should I Emit A Mark Instead Of A Scope? @@ -186,8 +187,8 @@ point-in-time milestone that should appear in the event stream but does not represent a full lifecycle span, such as "routing complete" or "selected candidate plan." -Refer to [Events](../about/concepts/events.md) and -[Adding Scopes and Marks](../instrument-applications/adding-scopes-and-marks.md#when-to-add-marks). +Refer to [Events](/about-nemo-flow/concepts/events) and +[Adding Scopes and Marks](/instrument-applications/adding-scopes-and-marks#when-to-add-marks). ### Should I Use Managed Execution Helpers Or Manual Lifecycle APIs? @@ -199,8 +200,8 @@ subscriber payloads consistent. Use manual lifecycle APIs only when the framework owns the invocation internally and you only have start and finish hooks. In that case, preserve the start handle, emit the matching end event, and handle error paths deliberately. See -[Invocation API Selection](../instrument-applications/code-examples.md#invocation-api-selection) -and [Preferred Integration Order](../integrate-frameworks/code-examples.md#preferred-integration-order). +[Invocation API Selection](/instrument-applications/code-examples#invocation-api-selection) +and [Preferred Integration Order](/integrate-into-frameworks/code-examples#preferred-integration-order). ### How Are Tool Calls And LLM Calls Different? @@ -209,8 +210,8 @@ structured function or tool execution, while LLM calls represent model-provider requests and responses. LLM calls also carry model-oriented metadata, and streaming LLM flows can use stream-specific execution behavior. -Start with [Instrument a Tool Call](../instrument-applications/instrument-tool-call.md) -or [Instrument an LLM Call](../instrument-applications/instrument-llm-call.md). +Start with [Instrument a Tool Call](/instrument-applications/instrument-tool-call) +or [Instrument an LLM Call](/instrument-applications/instrument-llm-call). ### Does NeMo Flow Support Streaming LLM Responses? @@ -219,8 +220,8 @@ around chunk delivery and finalization, not only around a single response object. Use the streaming helpers when callers need incremental output or when subscribers should observe streaming lifecycle activity. -Refer to [Streaming LLM Execution](../instrument-applications/code-examples.md#streaming-llm-execution) -and [Wrap LLM Calls](../integrate-frameworks/wrap-llm-calls.md#streaming-providers). +Refer to [Streaming LLM Execution](/instrument-applications/code-examples#streaming-llm-execution) +and [Wrap LLM Calls](/integrate-into-frameworks/wrap-llm-calls#streaming-providers). ## Middleware, Policy, And Data @@ -239,8 +240,8 @@ Choose the surface based on what must change: | Rewrite only emitted request or response payloads | Sanitize guardrail | | Wrap streaming chunk delivery and finalization | Stream execution intercept | -Refer to [Middleware](../about/concepts/middleware.md) and -[Add Middleware](../instrument-applications/advanced-guide.md). +Refer to [Middleware](/about-nemo-flow/concepts/middleware) and +[Add Middleware](/instrument-applications/advanced-guide). ### What Is The Middleware Pipeline? @@ -276,8 +277,8 @@ request, workflow, or nested unit of work and disappear automatically when that scope closes. Use plugins when the behavior should be reusable and installed from -configuration. Refer to [Registration Levels](../about/concepts/middleware.md#registration-levels) -and [Middleware Registration Families](../instrument-applications/advanced-guide.md#middleware-registration-families). +configuration. Refer to [Registration Levels](/about-nemo-flow/concepts/middleware#registration-levels) +and [Middleware Registration Families](/instrument-applications/advanced-guide#middleware-registration-families). ### How Does Middleware Ordering Work? @@ -287,7 +288,7 @@ and the real callback, then response sanitization for emitted end events. Registries are priority ordered. When scope-local behavior is present, NeMo Flow combines applicable global and ancestor scope-local entries into the execution -chain. Refer to [Managed Execution Order](../about/concepts/middleware.md#managed-execution-order). +chain. Refer to [Managed Execution Order](/about-nemo-flow/concepts/middleware#managed-execution-order). ### What Data Can Middleware And Events Carry? @@ -297,7 +298,7 @@ instances outside NeMo Flow payloads. When a framework exposes non-serializable objects, pass stable IDs or summarized metadata through NeMo Flow and keep the original objects in framework-owned -storage. Refer to [Handle Non-Serializable Data](../integrate-frameworks/non-serializable-data.md). +storage. Refer to [Handle Non-Serializable Data](/integrate-into-frameworks/non-serializable-data). ### How Do I Keep Sensitive Data Out Of Observability? @@ -306,8 +307,8 @@ subscribers or exporters receive payloads. Keep credentials out of plugin configuration and source code, and emit summarized metadata when full request or response bodies are not needed. -Refer to [Middleware](../about/concepts/middleware.md#guardrails) and -[Observability](../plugins/observability/about.md). +Refer to [Middleware](/about-nemo-flow/concepts/middleware#guardrails) and +[Observability](/observability-plugin/about). ## Observability And Export @@ -319,22 +320,22 @@ Subscribers consume lifecycle events in process. Start with a local subscriber when validating instrumentation, then add exporter-oriented subscribers for operational tracing, trajectory export, or analytics. -Refer to [Subscribers](../about/concepts/subscribers.md), -[Events](../about/concepts/events.md), and -[Observability](../plugins/observability/about.md). +Refer to [Subscribers](/about-nemo-flow/concepts/subscribers), +[Events](/about-nemo-flow/concepts/events), and +[Observability](/observability-plugin/about). ### Which Exporter Should I Use? -Use a local subscriber for debugging and development. Use OpenTelemetry when you +Use a local subscriber for debugging and dev. Use OpenTelemetry when you want OTLP-compatible traces in existing observability infrastructure. Use OpenInference when your tracing stack expects OpenInference-style agent and LLM semantics. Use Agent Trajectory Interchange Format (ATIF) when you need trajectory artifacts for analysis, replay, or evaluation workflows. -Refer to [Exporter Selection](../plugins/observability/about.md#exporter-selection), -[OpenTelemetry](../plugins/observability/opentelemetry.md), -[OpenInference](../plugins/observability/openinference.md), and -[Agent Trajectory Interchange Format (ATIF)](../plugins/observability/atif.md). +Refer to [Exporter Selection](/observability-plugin/about#exporter-selection), +[OpenTelemetry](/observability-plugin/opentelemetry), +[OpenInference](/observability-plugin/openinference), and +[Agent Trajectory Interchange Format (ATIF)](/observability-plugin/atif). ### Can I Use NeMo Flow Just For Observability Without Adaptive Optimization Or Middleware? @@ -360,8 +361,8 @@ subscribers, or related runtime helpers without requiring every application to hand-register the same behavior. Plugins install behavior into the same runtime model; they do not replace -scopes, middleware, or subscribers. Refer to [Plugins](../about/concepts/plugins.md) -and [Build Plugins](../build-plugins/about.md). +scopes, middleware, or subscribers. Refer to [Plugins](/about-nemo-flow/concepts/plugins) +and [Build Plugins](/build-plugins/about). ### When Should I Build A Plugin Instead Of Application Code? @@ -370,8 +371,8 @@ path, or experiment. Build a plugin when the behavior should be reused across applications, activated through configuration, validated before startup, or reported through structured activation diagnostics. -Refer to [Define a Plugin](../build-plugins/basic-guide.md) and -[Register Plugin Behavior](../build-plugins/register-behavior.md). +Refer to [Define a Plugin](/build-plugins/basic-guide) and +[Register Plugin Behavior](/build-plugins/register-behavior). ### How Is Adaptive Optimization Enabled? @@ -380,10 +381,10 @@ telemetry and in-memory state so the runtime can observe representative workflows before changing behavior. Enable active behavior one area at a time, such as adaptive hints, tool parallelism, or cache-governor behavior. -Refer to [Adaptive](../plugins/adaptive/about.md), -[Adaptive Configuration](../plugins/adaptive/configuration.md), -[Adaptive Cache Governor (ACG)](../plugins/adaptive/acg.md), and -[Adaptive Hints](../plugins/adaptive/adaptive-hints.md). +Refer to [Adaptive](/adaptive-plugin/about), +[Adaptive Configuration](/adaptive-plugin/configuration), +[Adaptive Cache Governor (ACG)](/adaptive-plugin/acg), and +[Adaptive Hints](/adaptive-plugin/adaptive-hints). ## Framework Integration And APIs @@ -398,8 +399,8 @@ owns execution. Use standalone conditional-execution or request-intercept helpers only when the framework needs those decisions before it invokes its own downstream code. -Refer to [Framework Integrations](../about/concepts/framework-integrations.md) and -[Integrate into Frameworks](../integrate-frameworks/about.md). +Refer to [Framework Integrations](/about-nemo-flow/concepts/framework-integrations) and +[Integrate into Frameworks](/integrate-into-frameworks/about). ### How Does NeMo Flow Connect To My Favorite Agent Harness Or Framework? @@ -420,9 +421,9 @@ into a normalized request shape for middleware and encoded back before the real provider call. Use provider response codecs when provider responses need a normalized annotated shape for events or downstream consumers. -Refer to [Using Codecs](../integrate-frameworks/using-codecs.md), -[Provider Codecs](../integrate-frameworks/provider-codecs.md), and -[Provider Response Codecs](../integrate-frameworks/provider-response-codecs.md). +Refer to [Using Codecs](/integrate-into-frameworks/using-codecs), +[Provider Codecs](/integrate-into-frameworks/provider-codecs), and +[Provider Response Codecs](/integrate-into-frameworks/provider-response-codecs). ### How Are Third-Party Integrations Maintained? @@ -431,18 +432,18 @@ upstream source checkouts under `third_party/`. Use the repository wrapper scripts when checking or applying those patches, and regenerate the patch after changing files inside a submodule. -Refer to [Framework Integration Code Examples](../integrate-frameworks/code-examples.md#quickstart-apply-maintained-patches) +Refer to [Framework Integration Code Examples](/integrate-into-frameworks/code-examples#quickstart-apply-maintained-patches) and the repository root `third_party/README.md`. ### Where Are The API Docs? -Use [API](../reference/api/index.md) for generated symbol-level documentation. -The primary generated entry points are [Python API](../reference/api/python/index.md), -[Node.js API](../reference/api/nodejs/index.md), and -[Rust API](../reference/api/rust/index.md). - -Go, WebAssembly, and raw FFI are experimental and source-first; use their source -directories and tests when you need exact behavior. +Use the [Python Library Reference](/reference/api/python-library-reference), +[Node.js Library Reference](/reference/api/nodejs-library-reference), and +[Rust Library Reference](/reference/api/rust-library-reference) for generated +symbol-level documentation. The Rust reference includes `nemo-flow`, +`nemo-flow-adaptive`, and `nemo-flow-ffi`. For Go and WebAssembly surfaces, use +the source directories, tests, and task-focused guides when you need exact +behavior. ### What Should I Know About Performance? @@ -451,7 +452,7 @@ scope-local behavior when policy should apply only to one request or workflow. Sanitize or summarize large payloads before production subscribers and exporters consume them. -Refer to [Performance](../reference/performance.md) for runtime-model guidance and +Refer to [Performance](/reference/performance) for runtime-model guidance and related topics. ## Troubleshooting, Releases, And Contributing @@ -461,10 +462,10 @@ you are preparing a contribution. ### What Should I Check When Something Fails? -Start with [Troubleshooting Guide](../troubleshooting/troubleshooting-guide.md). +Start with [Troubleshooting Guide](/resources/troubleshooting). Common checks include: -- Confirm the environment matches [Prerequisites](../getting-started/prerequisites.md). +- Confirm the environment matches [Prerequisites](/getting-started/prerequisites). - Verify work is running inside the intended scope stack. - Check whether middleware was registered globally or scope-locally. - Confirm manual lifecycle calls emit matching start and end events. @@ -473,7 +474,7 @@ Common checks include: ### Where Are Release Notes? -Use [Release Notes](../about/release-notes/index.md) for +Use [Release Notes](/about-nemo-flow/release-notes) for documentation-visible release status. Complete release history is published through the repository release page when that page is available. @@ -485,11 +486,11 @@ logs or emitted events. ### Where Should Contributors Start? -Start with [Contribute](../contribute/about.md) and the repository root +Start with [Contribute](/contribute/about) and the repository root `CONTRIBUTING.md`, then use -[Development Setup](../contribute/development-setup.md), -[Workflow And Reviews](../contribute/workflow-and-reviews.md), and -[Testing And Documentation](../contribute/testing-and-docs.md). +[Development Setup](/contribute/development-setup), +[Workflow and Reviews](/contribute/workflow-and-reviews), and +[Testing And Documentation](/contribute/testing-and-docs). ### How Will AI Coding Assistants Find NeMo Flow? @@ -498,9 +499,10 @@ AI coding assistants should start from the repository root `AGENTS.md`, runtime model, repository layout, supported bindings, validation commands, and contribution workflow. -For symbol-level work, assistants should use the generated Rust, Python, and -Node.js API references. For repository-specific automation, use the NeMo Flow -agent skills under `skills/` and keep examples aligned with the public docs. +For symbol-level work, assistants should use the source directories, tests, and +the generated Python, Node.js, and Rust library references. For +repository-specific automation, use the NeMo Flow agent skills under `skills/` +and keep examples aligned with the public docs. ### Which Tests Should I Run For A Change? @@ -513,12 +515,12 @@ Choose the smallest validation set that covers the touched surface: - WebAssembly changes: run `just test-wasm` and the WebAssembly crate tests (`cargo test -p nemo-flow-wasm`) when integration behavior changed. For focused debugging, you can run `wasm-pack test --node crates/wasm` directly. -- Documentation changes: run `./scripts/build-docs.sh html`. +- Documentation changes: run `./scripts/build-docs.sh check`. -Refer to [Testing and Documentation](../contribute/testing-and-docs.md) for the +Refer to [Testing and Documentation](/contribute/testing-and-docs) for the current contribution workflow. ### What License Applies? NeMo Flow is licensed under Apache-2.0. Source and documentation files use SPDX -headers. Refer to [Legal](legal/index.md) and the repository root `LICENSE`. +headers. Refer to [Legal](/resources/legal) and the repository root `LICENSE`. diff --git a/docs/troubleshooting/troubleshooting-guide.md b/docs/resources/troubleshooting/index.mdx similarity index 63% rename from docs/troubleshooting/troubleshooting-guide.md rename to docs/resources/troubleshooting/index.mdx index bfe95405..b07c0bbb 100644 --- a/docs/troubleshooting/troubleshooting-guide.md +++ b/docs/resources/troubleshooting/index.mdx @@ -1,15 +1,16 @@ - - -# Troubleshooting Guide +--- +title: "Troubleshooting Guide" +description: "" +position: 3 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} Use this page when a NeMo Flow setup, build, or runtime workflow does not behave as expected. ## Package Or Build Setup Fails -Confirm that your environment matches [Prerequisites](../getting-started/prerequisites.md), then rerun the binding-specific setup command from [Installation](../getting-started/installation.md). +Confirm that your environment matches [Prerequisites](/getting-started/prerequisites), then rerun the binding-specific setup command from [Installation](/getting-started/installation). If a command worked previously and now fails, check whether a toolchain update changed the active Rust, Python, Node.js, Go, or WebAssembly version. Recreate generated artifacts after switching versions, especially Python virtual environments, Node.js `node_modules`, Go build caches, and WebAssembly `pkg/` output. @@ -21,7 +22,7 @@ Run the narrowest failing build first: cargo build -p nemo-flow ``` -If the core crate builds but another crate fails, rerun the binding-specific build or test command from [Testing and Documentation](../contribute/testing-and-docs.md). Binding crates often depend on generated native artifacts, host toolchain headers, or runtime-specific test setup. +If the core crate builds but another crate fails, rerun the binding-specific build or test command from [Testing and Documentation](/contribute/testing-and-docs). Binding crates often depend on generated native artifacts, host toolchain headers, or runtime-specific test setup. ## Python Native Module Does Not Import @@ -32,7 +33,7 @@ uv sync uv run pytest python/tests/test_types.py ``` -Confirm that Python satisfies the supported version from [Prerequisites](../getting-started/prerequisites.md). If multiple Python installations are available, make sure the `uv` environment is the one running the test or application process. +Confirm that Python satisfies the supported version from [Prerequisites](/getting-started/prerequisites). If multiple Python installations are available, make sure the `uv` environment is the one running the test or application process. ## Node.js Native Addon Does Not Load @@ -43,7 +44,7 @@ npm install npm test --workspace=nemo-flow-node ``` -Use [Node.js Getting Started](../getting-started/nodejs.md) to confirm that the example runs against the generated local build, not a stale package or a globally installed copy. +Use [Node.js Getting Started](/getting-started/quick-start/nodejs) to confirm that the example runs against the generated local build, not a stale package or a globally installed copy. ## Go Tests Cannot Find The FFI Library @@ -59,7 +60,7 @@ On macOS, use `DYLD_LIBRARY_PATH="../../target/release"` instead of `LD_LIBRARY_ ## WebAssembly Tests Or Package Builds Fail -Confirm that `wasm-pack` is installed and matches the minimum version in [Prerequisites](../getting-started/prerequisites.md), then rerun the WebAssembly build or tests: +Confirm that `wasm-pack` is installed and matches the minimum version in [Prerequisites](/getting-started/prerequisites), then rerun the WebAssembly build or tests: ```bash wasm-pack build crates/wasm @@ -72,55 +73,55 @@ If generated files appear stale, remove the WebAssembly package output and rebui A scope-stack error usually means runtime work is executing outside an active scope or on a thread that did not receive the intended scope stack. -Use [Scopes](../about/concepts/scopes.md) and [Instrument Applications Code Examples](../instrument-applications/code-examples.md#scope-and-context-helpers) to choose the correct scope stack helper for the binding and concurrency model. +Use [Scopes](/about-nemo-flow/concepts/scopes) and [Instrument Applications Code Examples](/instrument-applications/code-examples#scope-and-context-helpers) to choose the correct scope stack helper for the binding and concurrency model. ## Work Leaks Across Requests Unexpected shared scopes, middleware, or events across concurrent requests usually means more than one request is using the same scope stack. Create a fresh scope stack per request or agent, and pass that stack into async tasks, threads, callbacks, or worker boundaries that continue the request. -Use [Adding Scopes and Marks](../instrument-applications/adding-scopes-and-marks.md) and [Scopes](../about/concepts/scopes.md) to verify that the root scope matches the request boundary. +Use [Adding Scopes and Marks](/instrument-applications/adding-scopes-and-marks) and [Scopes](/about-nemo-flow/concepts/scopes) to verify that the root scope matches the request boundary. ## Middleware Does Not Run Check whether the middleware was registered globally or scope-locally. Scope-local middleware is visible only to the owning scope and descendant scopes, and it is cleaned up when the owning scope closes. -Use [Middleware](../about/concepts/middleware.md), [Add Middleware](../instrument-applications/advanced-guide.md), and [Instrument Applications Code Examples](../instrument-applications/code-examples.md#middleware-registration-families) to verify the expected registration family. +Use [Middleware](/about-nemo-flow/concepts/middleware), [Add Middleware](/instrument-applications/advanced-guide), and [Instrument Applications Code Examples](/instrument-applications/code-examples#middleware-registration-families) to verify the expected registration family. ## Middleware Runs In The Wrong Order Middleware runs by priority after the runtime merges global middleware with scope-local middleware from the active scope chain. If the order is surprising, check the priority assigned to each middleware entry and confirm that similarly named global and scope-local entries are registered in the intended registry. -Use [Middleware](../about/concepts/middleware.md) and [Instrument Applications Code Examples](../instrument-applications/code-examples.md#middleware-registration-families) to compare registration names, priorities, and scope ownership. +Use [Middleware](/about-nemo-flow/concepts/middleware) and [Instrument Applications Code Examples](/instrument-applications/code-examples#middleware-registration-families) to compare registration names, priorities, and scope ownership. ## Guardrail Rejections Stop Calls A guardrail rejection is expected to stop the protected tool or LLM call. Inspect the guardrail result and confirm whether the guardrail was intended to sanitize input, sanitize output, or reject the request completely. -Use [Add Middleware](../instrument-applications/advanced-guide.md) to verify the guardrail family and expected behavior. +Use [Add Middleware](/instrument-applications/advanced-guide) to verify the guardrail family and expected behavior. ## Request Intercept Changes Are Not Visible Request intercepts transform the request before execution. If the original value still appears downstream, confirm that the intercept returns the changed value in the binding-specific shape and that a later request intercept is not replacing it. -Use [Instrument Applications Code Examples](../instrument-applications/code-examples.md#middleware-registration-families) to compare the expected request intercept callback signature for the binding. +Use [Instrument Applications Code Examples](/instrument-applications/code-examples#middleware-registration-families) to compare the expected request intercept callback signature for the binding. ## Execution Intercept Hangs Or Skips The Original Call Execution intercepts use a middleware-chain pattern. An intercept that never calls `next` intentionally short-circuits the original callable, while an intercept that awaits or calls `next` incorrectly can hang the request. -Use [Middleware](../about/concepts/middleware.md) to confirm when an execution intercept should call `next`, replace the result, or stop the chain. +Use [Middleware](/about-nemo-flow/concepts/middleware) to confirm when an execution intercept should call `next`, replace the result, or stop the chain. ## Subscribers Do Not Receive Events Confirm that the subscriber is registered before the runtime emits the events you expect. For scope-local subscribers, confirm that the active scope is the owning scope or a descendant scope. -Use [Subscribers](../about/concepts/subscribers.md), [Events](../about/concepts/events.md), and [Observability](../plugins/observability/about.md) to verify lifecycle timing and event names. +Use [Subscribers](/about-nemo-flow/concepts/subscribers), [Events](/about-nemo-flow/concepts/events), and [Observability](/observability-plugin/about) to verify lifecycle timing and event names. ## Events Are Missing Expected Fields Managed tool and LLM helpers populate semantic fields such as inputs, outputs, model names, and tool call IDs. Manual lifecycle calls require you to provide the relevant params explicitly. -Use [Events](../about/concepts/events.md) and [Instrument Applications Code Examples](../instrument-applications/code-examples.md) to verify the emitted payload shape. +Use [Events](/about-nemo-flow/concepts/events) and [Instrument Applications Code Examples](/instrument-applications/code-examples) to verify the emitted payload shape. ## Agent Trajectory Interchange Format (ATIF) Export Is Empty Or Mixed Across Agents @@ -129,35 +130,35 @@ exporter subscribed after the relevant events were emitted, or the export filter does not match the active `root_uuid`. Mixed trajectories usually mean multiple agents share a root scope or the export did not filter by root scope. -Use [Agent Trajectory Interchange Format (ATIF)](../plugins/observability/atif.md) -and [Observability](../plugins/observability/about.md) to confirm exporter +Use [Agent Trajectory Interchange Format (ATIF)](/observability-plugin/atif) +and [Observability](/observability-plugin/about) to confirm exporter setup, event collection timing, and root-scope filtering. ## LLM Stream Output Is Missing The Final Chunk When wrapping streamed LLM responses, confirm that the stream wrapper receives the provider's terminal event and that the application drains the stream until completion. A stream that is dropped early can prevent finalizers, collectors, or subscribers from seeing the completed output. -Use [Wrap LLM Calls](../integrate-frameworks/wrap-llm-calls.md) and [Provider Response Codecs](../integrate-frameworks/provider-response-codecs.md) to verify the expected stream event format. +Use [Wrap LLM Calls](/integrate-into-frameworks/wrap-llm-calls) and [Provider Response Codecs](/integrate-into-frameworks/provider-response-codecs) to verify the expected stream event format. ## Provider Payloads Fail To Convert JSON conversion errors usually mean the integration passed a value that cannot be represented in NeMo Flow's JSON model, such as functions, class instances, handles, or provider-specific streaming objects. -Use [Non-Serializable Data](../integrate-frameworks/non-serializable-data.md), [Provider Codecs](../integrate-frameworks/provider-codecs.md), and [Using Codecs](../integrate-frameworks/using-codecs.md) to define explicit conversions for provider-specific payloads. +Use [Non-Serializable Data](/integrate-into-frameworks/non-serializable-data), [Provider Codecs](/integrate-into-frameworks/provider-codecs), and [Using Codecs](/integrate-into-frameworks/using-codecs) to define explicit conversions for provider-specific payloads. ## Plugin Configuration Does Not Validate If a plugin fails before runtime execution, validate configuration separately from behavior registration. Check required fields, value types, defaults, and whether the plugin is reading configuration from the expected source. -Use [Validate Configuration](../build-plugins/validate-configuration.md), [Advanced Configuration](../build-plugins/advanced-configuration.md), and [Register Behavior](../build-plugins/register-behavior.md) to isolate configuration problems from runtime behavior problems. +Use [Validate Plugin Configuration](/build-plugins/validate-configuration), [Design Plugin Configuration](/build-plugins/advanced-configuration), and [Register Plugin Behavior](/build-plugins/register-behavior) to isolate configuration problems from runtime behavior problems. ## Adaptive Optimization Does Not Change Behavior Confirm that adaptive optimization is configured for the component you expect and that the runtime path actually reaches that component. If behavior does not change, check whether the configured policy is disabled, scoped too narrowly, or not connected to the call path under test. -Use [Adaptive Configuration](../plugins/adaptive/configuration.md), -[Adaptive Cache Governor (ACG)](../plugins/adaptive/acg.md), and -[Adaptive Hints](../plugins/adaptive/adaptive-hints.md) to verify component +Use [Adaptive Configuration](/adaptive-plugin/configuration), +[Adaptive Cache Governor (ACG)](/adaptive-plugin/acg), and +[Adaptive Hints](/adaptive-plugin/adaptive-hints) to verify component names and configuration scope. ## Third-Party Patch Does Not Apply @@ -174,4 +175,4 @@ If the patch still does not apply, confirm that the local checkout is clean and First reproduce the behavior through the closest core or binding-level API. If the core API behaves correctly, inspect the integration wrapper, codec, or provider adapter that translates provider calls into NeMo Flow calls. -Use [Integrate Frameworks](../integrate-frameworks/about.md), [Wrap Tool Calls](../integrate-frameworks/wrap-tool-calls.md), and [Wrap LLM Calls](../integrate-frameworks/wrap-llm-calls.md) to compare the integration path with the core runtime path. +Use [Integrate Frameworks](/integrate-into-frameworks/about), [Wrap Tool Calls](/integrate-into-frameworks/wrap-tool-calls), and [Wrap LLM Calls](/integrate-into-frameworks/wrap-llm-calls) to compare the integration path with the core runtime path. diff --git a/docs/typedoc.node.json b/docs/typedoc.node.json deleted file mode 100644 index 65c627f6..00000000 --- a/docs/typedoc.node.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "$schema": "https://typedoc.org/schema.json", - "name": "NeMo Flow Node.js API", - "excludeInternal": true, - "excludePrivate": true, - "excludeProtected": true, - "sort": ["source-order"] -} diff --git a/docs/typedoc.node.tsconfig.json b/docs/typedoc.node.tsconfig.json deleted file mode 100644 index 889f77ad..00000000 --- a/docs/typedoc.node.tsconfig.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "compilerOptions": { - "target": "ES2022", - "module": "NodeNext", - "moduleResolution": "NodeNext", - "skipLibCheck": true, - "strict": false - }, - "include": ["reference/api/nodejs/_generated/source/*.ts", "reference/api/nodejs/_generated/source/declarations/*.d.ts"] -} diff --git a/examples/nemoguardrails/README.md b/examples/nemoguardrails/README.md index 5242ef51..ed96e5ec 100644 --- a/examples/nemoguardrails/README.md +++ b/examples/nemoguardrails/README.md @@ -152,5 +152,5 @@ The script also accepts `NVIDIA_MODEL`, `NVIDIA_BASE_URL`, and `NEMO_GUARDRAILS_TOOL` as environment variable equivalents for the config lane, config path, and tool selection. -See [NeMo Guardrails Example Plugin](../../docs/build-plugins/nemoguardrails.md) +See [NeMo Guardrails Example Plugin](../../docs/build-plugins/nemoguardrails.mdx) for the full configuration and limitation notes. diff --git a/fern/assets/NVIDIA_dark.svg b/fern/assets/NVIDIA_dark.svg new file mode 100644 index 00000000..fe67b898 --- /dev/null +++ b/fern/assets/NVIDIA_dark.svg @@ -0,0 +1,37 @@ + + + + + + + + + + + + + + + + + + + + + diff --git a/fern/assets/NVIDIA_light.svg b/fern/assets/NVIDIA_light.svg new file mode 100644 index 00000000..568ee177 --- /dev/null +++ b/fern/assets/NVIDIA_light.svg @@ -0,0 +1,36 @@ + + + + + + + + + + + + + + + + + + + + + diff --git a/fern/assets/NVIDIA_symbol.svg b/fern/assets/NVIDIA_symbol.svg new file mode 100644 index 00000000..fd57037f --- /dev/null +++ b/fern/assets/NVIDIA_symbol.svg @@ -0,0 +1,24 @@ + + + + + + + + + + + + + + + + + diff --git a/fern/components/Authors.tsx b/fern/components/Authors.tsx new file mode 100644 index 00000000..0c711979 --- /dev/null +++ b/fern/components/Authors.tsx @@ -0,0 +1,56 @@ +/** + * SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + * SPDX-License-Identifier: Apache-2.0 + */ + +/** + * Authors - Renders author byline with avatars for dev notes / blog posts. + * + * Uses authors data from components/devnotes/authors-data.ts (synced with .authors.yml). + * NOTE: Fern's custom component pipeline uses the automatic JSX runtime. + * + * Usage in MDX (authors from frontmatter): + * --- + * authors: + * - jdoe + * - asmith + * --- + * + * import { Authors } from "@/components/Authors"; + * + */ + +import { authors } from "./devnotes/authors-data"; + +export interface AuthorsProps { + /** Author IDs from .authors.yml. From frontmatter: ids={authors} */ + ids?: string[]; +} + +export const Authors = ({ ids }: AuthorsProps) => { + const validAuthors = (ids ?? []) + .map((id) => authors[id]) + .filter(Boolean); + + if (validAuthors.length === 0) return null; + + return ( +
    + {validAuthors.map((author, i) => ( +
    + +
    + {author.name} + {author.description} +
    +
    + ))} +
    + ); +}; diff --git a/fern/components/BadgeLinks.tsx b/fern/components/BadgeLinks.tsx new file mode 100644 index 00000000..c4a5949c --- /dev/null +++ b/fern/components/BadgeLinks.tsx @@ -0,0 +1,37 @@ +/** + * SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + * SPDX-License-Identifier: Apache-2.0 + */ + +/** + * Badge links for GitHub, License, PyPI, etc. + * Uses a custom wrapper to avoid Fern's external-link icon stacking under badges. + * + * `badges` is required — there is intentionally no default. A previous + * version shipped placeholder URLs that could land in production for + * sites that rendered the component without props. See README-BadgeLinks.md. + */ +export type BadgeItem = { + href: string; + src: string; + alt: string; +}; + +export interface BadgeLinksProps { + badges: BadgeItem[]; +} + +export function BadgeLinks({ badges }: BadgeLinksProps) { + return ( +
    + {badges.map((b) => ( + + {b.alt} + + ))} +
    + ); +} diff --git a/fern/components/CustomFooter.tsx b/fern/components/CustomFooter.tsx new file mode 100644 index 00000000..db2d9da6 --- /dev/null +++ b/fern/components/CustomFooter.tsx @@ -0,0 +1,96 @@ +/** + * SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + * SPDX-License-Identifier: LicenseRef-NvidiaProprietary + */ + +/** + * Custom footer for NVIDIA docs (Fern native header/footer). + * Markup and class names match the original custom-app footer 1:1 so that + * fern/main.css (footer + Built with Fern styles) applies correctly: + * dark mode logo, responsive layout, and Built with Fern tooltip. + */ +export default function CustomFooter() { + const currentYear = new Date().getFullYear(); + const logoUrl = + "https://fern-image-hosting.s3.us-east-1.amazonaws.com/nvidia/NVIDIA_Logo_0.svg"; + + return ( + + ); +} diff --git a/fern/components/MetricsTable.tsx b/fern/components/MetricsTable.tsx new file mode 100644 index 00000000..f95dc186 --- /dev/null +++ b/fern/components/MetricsTable.tsx @@ -0,0 +1,106 @@ +/** + * SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + * SPDX-License-Identifier: Apache-2.0 + */ + +/** + * MetricsTable - Styled comparison table for benchmark results. + * + * Optional: highlights best values per column (bold). + * NOTE: Fern's custom component pipeline uses the automatic JSX runtime. + * Do NOT import React -- the `react` module is not resolvable in Fern's build. + * + * Usage in MDX: + * import { MetricsTable } from "@/components/MetricsTable"; + * + * + */ + +export interface MetricsTableProps { + headers: string[]; + rows: (string | number)[][]; + /** Column indices where lower is better (for highlighting) */ + lowerIsBetter?: number[]; + /** Column indices where higher is better (default for non-lowerIsBetter) */ + higherIsBetter?: number[]; +} + +function findBestIndices( + rows: (string | number)[][], + colIndex: number, + lowerIsBetter: boolean +): Set { + const values = rows.map((r) => { + const v = r[colIndex]; + if (typeof v === "number") return v; + const parsed = parseFloat(String(v)); + return isNaN(parsed) ? (lowerIsBetter ? Infinity : -Infinity) : parsed; + }); + const best = lowerIsBetter ? Math.min(...values) : Math.max(...values); + const bestIndices = new Set(); + values.forEach((v, i) => { + if (v === best) bestIndices.add(i); + }); + return bestIndices; +} + +export const MetricsTable = ({ + headers, + rows, + lowerIsBetter = [], + higherIsBetter = [], +}: MetricsTableProps) => { + const lowerSet = new Set(lowerIsBetter); + const bestByCol: Record> = {}; + + for (let c = 0; c < headers.length; c++) { + if (lowerSet.has(c)) { + bestByCol[c] = findBestIndices(rows, c, true); + } else if (higherIsBetter.includes(c)) { + bestByCol[c] = findBestIndices(rows, c, false); + } else { + const numLike = rows.every((r) => { + const v = r[c]; + return typeof v === "number" || !isNaN(parseFloat(String(v))); + }); + if (numLike) { + bestByCol[c] = findBestIndices(rows, c, false); + } + } + } + + return ( +
    + + + + {headers.map((h, i) => ( + + ))} + + + + {rows.map((row, rowIdx) => ( + + {row.map((cell, colIdx) => { + const isBest = bestByCol[colIdx]?.has(rowIdx); + return ( + + ); + })} + + ))} + +
    {h}
    + {cell} +
    +
    + ); +}; diff --git a/fern/components/NotebookViewer.tsx b/fern/components/NotebookViewer.tsx new file mode 100644 index 00000000..df73cea2 --- /dev/null +++ b/fern/components/NotebookViewer.tsx @@ -0,0 +1,399 @@ +/** + * SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + * SPDX-License-Identifier: Apache-2.0 + */ + +import type { ReactNode } from "react"; + +/** + * NotebookViewer - Renders Jupyter notebook content in Fern docs. + * + * Uses Fern's code block structure (fern-code, fern-code-block, etc.) so input + * and output cells match the default Fern code block styling. + * + * Accepts notebook cells (markdown + code) and optionally a Colab URL. + * Designed to work with notebooks converted via `scripts/converters/ipynb_to_fern_json.py` + * (NeMo Data Designer–compatible pipeline; sources may be plain `.ipynb` or Jupytext). + * + * NOTE: Fern's custom component pipeline uses the automatic JSX runtime. + * Only type-only imports from "react" are used (erased at compile time). + * + * Usage in MDX: + * import { NotebookViewer } from "@/components/NotebookViewer"; + * import notebook from "@/components/notebooks/1-the-basics"; + * + * + */ + +export interface CellOutput { + type: "text" | "image"; + data: string; + format?: "plain" | "html"; +} + +export interface NotebookCell { + type: "markdown" | "code"; + source: string; + /** Pre-rendered syntax-highlighted HTML (from Pygments). When present, used instead of escaped source. */ + source_html?: string; + language?: string; + outputs?: CellOutput[]; +} + +export interface NotebookData { + cells: NotebookCell[]; +} + +export interface NotebookViewerProps { + /** Notebook data with cells array. If import fails, this may be undefined. */ + notebook?: NotebookData | null; + /** Optional Colab URL for "Run in Colab" badge */ + colabUrl?: string; + /** Show code cell outputs (default: true) */ + showOutputs?: boolean; +} + +function NotebookViewerError({ message, detail }: { message: string; detail?: string }) { + return ( +
    + NotebookViewer error: {message} + {detail && ( + 
    +          {detail}
+
    + )} +
    + ); +} + +function escapeHtml(text: string): string { + if (typeof text !== "string") return ""; + return text + .replace(/&/g, "&") + .replace(//g, ">") + .replace(/"/g, """); +} + +// Sprint 4.2: markdown is rendered server-side in ipynb_to_fern_json.py +// (markdown-it-py) and emitted as cell.source_html. The component renders +// that HTML directly. The hand-rolled JS parser previously here mishandled +// blockquotes, fenced code, tables, and nested lists; it has been removed. + +function handleCopy(content: string, button: HTMLButtonElement) { + navigator.clipboard.writeText(content).catch(() => {}); + const originalHtml = button.innerHTML; + const originalLabel = button.getAttribute("aria-label") ?? "Copy code"; + button.innerHTML = "Copied!"; + button.setAttribute("aria-label", "Copied to clipboard"); + setTimeout(() => { + button.innerHTML = originalHtml; + button.setAttribute("aria-label", originalLabel); + }, 1500); +} + +const FLAG_ICON = ( + + + + +); + +const SCROLL_AREA_STYLE = `[data-radix-scroll-area-viewport]{scrollbar-width:none;-ms-overflow-style:none;-webkit-overflow-scrolling:touch;}[data-radix-scroll-area-viewport]::-webkit-scrollbar{display:none}`; + +const BUTTON_BASE_CLASS = + "focus-visible:ring-(color:--accent) rounded-2 inline-flex items-center justify-center gap-2 whitespace-nowrap text-sm font-medium transition-colors hover:transition-none focus-visible:outline-none focus-visible:ring-1 disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0 text-(color:--grayscale-a11) hover:bg-(color:--accent-a3) hover:text-(color:--accent-11) pointer-coarse:size-9 size-7"; + +/** Fern code block structure – matches Fern docs (header with language + buttons, pre with scroll area). */ +function FernCodeBlock({ + title, + children, + className = "", + asPre = true, + copyContent, + showLineNumbers = false, + codeHtml, +}: { + title: string; + children: ReactNode; + className?: string; + /** Use div instead of pre for content (needed when children include block elements like img/div). */ + asPre?: boolean; + /** Raw text to copy when copy button is clicked. When provided, shows a copy button. */ + copyContent?: string; + /** Show line numbers in a table layout (matches Fern's code block structure). */ + showLineNumbers?: boolean; + /** Pre-rendered HTML for each line when showLineNumbers is true. Lines are split by newline. */ + codeHtml?: string; +}) { + const headerLabel = title === "Output" ? "Output" : title.charAt(0).toUpperCase() + title.slice(1); + const wrapperClasses = + "fern-code fern-code-block bg-card-background border-card-border rounded-3 shadow-card-grayscale relative mb-6 mt-4 flex w-full min-w-0 max-w-full flex-col border first:mt-0"; + const preStyle = { + backgroundColor: "rgb(255, 255, 255)", + ["--shiki-dark-bg" as string]: "#212121", + color: "rgb(36, 41, 46)", + ["--shiki-dark" as string]: "#EEFFFF", + }; + + const scrollAreaContent = () => { + if (codeHtml == null) return null; + const lines = codeHtml.split("\n"); + return ( +
    +