feat: new docs (#309)

* feat: Functionary v3 support
* feat: Mistral chat wrapper
* feat: move `seed` option to the prompt level
* feat: make `LlamaEmbedding` an object
* feat: `HF_TOKEN` support for reading GGUF file metadata
* feat: `inspect estimate` command
* feat(`TemplateChatWrapper`): custom history template for each message role
* feat: extract all prebuilt binaries to external modules
* feat: more helpful `inspect gpu` command
* feat: combine model downloaders
* feat: simplify `TokenBias`
* feat: simplify compatibility detection
* feat: better `threads` default value
* feat: improve Llama 3.1 chat template detection
* feat: `--gpuLayers max` and `--contextSize max` flag support for `inspect estimate` command
* feat: iterate all tokenizer tokens
* feat: failed context creation automatic remedy
* feat: abort generation in CLI commands
* feat(electron example template): update badge, scroll anchoring, table support
* refactor: move `download`, `build` and `clear` commands to be subcommands of a `source` command
* docs: new docs
* fix: adapt to `llama.cpp` sampling refactor
* fix: Llama 3.1 chat wrapper standard chat history
* fix: Llama 3 Instruct function calling
* fix: don't preload prompt in the `chat` command when using `--printTimings` or `--meter`
* fix: change `autoDisposeSequence` default to `false`
* fix: more stable Jinja template matching
* fix: improve performance of parallel evaluation from multiple contexts
* build(CI): resolve next version before release, update documentation website without a release
* build: only create a GitHub discussion on major or minor releases
* chore: update models list
* chore: remove unused field from `TokenMeter`

Author: giladgd

.config/typedoc.css

@@ -214,8 +214,8 @@ h6:not(.tsd-anchor-link, .tsd-returns-title) > a:hover:before {
     margin-top: 16px;
 }
 
-img[src$="assets/logo.roundEdges.png"],
-img[src$="assets/logo.png"] {
+img[src$="assets/logo.v3.roundEdges.png"],
+img[src$="assets/logo.v3.png"] {
     box-shadow: 0px 4px 12px 0px rgb(0 0 0 / 16%), 0px 8px 64px 0px rgb(0 0 0 / 24%);
     border-radius: 14px;
 }

.config/typedoc.json

@@ -1,6 +1,6 @@
 {
     "$schema": "https://typedoc.org/schema.json",
-    "entryPoints": ["../src/index.ts"],
+    "entryPoints": ["../src/apiDocsIndex.ts"],
     "out": "../docs/api",
     "tsconfig": "../tsconfig.json",
     "customCss": "./typedoc.css",
@@ -11,7 +11,7 @@
     "githubPages": true,
     "hideGenerator": true,
     "jsDocCompatibility": true,
-    "htmlLang": "en",
+    "lang": "en",
     "plugin": ["typedoc-plugin-markdown", "typedoc-vitepress-theme", "typedoc-plugin-mdn-links"],
     "hideBreadcrumbs": true,
     "hidePageHeader": true,
@@ -23,7 +23,10 @@
     "propertiesFormat": "list",
     "enumMembersFormat": "table",
     "typeDeclarationFormat": "list",
+    "classPropertiesFormat": "list",
+    "interfacePropertiesFormat": "list",
     "sort": ["source-order"],
     "docsRoot": "../docs",
-    "intentionallyNotExported": ["MergeOptionalUnionTypes", "GbnfJsonSchemaToTSType", "_LlamaText"]
+    "intentionallyNotExported": ["MergeOptionalUnionTypes", "GbnfJsonSchemaToTSType", "_LlamaText"],
+    "useHTMLEncodedBrackets": true
 }

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -39,6 +39,7 @@ body:
         Your bug can be investigated much faster if your code can be run without any dependencies other than `node-llama-cpp`.
         Issues without reproduction steps or code examples may be closed as not actionable.
         Please try to provide a Minimal, Complete, and Verifiable example ([link](http://stackoverflow.com/help/mcve)).
+        Please include a link to the model file you used if possible.
         Also, please enable enable debug logs by using `getLlama({debug: true})` to get more information.
       placeholder: >-
         Please try to provide a Minimal, Complete, and Verifiable example.

.github/ISSUE_TEMPLATE/config.yml

@@ -1,3 +1,4 @@
+blank_issues_enabled: false
 contact_links:
   - name: 🤔 Questions, General Support, and Help
     url: https://github.com/withcatai/node-llama-cpp/discussions

.github/PULL_REQUEST_TEMPLATE.md

@@ -29,4 +29,4 @@
 - [ ] This pull request links relevant issues as `Fixes #0000`
 - [ ] There are new or updated unit tests validating the change
 - [ ] Documentation has been updated to reflect this change
-- [ ] The new commits and pull request title follow conventions explained in [pull request guidelines](https://withcatai.github.io/node-llama-cpp/guide/contributing) (PRs that do not follow this convention will not be merged)
+- [ ] The new commits and pull request title follow conventions explained in [pull request guidelines](https://node-llama-cpp.withcat.ai/guide/contributing) (PRs that do not follow this convention will not be merged)

.github/workflows/build.yml

@@ -23,20 +23,23 @@ jobs:
       - name: Download latest llama.cpp release
         env:
           CI: true
-        run: node ./dist/cli/cli.js download --release b3543 --skipBuild --noBundle --noUsageExample --updateBinariesReleaseMetadataAndSaveGitBundle
+        run: node ./dist/cli/cli.js source download --release latest --skipBuild --noBundle --noUsageExample --updateBinariesReleaseMetadataAndSaveGitBundle
       - name: Upload build artifact
         uses: actions/upload-artifact@v4
         with:
+          include-hidden-files: true
           name: "build"
           path: "dist"
       - name: Upload packed templates artifact
         uses: actions/upload-artifact@v4
         with:
+          include-hidden-files: true
           name: "build-templates"
           path: "templates/packed"
       - name: Upload llama.cpp artifact
         uses: actions/upload-artifact@v4
         with:
+          include-hidden-files: true
           name: "llama.cpp"
           path: |
             llama/binariesGithubRelease.json
@@ -145,7 +148,7 @@ jobs:
       - name: Setup & Build
         id: build
         shell: bash
-        timeout-minutes: 80
+        timeout-minutes: 160
         env:
           ARTIFACT_NAME: ${{ matrix.config.artifact }}
         run: |
@@ -193,7 +196,7 @@ jobs:
           async function buildBinary(arch, flags = [], nodeTarget = nodeVersion) {
             console.log(`Building ${arch} for node ${nodeTarget} with flags`, flags);
             
-            await $`node ./dist/cli/cli.js build --ciMode --noUsageExample --arch ${arch} --nodeTarget ${nodeVersion} ${flags}`;
+            await $`node ./dist/cli/cli.js source build --ciMode --noUsageExample --arch ${arch} --nodeTarget ${nodeVersion} ${flags}`;
           }
           
           // build binaries
@@ -229,12 +232,12 @@ jobs:
           
           EOF
 
-      - name: Cache UPX
-        id: cache-upx
-        uses: actions/cache@v4
-        with:
-          path: "upxInstallations/**"
-          key: cache-upx-${{ runner.os }}-${{ github.workflow }}
+#      - name: Cache UPX
+#        id: cache-upx
+#        uses: actions/cache@v4
+#        with:
+#          path: "upxInstallations/**"
+#          key: cache-upx-${{ runner.os }}-${{ github.workflow }}
 
 #      - name: Compress CUDA binary on Windows
 #        if: matrix.config.name == 'Windows for x64'
@@ -280,9 +283,48 @@ jobs:
       - name: Publish artifact
         uses: actions/upload-artifact@v4
         with:
+          include-hidden-files: true
           name: "bins-${{ matrix.config.artifact }}"
           path: "bins/*"
 
+  resolve-next-release:
+    name: Resolve next release
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/beta')
+    runs-on: ubuntu-latest
+    permissions:
+      pages: read
+      id-token: write
+      contents: read
+      issues: read
+      pull-requests: read
+      discussions: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - name: Install modules
+        run: npm ci
+      - name: Resolve next release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: npx --no vite-node ./scripts/resolveNextReleaseVersion.ts --saveReleaseToFile ./semanticReleaseDryRunReleaseResult.json --saveVersionToFile ./resolvedNextVersion.txt
+      - name: Save next version output
+        run: echo "next-version=$(cat ./resolvedNextVersion.txt)" >> $GITHUB_ENV
+      - name: Update job summary
+        run: |
+          if [ "$(cat ./resolvedNextVersion.txt)" == "false" ]; then
+            echo "Next release version: `N/A`" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "Next release version: `$(cat ./resolvedNextVersion.txt)`" >> $GITHUB_STEP_SUMMARY
+          fi
+      - name: Upload resolved release artifact
+        uses: actions/upload-artifact@v4
+        with:
+          include-hidden-files: true
+          name: "resolved-next-release"
+          path: "./semanticReleaseDryRunReleaseResult.json"
+
   standalone-tests:
     name: Standalone tests
     runs-on: ubuntu-22.04
@@ -315,7 +357,7 @@ jobs:
         run: npm ci
 
       - name: Build binary
-        run: node ./dist/cli/cli.js build --noUsageExample
+        run: node ./dist/cli/cli.js source build --noUsageExample
 
       - name: Run standalone tests
         run: npm run test:standalone
@@ -354,7 +396,7 @@ jobs:
         run: npm ci
 
       - name: Build binary
-        run: node ./dist/cli/cli.js build --noUsageExample
+        run: node ./dist/cli/cli.js source build --noUsageExample
 
       - name: Cache models
         id: cache-test-models
@@ -371,7 +413,7 @@ jobs:
 
   release:
     name: Release
-    if: github.event_name == 'push' && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/beta')
+    if: needs.resolve-next-release.outputs.next-version != '' && needs.resolve-next-release.outputs.next-version != 'false'
     runs-on: ubuntu-latest
     concurrency: release-${{ github.ref }}
     environment:
@@ -385,6 +427,7 @@ jobs:
       pull-requests: write
       discussions: write
     needs:
+      - resolve-next-release
       - build
       - build-binaries
     outputs:
@@ -430,13 +473,16 @@ jobs:
         run: npx --no vite-node ./scripts/prepareStandalonePrebuiltBinaryModules.ts
       - name: Add "postinstall" script to package.json
         run: npm run addPostinstallScript
+      - name: Move semanticReleaseDryRunReleaseResult.json artifact
+        run: mv artifacts/resolved-next-release/semanticReleaseDryRunReleaseResult.json ./semanticReleaseDryRunReleaseResult.json
       - name: Release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
           GH_RELEASE_REF: ${{ github.ref }}
         run: |
           echo "//registry.npmjs.org/:_authToken=\${NPM_TOKEN}" > ~/.npmrc
+          export DRY_RUN_RESULT="$(cat ./semanticReleaseDryRunReleaseResult.json)"
           
           npx semantic-release
       - name: Set npm package url to GITHUB_OUTPUT
@@ -479,24 +525,20 @@ jobs:
           else
               npm publish
           fi
-      - name: Generate docs with updated version
-        if: steps.set-npm-url.outputs.npm-url != '' && github.ref == 'refs/heads/master'
-        env:
-          DOCS_URL_BASE: "/node-llama-cpp/"
-        run: |
-          export DOCS_PACKAGE_VERSION=$(cat .semanticRelease.npmPackage.deployedVersion.txt)
-          npm run docs:build
-      - name: Upload docs to GitHub Pages
-        if: steps.set-npm-url.outputs.npm-url != '' && github.ref == 'refs/heads/master'
-        uses: actions/upload-pages-artifact@v3
-        with:
-          name: pages-docs
-          path: docs-site
-      - name: Deploy docs to GitHub Pages
-        if: steps.set-npm-url.outputs.npm-url != '' && github.ref == 'refs/heads/master'
-        uses: actions/deploy-pages@v4
+
+  auto-approve-documentation-website-deployment:
+    name: Auto-approve documentation website deployment
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    needs:
+      - release
+    steps:
+      - name: Approve documentation website deployment
+        uses: activescott/automate-environment-deployment-approval@v1.0.6
         with:
-          artifact_name: pages-docs
+          github_token: ${{ secrets.AUTO_APPROVAL_GITHUB_TOKEN }}
+          environment_allow_list: "Documentation website"
+          actor_allow_list: giladgd
 
   build-electron-example:
     name: Build & release Electron app example - ${{ matrix.config.name }}
@@ -555,6 +597,7 @@ jobs:
       - name: Upload artifacts
         uses: actions/upload-artifact@v4
         with:
+          include-hidden-files: true
           name: "electron-app-example-${{ matrix.config.name }}"
           path: "./electron-app-example/release"
 
@@ -572,3 +615,87 @@ jobs:
           done
           
           shopt -u nullglob
+
+  update-documentation-website:
+    name: Update documentation website
+    if: |
+      always() &&
+      github.event_name == 'push' &&
+      (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/beta') &&
+      needs.build.result == 'success' &&
+      needs.resolve-next-release.result == 'success' &&
+      needs.resolve-next-release.outputs.next-version != '' && (
+        needs.resolve-next-release.outputs.next-version == 'false' ||
+        needs.release.result == 'skipped' || (
+          needs.release.result == 'success' &&
+          needs.release.outputs.package-version != ''
+        )
+      )
+    runs-on: ubuntu-latest
+    concurrency: update-documentation-website-${{ github.ref }}
+    environment:
+      name: Documentation website
+#      url: "https://node-llama-cpp.withcat.ai"
+    needs:
+      - build
+      - resolve-next-release
+      - release
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          lfs: true
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - name: Install modules
+        run: npm ci
+      - uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+      - name: Move artifacts
+        run: |
+          mv artifacts/build dist/
+          
+          cp -r artifacts/llama.cpp/llama.cpp llama/llama.cpp
+
+          rm -f ./llama/binariesGithubRelease.json
+          mv artifacts/llama.cpp/binariesGithubRelease.json ./llama/binariesGithubRelease.json
+
+          rm -f ./llama/llama.cpp.info.json
+          mv artifacts/llama.cpp/llama.cpp.info.json ./llama/llama.cpp.info.json
+      - name: Resolve docs version
+        env:
+          RELEASE_VERSION: ${{ needs.release.outputs.package-version || needs.resolve-next-release.outputs.next-version }}
+        run: |
+          if [ "$RELEASE_VERSION" == "false" ]; then
+            npx --no vite-node ./scripts/resolveLatestReleaseVersion.ts --saveVersionToFile ./docsVersion.txt
+          else
+            echo "$RELEASE_VERSION" > ./docsVersion.txt
+          fi
+      - name: Generate docs with updated version
+        env:
+          DOCS_URL_BASE: "/"
+        run: |
+          export DOCS_PACKAGE_VERSION="$(cat ./docsVersion.txt)"
+          echo "Package version: $DOCS_PACKAGE_VERSION"
+          
+          npm run docs:build
+      - name: Upload docs
+        uses: actions/upload-artifact@v4
+        with:
+          include-hidden-files: true
+          retention-days: 2
+          name: "docs-site"
+          path: docs-site
+#      - name: Upload docs to GitHub Pages
+#        uses: actions/upload-pages-artifact@v3
+#        with:
+#          name: pages-docs
+#          path: docs-site
+#      - name: Deploy docs to GitHub Pages
+#        uses: actions/deploy-pages@v4
+#        with:
+#          artifact_name: pages-docs
+#      - name: Update feed
+#        run: |
+#          curl -X POST "https://pubsubhubbub.appspot.com/" -H "Content-Type: application/x-www-form-urlencoded" --data-urlencode "hub.mode=publish" --data-urlencode "hub.url=https://node-llama-cpp.withcat.ai/blog/feed.atom"

.github/workflows/test.yml

@@ -35,5 +35,11 @@ jobs:
           node-version: "20"
       - name: Install modules
         run: npm ci
+      - name: Build
+        run: npm run build
+      - name: Download latest llama.cpp release
+        env:
+          CI: true
+        run: node ./dist/cli/cli.js source download --release latest --skipBuild --noBundle --noUsageExample --updateBinariesReleaseMetadataAndSaveGitBundle
       - name: Compile docs
         run: npm run docs:build

.gitignore

@@ -14,6 +14,7 @@ node_modules
 /.vitepress/.cache
 /test/.models
 /test/temp
+/temp
 /coverage
 
 /llama/compile_commands.json

.husky/commit-msg

@@ -1 +1 @@
-npx --no -- commitlint --edit "$1"
+commitlint --edit "$1"