From 0104f66c4d97438e16f202799cfa81f283ba737d Mon Sep 17 00:00:00 2001 From: dannyjameswilliams Date: Fri, 15 May 2026 15:19:36 +0100 Subject: [PATCH 1/3] added docs build, updated docstrings --- .github/workflows/release.yaml | 11 +- .gitignore | 1 + package.json | 3 + pnpm-lock.yaml | 173 +++++++++++++++++++++ src/query/agent.ts | 271 ++++++++++++++++++++++++++------- src/query/response/response.ts | 29 +++- 6 files changed, 432 insertions(+), 56 deletions(-) diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 3ece29f..5eb6087 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -7,7 +7,9 @@ on: - "*" permissions: - id-token: write + contents: read + id-token: write # to authenticate with OIDC when publishing to npm + pages: write # to deploy to Pages jobs: publish: @@ -23,3 +25,10 @@ jobs: version: 10 - run: pnpm install - run: pnpm publish --no-git-checks + - run: pnpm run docs + - name: "Upload docs as pages artifact" + uses: actions/upload-pages-artifact@v3 + with: + path: ./docs + - name: "Deploy the uploaded pages artifact" + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index f1501d0..20105f4 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ node_modules dist +docs .npmrc \ No newline at end of file diff --git a/package.json b/package.json index 2123122..7fb796e 100644 --- a/package.json +++ b/package.json @@ -12,6 +12,7 @@ "format": "prettier --check .", "build": "tsc", "test": "jest", + "docs": "typedoc --plugin typedoc-plugin-extras --out docs/ src/index.ts", "prepack": "pnpm build" }, "repository": { @@ -37,6 +38,8 @@ "jest": "^30.0.4", "prettier": "^3.6.2", "ts-jest": "^29.4.0", + "typedoc": "^0.28.15", + "typedoc-plugin-extras": "^4.0.1", "typescript": "^5.8.3", "typescript-eslint": "^8.32.1" } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 4663134..fedbffe 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -33,6 +33,12 @@ importers: ts-jest: specifier: ^29.4.0 version: 29.4.0(@babel/core@7.28.0)(@jest/transform@30.0.4)(@jest/types@30.0.1)(babel-jest@30.0.4(@babel/core@7.28.0))(jest-util@30.0.2)(jest@30.0.4(@types/node@22.15.18))(typescript@5.8.3) + typedoc: + specifier: ^0.28.15 + version: 0.28.19(typescript@5.8.3) + typedoc-plugin-extras: + specifier: ^4.0.1 + version: 4.0.1(typedoc@0.28.19(typescript@5.8.3)) typescript: specifier: ^5.8.3 version: 5.8.3 @@ -258,6 +264,9 @@ packages: resolution: {integrity: sha512-ZAoA40rNMPwSm+AeHpCq8STiNAwzWLJuP8Xv4CHIc9wv/PSuExjMrmjfYNj682vW0OOiZ1HKxzvjQr9XZIisQA==} engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + '@gerrit0/mini-shiki@3.23.0': + resolution: {integrity: sha512-bEMORlG0cqdjVyCEuU0cDQbORWX+kYCeo0kV1lbxF5bt4r7SID2l9bqsxJEM0zndaxpOUT7riCyIVEuqq/Ynxg==} + '@graphql-typed-document-node/core@3.2.0': resolution: {integrity: sha512-mB9oAsNCm9aM3/SOv4YtBMqZbYj10R7dkq8byBqxGY/ncFwhf2oQzMV+LCRlWoDSEBJ3COiR1yeDvMtsoOsuFQ==} peerDependencies: @@ -459,6 +468,21 @@ packages: '@protobufjs/utf8@1.1.0': resolution: {integrity: sha512-Vvn3zZrhQZkkBE8LSuW3em98c0FwgO4nxzv6OdSxPKJIEKY2bGbHn+mhGIPerzI4twdxaP8/0+06HBpwf345Lw==} + '@shikijs/engine-oniguruma@3.23.0': + resolution: {integrity: sha512-1nWINwKXxKKLqPibT5f4pAFLej9oZzQTsby8942OTlsJzOBZ0MWKiwzMsd+jhzu8YPCHAswGnnN1YtQfirL35g==} + + '@shikijs/langs@3.23.0': + resolution: {integrity: sha512-2Ep4W3Re5aB1/62RSYQInK9mM3HsLeB91cHqznAJMuylqjzNVAVCMnNWRHFtcNHXsoNRayP9z1qj4Sq3nMqYXg==} + + '@shikijs/themes@3.23.0': + resolution: {integrity: sha512-5qySYa1ZgAT18HR/ypENL9cUSGOeI2x+4IvYJu4JgVJdizn6kG4ia5Q1jDEOi7gTbN4RbuYtmHh0W3eccOrjMA==} + + '@shikijs/types@3.23.0': + resolution: {integrity: sha512-3JZ5HXOZfYjsYSk0yPwBrkupyYSLpAE26Qc0HLghhZNGTZg/SKxXIIgoxOpmmeQP0RRSDJTk1/vPfw9tbw+jSQ==} + + '@shikijs/vscode-textmate@10.0.2': + resolution: {integrity: sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==} + '@sinclair/typebox@0.34.38': resolution: {integrity: sha512-HpkxMmc2XmZKhvaKIZZThlHmx1L0I/V1hWK1NubtlFnr6ZqdiOpV72TKudZUNQjZNsyDBay72qFEhEvb+bcwcA==} @@ -486,6 +510,9 @@ packages: '@types/estree@1.0.7': resolution: {integrity: sha512-w28IoSUCJpidD/TGviZwwMJckNESJZXFu7NBZ5YJ4mEUnNraUn9Pm8HSZm/jDF1pDWYKspWE7oVphigUPRakIQ==} + '@types/hast@3.0.4': + resolution: {integrity: sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==} + '@types/istanbul-lib-coverage@2.0.6': resolution: {integrity: sha512-2QF/t/auWm0lsy8XtKVPG19v3sSOQlJe/YHZgfjb/KBBHOGSV+J2q/S671rcq9uTBrLAXmZpqJiaQbMT+zNU1w==} @@ -507,6 +534,9 @@ packages: '@types/stack-utils@2.0.3': resolution: {integrity: sha512-9aEbYZ3TbYMznPdcdr3SmIrLXwC/AKZXQeCf9Pgao5CKb8CyHuEX5jzWPTkvregvhRJHcpRO6BFoGW9ycaOkYw==} + '@types/unist@3.0.3': + resolution: {integrity: sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==} + '@types/yargs-parser@21.0.3': resolution: {integrity: sha512-I4q9QU9MQv4oEOz4tAHJtNz1cwuLxn2F3xcc2iV5WdqLPpUnj30aUuxt1mAxYTG+oe8CZMV/+6rU4S4gRDzqtQ==} @@ -602,41 +632,49 @@ packages: resolution: {integrity: sha512-34gw7PjDGB9JgePJEmhEqBhWvCiiWCuXsL9hYphDF7crW7UgI05gyBAi6MF58uGcMOiOqSJ2ybEeCvHcq0BCmQ==} cpu: [arm64] os: [linux] + libc: [glibc] '@unrs/resolver-binding-linux-arm64-musl@1.11.1': resolution: {integrity: sha512-RyMIx6Uf53hhOtJDIamSbTskA99sPHS96wxVE/bJtePJJtpdKGXO1wY90oRdXuYOGOTuqjT8ACccMc4K6QmT3w==} cpu: [arm64] os: [linux] + libc: [musl] '@unrs/resolver-binding-linux-ppc64-gnu@1.11.1': resolution: {integrity: sha512-D8Vae74A4/a+mZH0FbOkFJL9DSK2R6TFPC9M+jCWYia/q2einCubX10pecpDiTmkJVUH+y8K3BZClycD8nCShA==} cpu: [ppc64] os: [linux] + libc: [glibc] '@unrs/resolver-binding-linux-riscv64-gnu@1.11.1': resolution: {integrity: sha512-frxL4OrzOWVVsOc96+V3aqTIQl1O2TjgExV4EKgRY09AJ9leZpEg8Ak9phadbuX0BA4k8U5qtvMSQQGGmaJqcQ==} cpu: [riscv64] os: [linux] + libc: [glibc] '@unrs/resolver-binding-linux-riscv64-musl@1.11.1': resolution: {integrity: sha512-mJ5vuDaIZ+l/acv01sHoXfpnyrNKOk/3aDoEdLO/Xtn9HuZlDD6jKxHlkN8ZhWyLJsRBxfv9GYM2utQ1SChKew==} cpu: [riscv64] os: [linux] + libc: [musl] '@unrs/resolver-binding-linux-s390x-gnu@1.11.1': resolution: {integrity: sha512-kELo8ebBVtb9sA7rMe1Cph4QHreByhaZ2QEADd9NzIQsYNQpt9UkM9iqr2lhGr5afh885d/cB5QeTXSbZHTYPg==} cpu: [s390x] os: [linux] + libc: [glibc] '@unrs/resolver-binding-linux-x64-gnu@1.11.1': resolution: {integrity: sha512-C3ZAHugKgovV5YvAMsxhq0gtXuwESUKc5MhEtjBpLoHPLYM+iuwSj3lflFwK3DPm68660rZ7G8BMcwSro7hD5w==} cpu: [x64] os: [linux] + libc: [glibc] '@unrs/resolver-binding-linux-x64-musl@1.11.1': resolution: {integrity: sha512-rV0YSoyhK2nZ4vEswT/QwqzqQXw5I6CjoaYMOX0TqBlWhojUf8P94mvI7nuJTeaCkkds3QE4+zS8Ko+GdXuZtA==} cpu: [x64] os: [linux] + libc: [musl] '@unrs/resolver-binding-wasm32-wasi@1.11.1': resolution: {integrity: sha512-5u4RkfxJm+Ng7IWgkzi3qrFOvLvQYnPBmjmZQ8+szTK/b31fQCnleNl1GgEt7nIsZRIf5PLhPwT0WM+q45x/UQ==} @@ -743,6 +781,10 @@ packages: balanced-match@1.0.2: resolution: {integrity: sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==} + balanced-match@4.0.4: + resolution: {integrity: sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==} + engines: {node: 18 || 20 || >=22} + body-parser@2.2.0: resolution: {integrity: sha512-02qvAaxv8tp7fBa/mw1ga98OGm+eCbqzJOKoRt70sLmfEEi+jyBYVTDGfCL/k06/4EMk/z01gCe7HoCH/f2LTg==} engines: {node: '>=18'} @@ -753,6 +795,10 @@ packages: brace-expansion@2.0.1: resolution: {integrity: sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==} + brace-expansion@5.0.6: + resolution: {integrity: sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g==} + engines: {node: 18 || 20 || >=22} + braces@3.0.3: resolution: {integrity: sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==} engines: {node: '>=8'} @@ -929,6 +975,10 @@ packages: resolution: {integrity: sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==} engines: {node: '>= 0.8'} + entities@4.5.0: + resolution: {integrity: sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==} + engines: {node: '>=0.12'} + error-ex@1.3.2: resolution: {integrity: sha512-7dFHNmqeFSEt2ZBsCriorKnn3Z2pj+fd9kmI6QoWw4//DL+icEBfc0U7qJCisqrTsKTjw4fNFy2pW9OqStD84g==} @@ -1474,6 +1524,9 @@ packages: lines-and-columns@1.2.4: resolution: {integrity: sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==} + linkify-it@5.0.0: + resolution: {integrity: sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==} + locate-path@5.0.0: resolution: {integrity: sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==} engines: {node: '>=8'} @@ -1500,6 +1553,9 @@ packages: lru-cache@5.1.1: resolution: {integrity: sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==} + lunr@2.3.9: + resolution: {integrity: sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==} + make-dir@4.0.0: resolution: {integrity: sha512-hXdUTZYIVOt1Ex//jAQi+wTZZpUpwBj/0QsOzqegb3rGMMeJiSEu5xLHnYfBrRV4RH2+OCSOO95Is/7x1WJ4bw==} engines: {node: '>=10'} @@ -1510,10 +1566,17 @@ packages: makeerror@1.0.12: resolution: {integrity: sha512-JmqCvUhmt43madlpFzG4BQzG2Z3m6tvQDNKdClZnO3VbIudJYmxsT0FNJMeiB2+JTSlTQTSbU8QdesVmwJcmLg==} + markdown-it@14.1.1: + resolution: {integrity: sha512-BuU2qnTti9YKgK5N+IeMubp14ZUKUUw7yeJbkjtosvHiP0AZ5c8IAgEMk79D0eC8F23r4Ac/q8cAIFdm2FtyoA==} + hasBin: true + math-intrinsics@1.1.0: resolution: {integrity: sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==} engines: {node: '>= 0.4'} + mdurl@2.0.0: + resolution: {integrity: sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==} + media-typer@1.1.0: resolution: {integrity: sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw==} engines: {node: '>= 0.8'} @@ -1545,6 +1608,10 @@ packages: resolution: {integrity: sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg==} engines: {node: '>=6'} + minimatch@10.2.5: + resolution: {integrity: sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg==} + engines: {node: 18 || 20 || >=22} + minimatch@3.1.2: resolution: {integrity: sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==} @@ -1729,6 +1796,10 @@ packages: resolution: {integrity: sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==} engines: {node: '>= 0.10'} + punycode.js@2.3.1: + resolution: {integrity: sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==} + engines: {node: '>=6'} + punycode@2.3.1: resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==} engines: {node: '>=6'} @@ -1981,6 +2052,18 @@ packages: resolution: {integrity: sha512-OZs6gsjF4vMp32qrCbiVSkrFmXtG/AZhY3t0iAMrMBiAZyV9oALtXO8hsrHbMXF9x6L3grlFuwW2oAz7cav+Gw==} engines: {node: '>= 0.6'} + typedoc-plugin-extras@4.0.1: + resolution: {integrity: sha512-ab3T37ukHCwBjwBJpAcWdxy/XAaLdUyy5pwbgF9WDqCRN0DTJmJPLew9Kv6qrx5qnxiyfe6F4Og+PUp15kJWLw==} + peerDependencies: + typedoc: 0.27.x || 0.28.x + + typedoc@0.28.19: + resolution: {integrity: sha512-wKh+lhdmMFivMlc6vRRcMGXeGEHGU2g8a2CkPTJjJlwRf1iXbimWIPcFolCqe4E0d/FRtGszpIrsp3WLpDB8Pw==} + engines: {node: '>= 18', pnpm: '>= 10'} + hasBin: true + peerDependencies: + typescript: 5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x || 5.5.x || 5.6.x || 5.7.x || 5.8.x || 5.9.x || 6.0.x + typescript-eslint@8.32.1: resolution: {integrity: sha512-D7el+eaDHAmXvrZBy1zpzSNIRqnCOrkwTgZxTu3MUqRWk8k0q9m9Ho4+vPf7iHtgUfrK/o8IZaEApsxPlHTFCg==} engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} @@ -1993,6 +2076,9 @@ packages: engines: {node: '>=14.17'} hasBin: true + uc.micro@2.1.0: + resolution: {integrity: sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==} + undici-types@6.21.0: resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==} @@ -2068,6 +2154,11 @@ packages: yallist@3.1.1: resolution: {integrity: sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==} + yaml@2.9.0: + resolution: {integrity: sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==} + engines: {node: '>= 14.6'} + hasBin: true + yargs-parser@21.1.1: resolution: {integrity: sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==} engines: {node: '>=12'} @@ -2344,6 +2435,14 @@ snapshots: '@eslint/core': 0.13.0 levn: 0.4.1 + '@gerrit0/mini-shiki@3.23.0': + dependencies: + '@shikijs/engine-oniguruma': 3.23.0 + '@shikijs/langs': 3.23.0 + '@shikijs/themes': 3.23.0 + '@shikijs/types': 3.23.0 + '@shikijs/vscode-textmate': 10.0.2 + '@graphql-typed-document-node/core@3.2.0(graphql@16.11.0)': dependencies: graphql: 16.11.0 @@ -2649,6 +2748,26 @@ snapshots: '@protobufjs/utf8@1.1.0': {} + '@shikijs/engine-oniguruma@3.23.0': + dependencies: + '@shikijs/types': 3.23.0 + '@shikijs/vscode-textmate': 10.0.2 + + '@shikijs/langs@3.23.0': + dependencies: + '@shikijs/types': 3.23.0 + + '@shikijs/themes@3.23.0': + dependencies: + '@shikijs/types': 3.23.0 + + '@shikijs/types@3.23.0': + dependencies: + '@shikijs/vscode-textmate': 10.0.2 + '@types/hast': 3.0.4 + + '@shikijs/vscode-textmate@10.0.2': {} + '@sinclair/typebox@0.34.38': {} '@sinonjs/commons@3.0.1': @@ -2687,6 +2806,10 @@ snapshots: '@types/estree@1.0.7': {} + '@types/hast@3.0.4': + dependencies: + '@types/unist': 3.0.3 + '@types/istanbul-lib-coverage@2.0.6': {} '@types/istanbul-lib-report@3.0.3': @@ -2710,6 +2833,8 @@ snapshots: '@types/stack-utils@2.0.3': {} + '@types/unist@3.0.3': {} + '@types/yargs-parser@21.0.3': {} '@types/yargs@17.0.33': @@ -2959,6 +3084,8 @@ snapshots: balanced-match@1.0.2: {} + balanced-match@4.0.4: {} + body-parser@2.2.0: dependencies: bytes: 3.1.2 @@ -2982,6 +3109,10 @@ snapshots: dependencies: balanced-match: 1.0.2 + brace-expansion@5.0.6: + dependencies: + balanced-match: 4.0.4 + braces@3.0.3: dependencies: fill-range: 7.1.1 @@ -3119,6 +3250,8 @@ snapshots: encodeurl@2.0.0: {} + entities@4.5.0: {} + error-ex@1.3.2: dependencies: is-arrayish: 0.2.1 @@ -3887,6 +4020,10 @@ snapshots: lines-and-columns@1.2.4: {} + linkify-it@5.0.0: + dependencies: + uc.micro: 2.1.0 + locate-path@5.0.0: dependencies: p-locate: 4.1.0 @@ -3909,6 +4046,8 @@ snapshots: dependencies: yallist: 3.1.1 + lunr@2.3.9: {} + make-dir@4.0.0: dependencies: semver: 7.7.2 @@ -3919,8 +4058,19 @@ snapshots: dependencies: tmpl: 1.0.5 + markdown-it@14.1.1: + dependencies: + argparse: 2.0.1 + entities: 4.5.0 + linkify-it: 5.0.0 + mdurl: 2.0.0 + punycode.js: 2.3.1 + uc.micro: 2.1.0 + math-intrinsics@1.1.0: {} + mdurl@2.0.0: {} + media-typer@1.1.0: {} merge-descriptors@2.0.0: {} @@ -3942,6 +4092,10 @@ snapshots: mimic-fn@2.1.0: {} + minimatch@10.2.5: + dependencies: + brace-expansion: 5.0.6 + minimatch@3.1.2: dependencies: brace-expansion: 1.1.11 @@ -4108,6 +4262,8 @@ snapshots: forwarded: 0.2.0 ipaddr.js: 1.9.1 + punycode.js@2.3.1: {} + punycode@2.3.1: {} pure-rand@7.0.1: {} @@ -4349,6 +4505,19 @@ snapshots: media-typer: 1.1.0 mime-types: 3.0.1 + typedoc-plugin-extras@4.0.1(typedoc@0.28.19(typescript@5.8.3)): + dependencies: + typedoc: 0.28.19(typescript@5.8.3) + + typedoc@0.28.19(typescript@5.8.3): + dependencies: + '@gerrit0/mini-shiki': 3.23.0 + lunr: 2.3.9 + markdown-it: 14.1.1 + minimatch: 10.2.5 + typescript: 5.8.3 + yaml: 2.9.0 + typescript-eslint@8.32.1(eslint@9.26.0)(typescript@5.8.3): dependencies: '@typescript-eslint/eslint-plugin': 8.32.1(@typescript-eslint/parser@8.32.1(eslint@9.26.0)(typescript@5.8.3))(eslint@9.26.0)(typescript@5.8.3) @@ -4361,6 +4530,8 @@ snapshots: typescript@5.8.3: {} + uc.micro@2.1.0: {} + undici-types@6.21.0: {} unpipe@1.0.0: {} @@ -4462,6 +4633,8 @@ snapshots: yallist@3.1.1: {} + yaml@2.9.0: {} + yargs-parser@21.1.1: {} yargs@17.7.2: diff --git a/src/query/agent.ts b/src/query/agent.ts index 3c9cde7..1047745 100644 --- a/src/query/agent.ts +++ b/src/query/agent.ts @@ -27,7 +27,8 @@ import { getHeaders } from "./connection.js"; /** * An agent for executing agentic queries against Weaviate. - * For more information, see the [Weaviate Query Agent Docs](https://weaviate.io/developers/agents/query) + * + * For more information, see the [Weaviate Agents - Query Agent Docs](https://weaviate.io/developers/agents). */ export class QueryAgent { private collections?: (string | QueryAgentCollectionConfig)[]; @@ -35,10 +36,17 @@ export class QueryAgent { private agentsHost: string; /** - * Creates a new QueryAgent instance. + * Initialize the Query Agent. * - * @param client - The Weaviate client instance. - * @param options - Additional options for the QueryAgent. + * @param client - The Weaviate client connected to a Weaviate Cloud cluster. + * @param options - Configuration for the agent. + * @param options.collections - The collections to query. Either a list of strings, or a list of + * {@link QueryAgentCollectionConfig} objects. Will be overridden if passed in any of the agent's + * methods that support it. + * @param options.systemPrompt - Optional prompt to control the tone, format, and style of the + * agent's final response. This prompt is both passed to the query writer agent, and applied + * when generating the answer after all research and data retrieval is complete. + * @param options.agentsHost - Optional host of the agents service. */ constructor( private client: WeaviateClient, @@ -56,9 +64,11 @@ export class QueryAgent { /** * Run the query agent. * - * @deprecated Use {@link ask} instead. + * @deprecated The `run` method is deprecated; use {@link ask} instead. * @param query - The natural language query string for the agent. - * @param options - Additional options for the run. + * @param options - Options for this run. + * @param options.collections - The collections to query. Will override any collections passed in the constructor. + * @param options.context - Optional previous response from the agent. * @returns The response from the query agent. */ async run( @@ -99,11 +109,30 @@ export class QueryAgent { } /** - * Ask query agent a question. + * Run the Query Agent ask mode. * - * @param query - The natural language query string or conversation context for the agent. - * @param options - Additional options for the run. - * @returns The response from the query agent. + * Performs an agentic search on the collections and returns a natural language answer to the query. + * + * @param query - The natural language query string, or a list of chat messages, for the agent. + * @param options - Options for this ask invocation. + * @param options.collections - The collections to query. Either a list of strings, or a list of + * {@link QueryAgentCollectionConfig} objects. Will override any collections passed in the constructor. + * @param options.resultEvaluation - One of `"llm"` or `"none"`. + * If `"llm"`, the final answer will be cross-compared to the sources, and those sources will be + * filtered to only those in the answer. Also populates the `missingInformation` and + * `isPartialAnswer` fields of the response. + * If `"none"`, the result will not be evaluated, and the sources will not be filtered. + * Defaults to `"none"`. + * @returns An {@link AskModeResponse} which contains the final answer, sources, and other + * metadata such as the searches performed, usage and total time. + * + * @example + * ```ts + * const agent = new QueryAgent(client, { collections: ["FinancialContracts"] }); + * const response = await agent.ask( + * "What are the terms of the contract signed by John Smith in May 2025?", + * ); + * ``` */ async ask( query: QueryAgentQuery, @@ -134,10 +163,17 @@ export class QueryAgent { /** * Stream responses from the query agent. * - * @deprecated Use {@link askStream} instead. + * @deprecated The `stream` method is deprecated; use {@link askStream} instead. * @param query - The natural language query string for the agent. - * @param options - Additional options for the run. - * @returns The response from the query agent. + * @param options - Options for the stream. + * @param options.collections - The collections to query. Will override any collections passed in the constructor. + * @param options.context - Optional previous response from the agent. + * @param options.includeProgress - Whether to include progress messages in the stream. These are + * informational messages about the progress of the agent's search. + * @param options.includeFinalState - Whether to include the final state in the stream. This is + * the final {@link QueryAgentResponse}, yielded as the last item in the stream. + * @returns An async generator yielding {@link ProgressMessage}, {@link StreamedTokens}, and a + * final {@link QueryAgentResponse}, depending on the include flags. */ stream( query: string, @@ -232,11 +268,48 @@ export class QueryAgent { } /** - * Ask query agent a question and stream the response. + * Run the Query Agent ask mode and stream the response. * - * @param query - The natural language query string or conversation context for the agent. - * @param options - Additional options for the run. - * @returns The response from the query agent. + * @param query - The natural language query string, or a list of chat messages, for the agent. + * @param options - Options for the ask stream. + * @param options.collections - The collections to query. Either a list of strings, or a list of + * {@link QueryAgentCollectionConfig} objects. Will override any collections passed in the constructor. + * @param options.includeProgress - Whether to include progress messages in the stream. These are + * informational messages about the progress of the agent's search. + * @param options.includeFinalState - Whether to include the final state in the stream. This is + * the final {@link AskModeResponse}, yielded as the last item in the stream. + * @param options.resultEvaluation - One of `"llm"` or `"none"`. + * If `"llm"`, the final answer will be cross-compared to the sources, and those sources will be + * filtered to only those in the answer. Also populates the `missingInformation` and + * `isPartialAnswer` fields of the response. + * If `"none"`, the result will not be evaluated, and the sources will not be filtered. + * Defaults to `"none"`. + * @returns An async generator yielding any of the following: + * + * - {@link ProgressMessage}: informational messages about the progress of the agent's search + * (if `includeProgress` is `true`). + * - {@link StreamedTokens}: token deltas from the agent's response. + * - {@link AskModeResponse}: the final response, yielded as the last item in the stream + * (if `includeFinalState` is `true`). + * + * @example + * ```ts + * const agent = new QueryAgent(client, { collections: ["FinancialContracts"] }); + * for await (const event of agent.askStream( + * "What are the terms of the contract signed by John Smith in May 2025?", + * )) { + * if ("finalAnswer" in event) { + * // AskModeResponse + * console.log(event.finalAnswer); + * } else if ("delta" in event) { + * // StreamedTokens + * process.stdout.write(event.delta); + * } else { + * // ProgressMessage + * console.log(event.message); + * } + * } + * ``` */ askStream( query: QueryAgentQuery, @@ -329,9 +402,29 @@ export class QueryAgent { /** * Run the Query Agent search-only mode. * - * Sends the initial search request and returns the first page of results. - * The returned response includes a `next` method for pagination which - * reuses the same underlying searches to ensure consistency across pages. + * Sends the initial search request and returns a {@link SearchModeResponse} containing the + * first page of results. To paginate, call `response.next({ limit, offset })` on the returned + * response. This reuses the same underlying searches to ensure a consistent result set across + * pages. + * + * @param query - The natural language query string, or a list of chat messages, for the agent. + * @param options - Options for this search invocation. + * @param options.limit - The maximum number of results to return for the first page. Defaults to 20. + * @param options.collections - The collections to query. Either a list of strings, or a list of + * {@link QueryAgentCollectionConfig} objects. Will override any collections passed in the constructor. + * @param options.diversityWeight - Optional number between `0.0` and `1.0` to diversify results + * with MMR reranking. Higher values push for more topical variety at the cost of relevance. + * Defaults to no diversity. + * @returns A {@link SearchModeResponse} for the first page of results. Use + * `response.next({ limit, offset })` to paginate. + * + * @example + * ```ts + * const agent = new QueryAgent(client, { collections: ["FinancialContracts"] }); + * const page1 = await agent.search("Find all NDAs signed by Jane Doe in 2024.", { limit: 5 }); + * const page2 = await page1.next({ limit: 5, offset: 5 }); + * const page3 = await page2.next({ limit: 5, offset: 10 }); + * ``` */ async search( query: QueryAgentQuery, @@ -354,10 +447,30 @@ export class QueryAgent { } /** - * Suggest example queries that a user could run against the given collections. + * Suggest queries for the data in your collections. + * + * Uses the agent to generate example queries that can be run against the given collections. + * This can help users discover what kinds of questions they can ask, or generate example prompts + * for a dataset. + * + * @param options - Options for the suggest-queries request. + * @param options.collections - Optional override for the collections configured at instantiation. + * Either a list of strings, or a list of {@link QueryAgentCollectionConfig} objects. + * @param options.numQueries - The number of queries to suggest. Defaults to 3. + * @param options.instructions - Optional natural language guidance for the style, topic, or + * language of the suggested queries. Supplied in addition to the agent's system instructions. + * @returns A {@link SuggestQueryResponse} containing the list of suggested queries, along with + * additional metadata if present. * - * @param options - Options for the suggest queries request. - * @returns A list of suggested queries with usage information. + * @example + * ```ts + * const agent = new QueryAgent(client, { collections: ["FinancialContracts"] }); + * const suggestions = await agent.suggestQueries({ + * collections: ["Products"], + * numQueries: 5, + * instructions: "Focus on questions about eco-friendly features.", + * }); + * ``` */ async suggestQueries({ collections, @@ -402,82 +515,136 @@ export class QueryAgent { }; } -/** Options for the QueryAgent. */ +/** Options for constructing a {@link QueryAgent}. */ export type QueryAgentOptions = { - /** List of collections to query. Will be overriden if passed in the `run` method. */ + /** + * The collections to query. Either a list of strings, or a list of + * {@link QueryAgentCollectionConfig} objects. Will be overridden if passed in any of the + * agent's methods that support it. + */ collections?: QueryAgentCollection[]; - /** System prompt to guide the agent's behavior. */ + /** + * Optional prompt to control the tone, format, and style of the agent's final response. This + * prompt is both passed to the query writer agent, and applied when generating the answer + * after all research and data retrieval is complete. + */ systemPrompt?: string; - /** Host of the agents service. */ + /** Optional host of the agents service. */ agentsHost?: string; }; +/** The query for a Query Agent invocation. Either a natural language string or a list of chat messages. */ export type QueryAgentQuery = string | ChatMessage[]; +/** A single chat message in a conversation context passed to the Query Agent. */ export type ChatMessage = { role: "user" | "assistant"; content: string; }; -/** Options for the QueryAgent run. */ +/** + * Options for {@link QueryAgent.run}. + * + * @deprecated `run` is deprecated; use {@link QueryAgent.ask} with {@link QueryAgentAskOptions} instead. + */ export type QueryAgentRunOptions = { - /** List of collections to query. Will override any collections if passed in the constructor. */ + /** The collections to query. Will override any collections passed in the constructor. */ collections?: (string | QueryAgentCollectionConfig)[]; - /** Previous response from the agent. */ + /** Optional previous response from the agent. */ context?: QueryAgentResponse; }; -/** Controls how the agent evaluates the final result. */ +/** + * Controls how the agent evaluates the final result. + * + * - `"llm"`: cross-compares the final answer to the sources, filters those sources to only the + * ones used in the answer, and populates `missingInformation` and `isPartialAnswer`. + * - `"none"`: the result is not evaluated and sources are not filtered. + */ export type ResultEvaluation = "llm" | "none"; -/** Options for the QueryAgent ask. */ +/** Options for {@link QueryAgent.ask}. */ export type QueryAgentAskOptions = { - /** List of collections to query. Will override any collections if passed in the constructor. */ + /** + * The collections to query. Either a list of strings, or a list of + * {@link QueryAgentCollectionConfig} objects. Will override any collections passed in the constructor. + */ collections?: (string | QueryAgentCollectionConfig)[]; - /** How the agent should evaluate the final result. Defaults to `"none"`. */ + /** How the agent should evaluate the final result. See {@link ResultEvaluation}. Defaults to `"none"`. */ resultEvaluation?: ResultEvaluation; }; -/** Options for the QueryAgent stream. */ +/** + * Options for {@link QueryAgent.stream}. + * + * @deprecated `stream` is deprecated; use {@link QueryAgent.askStream} with {@link QueryAgentAskStreamOptions} instead. + */ export type QueryAgentStreamOptions = { - /** List of collections to query. Will override any collections if passed in the constructor. */ + /** The collections to query. Will override any collections passed in the constructor. */ collections?: (string | QueryAgentCollectionConfig)[]; - /** Previous response from the agent. */ + /** Optional previous response from the agent. */ context?: QueryAgentResponse; - /** Include progress messages in the stream. */ + /** + * Whether to include progress messages in the stream. These are informational messages about the + * progress of the agent's search. + */ includeProgress?: boolean; - /** Include final state in the stream. */ + /** + * Whether to include the final state in the stream. This is the final {@link QueryAgentResponse}, + * yielded as the last item in the stream. + */ includeFinalState?: boolean; }; -/** Options for the QueryAgent askStream. */ +/** Options for {@link QueryAgent.askStream}. */ export type QueryAgentAskStreamOptions = { - /** List of collections to query. Will override any collections if passed in the constructor. */ + /** + * The collections to query. Either a list of strings, or a list of + * {@link QueryAgentCollectionConfig} objects. Will override any collections passed in the constructor. + */ collections?: (string | QueryAgentCollectionConfig)[]; - /** Include progress messages in the stream. */ + /** + * Whether to include progress messages in the stream. These are informational messages about the + * progress of the agent's search. + */ includeProgress?: boolean; - /** Include final state in the stream. */ + /** + * Whether to include the final state in the stream. This is the final {@link AskModeResponse}, + * yielded as the last item in the stream. + */ includeFinalState?: boolean; - /** How the agent should evaluate the final result. Defaults to `"none"`. */ + /** How the agent should evaluate the final result. See {@link ResultEvaluation}. Defaults to `"none"`. */ resultEvaluation?: ResultEvaluation; }; -/** Options for the QueryAgent search-only run. */ +/** Options for {@link QueryAgent.search}. */ export type QueryAgentSearchOnlyOptions = { - /** The maximum number of results to return. */ + /** The maximum number of results to return for the first page. Defaults to 20. */ limit?: number; - /** List of collections to query. Will override any collections if passed in the constructor. */ + /** + * The collections to query. Either a list of strings, or a list of + * {@link QueryAgentCollectionConfig} objects. Will override any collections passed in the constructor. + */ collections?: (string | QueryAgentCollectionConfig)[]; - /** Weight for diversity in search results. */ + /** + * Optional number between `0.0` and `1.0` to diversify results with MMR reranking. Higher values + * push for more topical variety at the cost of relevance. Defaults to no diversity. + */ diversityWeight?: number; }; -/** Options for the QueryAgent suggest queries. */ +/** Options for {@link QueryAgent.suggestQueries}. */ export type QueryAgentSuggestQueriesOptions = { - /** List of collections to query. Will override any collections if passed in the constructor. */ + /** + * Optional override for the collections configured at instantiation. Either a list of strings, + * or a list of {@link QueryAgentCollectionConfig} objects. + */ collections?: (string | QueryAgentCollectionConfig)[]; - /** Number of queries to suggest. Defaults to 3. */ + /** The number of queries to suggest. Defaults to 3. */ numQueries?: number; - /** Optional instructions to guide query suggestion. */ + /** + * Optional natural language guidance for the style, topic, or language of the suggested queries. + * Supplied in addition to the agent's system instructions. + */ instructions?: string; }; diff --git a/src/query/response/response.ts b/src/query/response/response.ts index c24bbd1..462f655 100644 --- a/src/query/response/response.ts +++ b/src/query/response/response.ts @@ -332,19 +332,42 @@ export type WeaviateReturnWithCollection = WeaviateReturn & { objects: WeaviateObjectWithCollection[]; }; -/** Options for the executing a prepared QueryAgent search. */ +/** Options for executing a prepared QueryAgent search. */ export type SearchExecutionOptions = { - /** The maximum number of results to return. */ + /** The maximum number of results to return. Defaults to 20 if not specified. */ limit?: number; - /** The offset of the results to return, for paginating through query result sets. */ + /** The offset to start from, for paginating through query result sets. */ offset: number; }; +/** + * Response for the Query Agent search-only mode. + * + * Contains the results of the search, the usage, and the underlying searches performed. You can + * paginate through the result set by calling {@link SearchModeResponse.next} on this response with + * different `limit` / `offset` values. This will reuse the same underlying searches each time, + * resulting in a consistent result set across pages. + */ export type SearchModeResponse = { + /** The underlying searches performed by the agent to produce this result set. */ searches?: Search[]; + /** Model unit usage for this invocation. */ usage: ModelUnitUsage; + /** Total time taken for the agent to produce this result set, in seconds. */ totalTime: number; + /** The objects returned by the underlying searches, paginated by `limit` and `offset`. */ searchResults: WeaviateReturnWithCollection; + /** + * Paginate the search-only results with the given `limit` and `offset` values. + * + * Reuses the same underlying searches as the originating request, so successive calls produce + * a consistent result set across pages. + * + * @param options - Pagination options. + * @param options.limit - The maximum number of results to return. Defaults to 20. + * @param options.offset - The offset to start from. + * @returns The next {@link SearchModeResponse} page. + */ next: (options: SearchExecutionOptions) => Promise; }; From 5193549488c9cdaadbc0d9a09bd81e351a1a64bd Mon Sep 17 00:00:00 2001 From: dannyjameswilliams Date: Mon, 18 May 2026 14:46:20 +0100 Subject: [PATCH 2/3] added docs run test to main action --- .github/workflows/main.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/main.yaml b/.github/workflows/main.yaml index f3fba04..3f2b5f9 100644 --- a/.github/workflows/main.yaml +++ b/.github/workflows/main.yaml @@ -20,3 +20,4 @@ jobs: - run: pnpm format - run: pnpm build - run: pnpm test + - run: pnpm run docs From 75c43e11f12fe8bb2325701782a79fbfd0d3fd1e Mon Sep 17 00:00:00 2001 From: dannyjameswilliams Date: Mon, 18 May 2026 15:00:23 +0100 Subject: [PATCH 3/3] enable preview docs on push to main --- .github/workflows/docs.yaml | 37 ++++++++++++++++++++++++++++++++++ .github/workflows/release.yaml | 19 ++++++++++------- 2 files changed, 49 insertions(+), 7 deletions(-) create mode 100644 .github/workflows/docs.yaml diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 0000000..1ae11a6 --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,37 @@ +--- +name: Docs Preview + +on: + push: + branches: + - main + workflow_dispatch: + +permissions: + contents: write # to push to gh-pages branch + +concurrency: + group: gh-pages-write + cancel-in-progress: false + +jobs: + deploy-preview: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + - uses: actions/setup-node@v6 + with: + node-version: 24 + - uses: pnpm/action-setup@v4 + with: + version: 10 + - run: pnpm install + - run: pnpm run docs + + - name: Deploy preview to gh-pages /preview + uses: peaceiris/actions-gh-pages@v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs + destination_dir: preview + commit_message: "Deploy preview from ${{ github.sha }}" diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 5eb6087..98b6d65 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -7,9 +7,12 @@ on: - "*" permissions: - contents: read + contents: write # to push to gh-pages branch id-token: write # to authenticate with OIDC when publishing to npm - pages: write # to deploy to Pages + +concurrency: + group: gh-pages-write + cancel-in-progress: false jobs: publish: @@ -26,9 +29,11 @@ jobs: - run: pnpm install - run: pnpm publish --no-git-checks - run: pnpm run docs - - name: "Upload docs as pages artifact" - uses: actions/upload-pages-artifact@v3 + + - name: Deploy released docs to gh-pages root + uses: peaceiris/actions-gh-pages@v4 with: - path: ./docs - - name: "Deploy the uploaded pages artifact" - uses: actions/deploy-pages@v4 + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs + keep_files: true + commit_message: "Deploy released docs ${{ github.ref_name }}"