diff --git a/.config/typedoc.css b/.config/typedoc.css new file mode 100644 index 0000000..b40e4d0 --- /dev/null +++ b/.config/typedoc.css @@ -0,0 +1,212 @@ +.tsd-typography h4, +.tsd-typography .tsd-index-panel h3, +.tsd-index-panel .tsd-typography h3, +.tsd-typography h5, +.tsd-typography h6 { + margin: 1.2em 0 0.4em 0; +} + +code { + padding: 4px 6px; + border-radius: 4px; +} + +pre { + border-radius: 4px; + padding: 8px 12px; + border: none; + overflow-x: auto; +} + +.tsd-page-toolbar { + border-bottom: none; + background: color-mix(in srgb, var(--color-background-secondary), transparent 20%); + box-shadow: 0px -148px 86px 86px #000000; +} + +.tsd-page-toolbar .tsd-toolbar-contents { + padding: 8px 2rem; +} + +.tsd-page-toolbar:before { + width: 100%; + position: absolute; + content: ""; + height: 100%; + z-index: -1; + backdrop-filter: blur(6px); +} + +@media (min-width: 1200px) { + .page-menu, + .site-menu { + top: 82px; + } +} + +.tsd-navigation a, +.tsd-navigation summary > span, +.tsd-page-navigation a { + margin: 4px 0px; + padding: 0.25rem 0.55rem 0.25rem 0.3rem; + border-radius: 4px; +}.tsd-navigation a:not(:has(> svg)), +.tsd-navigation summary > span:not(:has(> svg)), +.tsd-page-navigation a:not(:has(> svg)) { + padding: 0.25rem 0.55rem 0.25rem 0.4rem; +} + +.tsd-navigation a:hover, +.tsd-navigation summary > span:hover, +.tsd-page-navigation a:hover { + /*opacity: 0.8;*/ + text-decoration: none; + background-color: color-mix(in srgb, currentColor 12%, transparent); +} + +.tsd-navigation a.current, +.tsd-page-navigation a.current { + border-radius: 4px; +} +.tsd-navigation a.current:hover, +.tsd-page-navigation a.current:hover { + border-radius: 4px; + background-color: color-mix(in srgb, var(--color-active-menu-item), transparent 16%); +} + +pre { + position: relative; +} + +pre > button { + background-color: color-mix(in srgb, currentColor 12%, transparent); + border: none; + padding: 6px 12px; + border-radius: 4px; + cursor: pointer; + backdrop-filter: blur(6px); + max-height: calc(100% - 8px * 2); + display: flex; + flex-direction: row; + align-items: center; + box-sizing: border-box; + top: 8px; + right: 8px; +} +pre > button:hover { + background-color: color-mix(in srgb, currentColor 18%, transparent); +} + +h3 > svg { + vertical-align: middle; + margin-inline-end: 6px; + transform-origin: 48% 38%; +} + +h5 > svg { + vertical-align: middle; + margin-inline-end: 6px; + transform-origin: 48% 38%; +} + +#tsd-search { + border-radius: 4px; +} + +ul.tsd-hierarchy>li { + margin: 12px 0px; + list-style: disc; +} + +ul.tsd-hierarchy { + padding-inline-start: 24px; +} + +code.tsd-tag { + border: none; + box-shadow: 0px 0px 8px -2px var(--color-accent); +} + +h1 code.tsd-tag:first-of-type { + margin-left: 0.55em; +} + +.tsd-page-toolbar a.title:hover { + text-decoration: none; + background-color: color-mix(in srgb, currentColor 12%, transparent); + padding: 4px 8px; + margin: -4px -8px; + border-radius: 4px; +} + +a.tsd-index-link { + padding: 4px !important; +} + +a.tsd-index-link:hover { + text-decoration: none; + background-color: color-mix(in srgb, currentColor 12%, transparent); + border-radius: 8px; +} + +h1:not(.tsd-anchor-link, .tsd-returns-title) > a:hover, +h2:not(.tsd-anchor-link, .tsd-returns-title) > a:hover, +h3:not(.tsd-anchor-link, .tsd-returns-title) > a:hover, +h4:not(.tsd-anchor-link, .tsd-returns-title) > a:hover, +h5:not(.tsd-anchor-link, .tsd-returns-title) > a:hover, +h6:not(.tsd-anchor-link, .tsd-returns-title) > a:hover { + text-decoration: none; + color: var(--color-text); +} + +h1:not(.tsd-anchor-link, .tsd-returns-title) > a:hover:before, +h2:not(.tsd-anchor-link, .tsd-returns-title) > a:hover:before, +h3:not(.tsd-anchor-link, .tsd-returns-title) > a:hover:before, +h4:not(.tsd-anchor-link, .tsd-returns-title) > a:hover:before, +h5:not(.tsd-anchor-link, .tsd-returns-title) > a:hover:before, +h6:not(.tsd-anchor-link, .tsd-returns-title) > a:hover:before { + content: ""; + position: absolute; + height: calc(1ex + (1lh - 1ex)/2); + margin-top: calc(0.2 * 1ex); + margin-left: -8px; + width: 3px; + background-color: currentColor; + border-radius: 9999px; + opacity: 0.4; + pointer-events: none; +} + +#tsd-search.has-focus { + background-color: color-mix(in srgb, var(--color-accent), transparent 60%); +} + +#tsd-search .field input { + padding: 12px 16px; +} + +#tsd-search .results li { + padding: 0px 16px; +} + +#tsd-search .results li { + padding: 0px 16px; + background-color: color-mix(in srgb, var(--color-background), transparent 20%); +} + +#tsd-search .results li:nth-child(even) { + background-color: color-mix(in srgb, var(--color-background), transparent 20%); +} + +#tsd-search .results li.current, +#tsd-search .results li:hover { + background-color: color-mix(in srgb, var(--color-accent), transparent 20%); +} + +#tsd-search.has-focus .results { + backdrop-filter: blur(6px); +} + +.container-main { + margin-top: 16px; +} diff --git a/.config/typedoc.json b/.config/typedoc.json new file mode 100644 index 0000000..c72e7cc --- /dev/null +++ b/.config/typedoc.json @@ -0,0 +1,15 @@ +{ + "$schema": "https://typedoc.org/schema.json", + "entryPoints": ["../src/index.ts"], + "out": "../docs", + "tsconfig": "../tsconfig.json", + "customCss": "./typedoc.css", + "readme": "../README.md", + "excludeExternals": true, + "excludeInternal": true, + "excludePrivate": true, + "githubPages": true, + "hideGenerator": true, + "jsDocCompatibility": true, + "htmlLang": "en" +} diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 6dc7f0f..9ae6182 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -17,6 +17,8 @@ jobs: run: npm ci --ignore-scripts - name: Build run: npm run build + - name: Generate docs + run: npm run generate-docs - name: Download latest llama.cpp release run: node ./dist/cli/cli.js download --release latest --skipBuild - name: Upload build artifact @@ -24,6 +26,11 @@ jobs: with: name: "build" path: "dist" + - name: Upload build artifact + uses: actions/upload-artifact@v3 + with: + name: "docs" + path: "docs" - name: Upload llama.cpp artifact uses: actions/upload-artifact@v3 with: @@ -191,7 +198,12 @@ jobs: if: github.ref == 'refs/heads/master' runs-on: ubuntu-latest concurrency: release-${{ github.ref }} + environment: + name: npm + url: ${{ steps.set-npm-url.outputs.npm-url }} permissions: + pages: write + id-token: write contents: write issues: write pull-requests: write @@ -213,6 +225,7 @@ jobs: mkdir -p llamaBins mv artifacts/bins-*/* llamaBins/ mv artifacts/build dist/ + mv artifacts/docs docs/ echo "Built binaries:" ls llamaBins @@ -221,4 +234,20 @@ jobs: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} NPM_TOKEN: ${{ secrets.NPM_TOKEN }} run: npx semantic-release - + - name: Set npm package url to GITHUB_OUTPUT + id: set-npm-url + run: | + if [ -f .semanticRelease.npmPackage.deployedVersion.txt ]; then + echo "npm-url=https://www.npmjs.com/package/node-llama-cpp/v/$(cat .semanticRelease.npmPackage.deployedVersion.txt)" >> $GITHUB_OUTPUT + fi + - name: Upload docs to GitHub Pages + if: steps.set-npm-url.outputs.npm-url != '' + uses: actions/upload-pages-artifact@v2 + with: + name: pages-docs + path: docs + - name: Deploy docs to GitHub Pages + if: steps.set-npm-url.outputs.npm-url != '' + uses: actions/deploy-pages@v2 + with: + artifact_name: pages-docs diff --git a/.gitignore b/.gitignore index 7728c11..bb3e43a 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,7 @@ node_modules .DS_Store /dist +/docs /.env /.eslintcache diff --git a/.releaserc.json b/.releaserc.json index 6b295e8..ebf5123 100644 --- a/.releaserc.json +++ b/.releaserc.json @@ -12,6 +12,9 @@ }], "@semantic-release/release-notes-generator", "@semantic-release/npm", - "@semantic-release/github" + "@semantic-release/github", + ["@semantic-release/exec", { + "publishCmd": "echo \"${nextRelease.version}\" > .semanticRelease.npmPackage.deployedVersion.txt" + }] ] } diff --git a/README.md b/README.md index 2bc2cdb..150f258 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,8 @@ If binaries are not available for your platform, it'll fallback to download the To disable this behavior set the environment variable `NODE_LLAMA_CPP_SKIP_DOWNLOAD` to `true`. ## Documentation +### [API reference](https://withcatai.github.io/node-llama-cpp/modules.html) + ### Usage #### As a chatbot ```typescript @@ -129,7 +131,7 @@ console.log("AI: " + a1); ``` ### CLI -```txt +``` Usage: node-llama-cpp [options] Commands: @@ -140,11 +142,11 @@ Commands: Options: -h, --help Show help [boolean] - -v, --version Show version number [boolean] [boolean] + -v, --version Show version number [boolean] ``` #### `download` command -```txt +``` node-llama-cpp download Download a release of llama.cpp and compile it @@ -162,7 +164,7 @@ Options: ``` #### `build` command -```txt +``` node-llama-cpp build Compile the currently downloaded llama.cpp @@ -175,7 +177,7 @@ Options: ``` #### `clear` command -```txt +``` node-llama-cpp clear [type] Clear files created by llama-cli @@ -187,7 +189,7 @@ Options: ``` #### `chat` command -```txt +``` node-llama-cpp chat Chat with a LLama model diff --git a/package-lock.json b/package-lock.json index 9494ed1..dfcac0b 100644 --- a/package-lock.json +++ b/package-lock.json @@ -32,6 +32,7 @@ "devDependencies": { "@commitlint/cli": "^17.7.1", "@commitlint/config-conventional": "^17.7.0", + "@semantic-release/exec": "^6.0.3", "@types/bytes": "^3.1.1", "@types/cli-progress": "^3.11.0", "@types/cross-spawn": "^6.0.2", @@ -48,6 +49,7 @@ "semantic-release": "^21.0.7", "ts-node": "^10.9.1", "tslib": "^2.6.1", + "typedoc": "^0.24.8", "typescript": "^5.1.6", "zx": "^7.2.3" }, @@ -1268,6 +1270,57 @@ "node": ">=18" } }, + "node_modules/@semantic-release/exec": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/@semantic-release/exec/-/exec-6.0.3.tgz", + "integrity": "sha512-bxAq8vLOw76aV89vxxICecEa8jfaWwYITw6X74zzlO0mc/Bgieqx9kBRz9z96pHectiTAtsCwsQcUyLYWnp3VQ==", + "dev": true, + "dependencies": { + "@semantic-release/error": "^3.0.0", + "aggregate-error": "^3.0.0", + "debug": "^4.0.0", + "execa": "^5.0.0", + "lodash": "^4.17.4", + "parse-json": "^5.0.0" + }, + "engines": { + "node": ">=14.17" + }, + "peerDependencies": { + "semantic-release": ">=18.0.0" + } + }, + "node_modules/@semantic-release/exec/node_modules/@semantic-release/error": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/@semantic-release/error/-/error-3.0.0.tgz", + "integrity": "sha512-5hiM4Un+tpl4cKw3lV4UgzJj+SmfNIDCLLw0TepzQxz9ZGV5ixnqkzIVF+3tp0ZHgcMKE+VNGHJjEeyFG2dcSw==", + "dev": true, + "engines": { + "node": ">=14.17" + } + }, + "node_modules/@semantic-release/exec/node_modules/aggregate-error": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/aggregate-error/-/aggregate-error-3.1.0.tgz", + "integrity": "sha512-4I7Td01quW/RpocfNayFdFVk1qSuoh0E7JrbRJ16nH01HhKFQ88INq9Sd+nd72zqRySlr9BmDA8xlEJ6vJMrYA==", + "dev": true, + "dependencies": { + "clean-stack": "^2.0.0", + "indent-string": "^4.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/@semantic-release/exec/node_modules/clean-stack": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/clean-stack/-/clean-stack-2.2.0.tgz", + "integrity": "sha512-4diC9HaTE+KRAMWhDhrGOECgWZxoevMc5TlkObMqNSsVU62PYzXZ/SMTjzyGAFF1YusgxGcSWTEXBhp0CPwQ1A==", + "dev": true, + "engines": { + "node": ">=6" + } + }, "node_modules/@semantic-release/github": { "version": "9.0.4", "resolved": "https://registry.npmjs.org/@semantic-release/github/-/github-9.0.4.tgz", @@ -2295,6 +2348,12 @@ "node": ">=8" } }, + "node_modules/ansi-sequence-parser": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/ansi-sequence-parser/-/ansi-sequence-parser-1.1.1.tgz", + "integrity": "sha512-vJXt3yiaUL4UU546s3rPXlsry/RnM730G1+HkpKE012AN0sx1eOrxSu95oKDIonskeLTijMgqWZ3uDEe3NFvyg==", + "dev": true + }, "node_modules/ansi-styles": { "version": "4.3.0", "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", @@ -5375,6 +5434,12 @@ "json5": "lib/cli.js" } }, + "node_modules/jsonc-parser": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.2.0.tgz", + "integrity": "sha512-gfFQZrcTc8CnKXp6Y4/CBT3fTc0OVuDofpre4aEeEpSBPV5X5v4+Vmx+8snU7RLPrNHPKSgLxGo9YuQzz20o+w==", + "dev": true + }, "node_modules/jsonfile": { "version": "6.1.0", "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.1.0.tgz", @@ -5643,6 +5708,12 @@ "node": ">=10" } }, + "node_modules/lunr": { + "version": "2.3.9", + "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz", + "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==", + "dev": true + }, "node_modules/make-error": { "version": "1.3.6", "resolved": "https://registry.npmjs.org/make-error/-/make-error-1.3.6.tgz", @@ -10793,6 +10864,18 @@ "node": ">=8" } }, + "node_modules/shiki": { + "version": "0.14.3", + "resolved": "https://registry.npmjs.org/shiki/-/shiki-0.14.3.tgz", + "integrity": "sha512-U3S/a+b0KS+UkTyMjoNojvTgrBHjgp7L6ovhFVZsXmBGnVdQ4K4U9oK0z63w538S91ATngv1vXigHCSWOwnr+g==", + "dev": true, + "dependencies": { + "ansi-sequence-parser": "^1.1.0", + "jsonc-parser": "^3.2.0", + "vscode-oniguruma": "^1.7.0", + "vscode-textmate": "^8.0.0" + } + }, "node_modules/side-channel": { "version": "1.0.4", "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.0.4.tgz", @@ -11597,6 +11680,63 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/typedoc": { + "version": "0.24.8", + "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.24.8.tgz", + "integrity": "sha512-ahJ6Cpcvxwaxfu4KtjA8qZNqS43wYt6JL27wYiIgl1vd38WW/KWX11YuAeZhuz9v+ttrutSsgK+XO1CjL1kA3w==", + "dev": true, + "dependencies": { + "lunr": "^2.3.9", + "marked": "^4.3.0", + "minimatch": "^9.0.0", + "shiki": "^0.14.1" + }, + "bin": { + "typedoc": "bin/typedoc" + }, + "engines": { + "node": ">= 14.14" + }, + "peerDependencies": { + "typescript": "4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x" + } + }, + "node_modules/typedoc/node_modules/brace-expansion": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz", + "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", + "dev": true, + "dependencies": { + "balanced-match": "^1.0.0" + } + }, + "node_modules/typedoc/node_modules/marked": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/marked/-/marked-4.3.0.tgz", + "integrity": "sha512-PRsaiG84bK+AMvxziE/lCFss8juXjNaWzVbN5tXAm4XjeaS9NAHhop+PjQxz2A9h8Q4M/xGmzP8vqNwy6JeK0A==", + "dev": true, + "bin": { + "marked": "bin/marked.js" + }, + "engines": { + "node": ">= 12" + } + }, + "node_modules/typedoc/node_modules/minimatch": { + "version": "9.0.3", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.3.tgz", + "integrity": "sha512-RHiac9mvaRw0x3AYRgDC1CxAP7HTcNrrECeA8YYJeWnpo+2Q5CegtZjaotWTWxDG3UeGA1coE05iH1mPjT/2mg==", + "dev": true, + "dependencies": { + "brace-expansion": "^2.0.1" + }, + "engines": { + "node": ">=16 || 14 >=14.17" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, "node_modules/typescript": { "version": "5.1.6", "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.1.6.tgz", @@ -11744,6 +11884,18 @@ "spdx-expression-parse": "^3.0.0" } }, + "node_modules/vscode-oniguruma": { + "version": "1.7.0", + "resolved": "https://registry.npmjs.org/vscode-oniguruma/-/vscode-oniguruma-1.7.0.tgz", + "integrity": "sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA==", + "dev": true + }, + "node_modules/vscode-textmate": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/vscode-textmate/-/vscode-textmate-8.0.0.tgz", + "integrity": "sha512-AFbieoL7a5LMqcnOF04ji+rpXadgOXnZsxQr//r83kLPr7biP7am3g9zbaZIaBGwBRWeSvoMD4mgPdX3e4NWBg==", + "dev": true + }, "node_modules/web-streams-polyfill": { "version": "3.2.1", "resolved": "https://registry.npmjs.org/web-streams-polyfill/-/web-streams-polyfill-3.2.1.tgz", diff --git a/package.json b/package.json index 71354b2..f48ef53 100644 --- a/package.json +++ b/package.json @@ -44,6 +44,7 @@ "prepare": "[ $CI = true ] || [ -d '.husky/_' ] || husky install", "prebuild": "rm -rf ./dist ./tsconfig.tsbuildinfo", "build": "tsc --build tsconfig.json --force", + "generate-docs": "typedoc", "prewatch": "rm -rf ./dist ./tsconfig.tsbuildinfo", "watch": "tsc --build tsconfig.json --watch --force", "node-gyp-llama": "cd llama && node-gyp", @@ -79,10 +80,11 @@ "bugs": { "url": "https://github.com/withcatai/node-llama-cpp/issues" }, - "homepage": "https://github.com/withcatai/node-llama-cpp#readme", + "homepage": "https://withcatai.github.io/node-llama-cpp/", "devDependencies": { "@commitlint/cli": "^17.7.1", "@commitlint/config-conventional": "^17.7.0", + "@semantic-release/exec": "^6.0.3", "@types/bytes": "^3.1.1", "@types/cli-progress": "^3.11.0", "@types/cross-spawn": "^6.0.2", @@ -99,6 +101,7 @@ "semantic-release": "^21.0.7", "ts-node": "^10.9.1", "tslib": "^2.6.1", + "typedoc": "^0.24.8", "typescript": "^5.1.6", "zx": "^7.2.3" },