diff --git a/.gitignore b/.gitignore index 10ad49dd7..c3787f479 100644 --- a/.gitignore +++ b/.gitignore @@ -160,4 +160,7 @@ cython_debug/ .idea/ .DS_Store +# JS API refs +js/_build/ + .envrc diff --git a/js/package.json b/js/package.json index ea1e042de..b94c30c7c 100644 --- a/js/package.json +++ b/js/package.json @@ -67,6 +67,7 @@ "types": "./dist/index.d.ts", "scripts": { "build": "yarn clean && yarn build:esm && yarn build:cjs && node scripts/create-entrypoints.js", + "build:typedoc": "yarn build && rm -rf ./_build/api_refs && npx typedoc", "bump-version": "node scripts/bump-version.js", "check-version": "node scripts/check-version.js", "check-npm-version": "node scripts/check-npm-version.js", @@ -139,6 +140,8 @@ "prettier": "^2.8.8", "ts-jest": "^29.1.0", "ts-node": "^10.9.1", + "typedoc": "^0.27.6", + "typedoc-plugin-expand-object-like-types": "^0.1.2", "typescript": "^5.4.5", "zod": "^3.23.8" }, diff --git a/js/scripts/typedoc-plugin.cjs b/js/scripts/typedoc-plugin.cjs new file mode 100644 index 000000000..c1bbd3ee6 --- /dev/null +++ b/js/scripts/typedoc-plugin.cjs @@ -0,0 +1,113 @@ +const { + Application, + Converter, + Context, + ReflectionKind, + DeclarationReflection, + RendererEvent, +} = require("typedoc"); +const fs = require("fs"); +const path = require("path"); + +// Reflection types to check for methods that should not be documented. +// e.g methods prefixed with `_` or `lc_` +const REFLECTION_KINDS_TO_HIDE = [ + ReflectionKind.Property, + ReflectionKind.Accessor, + ReflectionKind.Variable, + ReflectionKind.Method, + ReflectionKind.Function, + ReflectionKind.Class, + ReflectionKind.Interface, + ReflectionKind.Enum, + ReflectionKind.TypeAlias, +]; + +const BASE_OUTPUT_DIR = "./_build/api_refs"; + +// Script to inject into the HTML to add a CMD/CTRL + K 'hotkey' which focuses +// on the search input element. +const SCRIPT_HTML = ``; + +/** + * Takes in a reflection and an array of all chat model class names. + * Then performs checks to see if the given reflection should be removed + * from the documentation. + * E.g a class method on chat models which is + * not intended to be documented. + * + * @param {DeclarationReflection} reflection + * @returns {boolean} Whether or not the reflection should be removed + */ +function shouldRemoveReflection(reflection) { + const kind = reflection.kind; + + if ( + reflection.parent && + reflection.name !== "constructor" + ) { + if (kind === ReflectionKind.Property) { + return true; + } + } + + if (REFLECTION_KINDS_TO_HIDE.find((kindToHide) => kindToHide === kind)) { + if (reflection.name.startsWith("_") || reflection.name.startsWith("ls_")) { + // Remove all reflections which start with an `_` or `ls_` as those are internal + return true; + } + } +} + +/** + * @param {Application} application + * @returns {void} + */ +function load(application) { + application.converter.on( + Converter.EVENT_CREATE_DECLARATION, + resolveReflection + ); + + application.renderer.on(RendererEvent.END, onEndRenderEvent); + + /** + * @param {Context} context + * @param {DeclarationReflection} reflection + * @returns {void} + */ + function resolveReflection(context, reflection) { + const { project } = context; + + if (shouldRemoveReflection(reflection)) { + project.removeReflection(reflection); + } + } + + /** + * @param {Context} context + */ + function onEndRenderEvent(context) { + const htmlToSplitAtSearchScript = `
`; + + const { urls } = context; + for (const { url } of urls) { + const indexFilePath = path.join(BASE_OUTPUT_DIR, url); + const htmlFileContent = fs.readFileSync(indexFilePath, "utf-8"); + + const [part1, part2] = htmlFileContent.split(htmlToSplitAtSearchScript); + const htmlWithScript = part1 + SCRIPT_HTML + part2; + fs.writeFileSync(indexFilePath, htmlWithScript); + } + } +} + +module.exports = { load }; diff --git a/js/src/wrappers/openai.ts b/js/src/wrappers/openai.ts index 9987e0adb..f654481c6 100644 --- a/js/src/wrappers/openai.ts +++ b/js/src/wrappers/openai.ts @@ -234,6 +234,11 @@ function processChatCompletion(outputs: Readonly): KVMap { * @param options LangSmith options. * @example * ```ts + * import { OpenAI } from "openai"; + * import { wrapOpenAI } from "langsmith/wrappers/openai"; + * + * const patchedClient = wrapOpenAI(new OpenAI()); + * * const patchedStream = await patchedClient.chat.completions.create( * { * messages: [{ role: "user", content: `Say 'foo'` }], diff --git a/js/typedoc.json b/js/typedoc.json new file mode 100644 index 000000000..dc2d2e961 --- /dev/null +++ b/js/typedoc.json @@ -0,0 +1,27 @@ +{ + "$schema": "https://typedoc.org/schema.json", + "out": "_build/api_refs", + "sort": [ + "kind", + "visibility", + "instance-first", + "required-first", + "alphabetical" + ], + "plugin": [ + "typedoc-plugin-expand-object-like-types", + "./scripts/typedoc-plugin.cjs" + ], + "tsconfig": "./tsconfig.json", + "excludePrivate": true, + "excludeInternal": true, + "excludeExternals": false, + "excludeNotDocumented": false, + "includeVersion": true, + "sourceLinkTemplate": "https://github.com/langchain-ai/langsmith-sdk/blob/{gitRevision}/{path}#L{line}", + "logLevel": "Error", + "name": "LangSmith", + "skipErrorChecking": false, + "exclude": ["dist"], + "hostedBaseUrl": "https://docs.smith.langchain.com/reference/js/", +} \ No newline at end of file diff --git a/js/yarn.lock b/js/yarn.lock index a5e15453f..295a3f667 100644 --- a/js/yarn.lock +++ b/js/yarn.lock @@ -1072,6 +1072,15 @@ resolved "https://registry.yarnpkg.com/@faker-js/faker/-/faker-8.4.1.tgz#5d5e8aee8fce48f5e189bf730ebd1f758f491451" integrity sha512-XQ3cU+Q8Uqmrbf2e0cIC/QN43sTBSC8KF12u29Mb47tWrt2hAgBXSgpZMj4Ao8Uk0iJcU99QsOCaIL8934obCg== +"@gerrit0/mini-shiki@^1.24.0": + version "1.27.0" + resolved "https://registry.yarnpkg.com/@gerrit0/mini-shiki/-/mini-shiki-1.27.0.tgz#8bc370ac8b80c5e5e0c20fa69edcc7dec9b593fc" + integrity sha512-nFZkbq4/wU+GxkyJVrXeMIS9SEcHI1HzJtK3EDtMQy16nNs1LNaI0dZTLAP2EuK/QSTYLo/Zaabm6Phxlmra1A== + dependencies: + "@shikijs/engine-oniguruma" "^1.27.0" + "@shikijs/types" "^1.27.0" + "@shikijs/vscode-textmate" "^10.0.1" + "@humanwhocodes/config-array@^0.11.8": version "0.11.8" resolved "https://registry.npmjs.org/@humanwhocodes/config-array/-/config-array-0.11.8.tgz" @@ -1501,6 +1510,27 @@ resolved "https://registry.yarnpkg.com/@opentelemetry/semantic-conventions/-/semantic-conventions-1.27.0.tgz#1a857dcc95a5ab30122e04417148211e6f945e6c" integrity sha512-sAay1RrB+ONOem0OZanAR1ZI/k7yDpnOQSQmTMuGImUQb2y8EbSaCJ94FQluM74xoU03vlb2d2U90hZluL6nQg== +"@shikijs/engine-oniguruma@^1.27.0": + version "1.27.2" + resolved "https://registry.yarnpkg.com/@shikijs/engine-oniguruma/-/engine-oniguruma-1.27.2.tgz#b120e6aaf654fccec4268f1c12bf70b24fd7373f" + integrity sha512-FZYKD1KN7srvpkz4lbGLOYWlyDU4Rd+2RtuKfABTkafAPOFr+J6umfIwY/TzOQqfNtWjL7SAwPAO0dcOraRLaQ== + dependencies: + "@shikijs/types" "1.27.2" + "@shikijs/vscode-textmate" "^10.0.1" + +"@shikijs/types@1.27.2", "@shikijs/types@^1.27.0": + version "1.27.2" + resolved "https://registry.yarnpkg.com/@shikijs/types/-/types-1.27.2.tgz#0288966973ac8d9c4186998e6be9969ff9a045a4" + integrity sha512-DM9OWUyjmdYdnKDpaGB/GEn9XkToyK1tqxuqbmc5PV+5K8WjjwfygL3+cIvbkSw2v1ySwHDgqATq/+98pJ4Kyg== + dependencies: + "@shikijs/vscode-textmate" "^10.0.1" + "@types/hast" "^3.0.4" + +"@shikijs/vscode-textmate@^10.0.1": + version "10.0.1" + resolved "https://registry.yarnpkg.com/@shikijs/vscode-textmate/-/vscode-textmate-10.0.1.tgz#d06d45b67ac5e9b0088e3f67ebd3f25c6c3d711a" + integrity sha512-fTIQwLF+Qhuws31iw7Ncl1R3HUDtGwIipiJ9iU+UsDUwMhegFcQKQHd51nZjb7CArq0MvON8rbgCGQYWHUKAdg== + "@sinclair/typebox@^0.25.16": version "0.25.24" resolved "https://registry.npmjs.org/@sinclair/typebox/-/typebox-0.25.24.tgz" @@ -1590,6 +1620,13 @@ dependencies: "@types/node" "*" +"@types/hast@^3.0.4": + version "3.0.4" + resolved "https://registry.yarnpkg.com/@types/hast/-/hast-3.0.4.tgz#1d6b39993b82cea6ad783945b0508c25903e15aa" + integrity sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ== + dependencies: + "@types/unist" "*" + "@types/istanbul-lib-coverage@*", "@types/istanbul-lib-coverage@^2.0.0", "@types/istanbul-lib-coverage@^2.0.1": version "2.0.4" resolved "https://registry.npmjs.org/@types/istanbul-lib-coverage/-/istanbul-lib-coverage-2.0.4.tgz" @@ -1677,6 +1714,11 @@ resolved "https://registry.npmjs.org/@types/stack-utils/-/stack-utils-2.0.1.tgz" integrity sha512-Hl219/BT5fLAaz6NDkSuhzasy49dwQS/DSdu4MdggFB8zcXv7vflBI3xp7FEmkmdDkBUI2bPUNeMttp2knYdxw== +"@types/unist@*": + version "3.0.3" + resolved "https://registry.yarnpkg.com/@types/unist/-/unist-3.0.3.tgz#acaab0f919ce69cce629c2d4ed2eb4adc1b6c20c" + integrity sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q== + "@types/uuid@^10.0.0": version "10.0.0" resolved "https://registry.yarnpkg.com/@types/uuid/-/uuid-10.0.0.tgz#e9c07fe50da0f53dc24970cca94d619ff03f6f6d" @@ -2042,6 +2084,13 @@ brace-expansion@^1.1.7: balanced-match "^1.0.0" concat-map "0.0.1" +brace-expansion@^2.0.1: + version "2.0.1" + resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-2.0.1.tgz#1edc459e0f0c548486ecf9fc99f2221364b9a0ae" + integrity sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA== + dependencies: + balanced-match "^1.0.0" + braces@^3.0.3: version "3.0.3" resolved "https://registry.yarnpkg.com/braces/-/braces-3.0.3.tgz#490332f40919452272d55a8480adc0c441358789" @@ -2374,6 +2423,11 @@ emoji-regex@^8.0.0: resolved "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz" integrity sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A== +entities@^4.4.0: + version "4.5.0" + resolved "https://registry.yarnpkg.com/entities/-/entities-4.5.0.tgz#5d268ea5e7113ec74c4d033b79ea5a35a488fb48" + integrity sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw== + error-ex@^1.3.1: version "1.3.2" resolved "https://registry.npmjs.org/error-ex/-/error-ex-1.3.2.tgz" @@ -3780,6 +3834,13 @@ lines-and-columns@^1.1.6: resolved "https://registry.npmjs.org/lines-and-columns/-/lines-and-columns-1.2.4.tgz" integrity sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg== +linkify-it@^5.0.0: + version "5.0.0" + resolved "https://registry.yarnpkg.com/linkify-it/-/linkify-it-5.0.0.tgz#9ef238bfa6dc70bd8e7f9572b52d369af569b421" + integrity sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ== + dependencies: + uc.micro "^2.0.0" + locate-path@^5.0.0: version "5.0.0" resolved "https://registry.npmjs.org/locate-path/-/locate-path-5.0.0.tgz" @@ -3823,6 +3884,11 @@ lru-cache@^6.0.0: dependencies: yallist "^4.0.0" +lunr@^2.3.9: + version "2.3.9" + resolved "https://registry.yarnpkg.com/lunr/-/lunr-2.3.9.tgz#18b123142832337dd6e964df1a5a7707b25d35e1" + integrity sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow== + make-dir@^3.0.0: version "3.1.0" resolved "https://registry.npmjs.org/make-dir/-/make-dir-3.1.0.tgz" @@ -3842,6 +3908,23 @@ makeerror@1.0.12: dependencies: tmpl "1.0.5" +markdown-it@^14.1.0: + version "14.1.0" + resolved "https://registry.yarnpkg.com/markdown-it/-/markdown-it-14.1.0.tgz#3c3c5992883c633db4714ccb4d7b5935d98b7d45" + integrity sha512-a54IwgWPaeBCAAsv13YgmALOF1elABB08FxO9i+r4VFk5Vl4pKokRPeX8u5TCgSsPi6ec1otfLjdOpVcgbpshg== + dependencies: + argparse "^2.0.1" + entities "^4.4.0" + linkify-it "^5.0.0" + mdurl "^2.0.0" + punycode.js "^2.3.1" + uc.micro "^2.1.0" + +mdurl@^2.0.0: + version "2.0.0" + resolved "https://registry.yarnpkg.com/mdurl/-/mdurl-2.0.0.tgz#80676ec0433025dd3e17ee983d0fe8de5a2237e0" + integrity sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w== + merge-stream@^2.0.0: version "2.0.0" resolved "https://registry.npmjs.org/merge-stream/-/merge-stream-2.0.0.tgz" @@ -3884,6 +3967,13 @@ minimatch@^3.0.4, minimatch@^3.0.5, minimatch@^3.1.1, minimatch@^3.1.2: dependencies: brace-expansion "^1.1.7" +minimatch@^9.0.5: + version "9.0.5" + resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-9.0.5.tgz#d74f9dd6b57d83d8e98cfb82133b03978bc929e5" + integrity sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow== + dependencies: + brace-expansion "^2.0.1" + minimist@^1.2.0, minimist@^1.2.6: version "1.2.8" resolved "https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz" @@ -4218,6 +4308,11 @@ prompts@^2.0.1: kleur "^3.0.3" sisteransi "^1.0.5" +punycode.js@^2.3.1: + version "2.3.1" + resolved "https://registry.yarnpkg.com/punycode.js/-/punycode.js-2.3.1.tgz#6b53e56ad75588234e79f4affa90972c7dd8cdb7" + integrity sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA== + punycode@^2.1.0: version "2.3.0" resolved "https://registry.npmjs.org/punycode/-/punycode-2.3.0.tgz" @@ -4703,11 +4798,32 @@ typed-array-length@^1.0.4: for-each "^0.3.3" is-typed-array "^1.1.9" +typedoc-plugin-expand-object-like-types@^0.1.2: + version "0.1.2" + resolved "https://registry.yarnpkg.com/typedoc-plugin-expand-object-like-types/-/typedoc-plugin-expand-object-like-types-0.1.2.tgz#7b97e2e0ccb5f0d7e784677a62b89b2ce163fc39" + integrity sha512-RRMOCWMElQHBOVraWMWrh/0tDqCdS5oxYwaWMZBB3KlUUUUCxKllpvJPsRH/uFLO1nOuy28CbJxGVU1umv7LOQ== + +typedoc@^0.27.6: + version "0.27.6" + resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.27.6.tgz#7e8d067bd5386b7908afcb12c9054a83e8bb326b" + integrity sha512-oBFRoh2Px6jFx366db0lLlihcalq/JzyCVp7Vaq1yphL/tbgx2e+bkpkCgJPunaPvPwoTOXSwasfklWHm7GfAw== + dependencies: + "@gerrit0/mini-shiki" "^1.24.0" + lunr "^2.3.9" + markdown-it "^14.1.0" + minimatch "^9.0.5" + yaml "^2.6.1" + typescript@^5.4.5: version "5.4.5" resolved "https://registry.yarnpkg.com/typescript/-/typescript-5.4.5.tgz#42ccef2c571fdbd0f6718b1d1f5e6e5ef006f611" integrity sha512-vcI4UpRgg81oIRUFwR0WSIHKt11nJ7SAVlYNIu+QpqeyXP+gpQJy/Z4+F0aGxSE4MqwjyXvW/TzgkLAx2AGHwQ== +uc.micro@^2.0.0, uc.micro@^2.1.0: + version "2.1.0" + resolved "https://registry.yarnpkg.com/uc.micro/-/uc.micro-2.1.0.tgz#f8d3f7d0ec4c3dea35a7e3c8efa4cb8b45c9e7ee" + integrity sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A== + unbox-primitive@^1.0.2: version "1.0.2" resolved "https://registry.npmjs.org/unbox-primitive/-/unbox-primitive-1.0.2.tgz" @@ -4892,6 +5008,11 @@ yaml@^2.2.1: resolved "https://registry.yarnpkg.com/yaml/-/yaml-2.4.2.tgz#7a2b30f2243a5fc299e1f14ca58d475ed4bc5362" integrity sha512-B3VqDZ+JAg1nZpaEmWtTXUlBneoGx6CPM9b0TENK6aoSu5t73dItudwdgmi6tHlIZZId4dZ9skcAQ2UbcyAeVA== +yaml@^2.6.1: + version "2.7.0" + resolved "https://registry.yarnpkg.com/yaml/-/yaml-2.7.0.tgz#aef9bb617a64c937a9a748803786ad8d3ffe1e98" + integrity sha512-+hSoy/QHluxmC9kCIJyL/uyFmLmc+e5CFR5Wa+bpIhIj85LVb9ZH2nVnqrHoSvKogwODv0ClqZkmiSSaIH5LTA== + yargs-parser@^21.0.1, yargs-parser@^21.1.1: version "21.1.1" resolved "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz"