Agent TypeScript reference

scripts/reference-generation/weave/generate_typescript_sdk_docs.py

@@ -76,8 +76,8 @@ def download_weave_source(version="main"):
             "--single-branch"
         ]
 
-        # Add branch/tag specification
-        if version != "main":
+        # Default branch on wandb/weave is `master`; either alias clones HEAD.
+        if version not in ("main", "master"):
             clone_cmd.extend(["--branch", version])
 
         clone_cmd.extend([
@@ -104,36 +104,53 @@ def download_weave_source(version="main"):
         sys.exit(1)
 
 
+def _npm_install_args(sdk_path: Path) -> list[str]:
+    """
+    Build npm install args for doc generation.
+
+    --ignore-scripts: the SDK's `prepare` script runs `npm run build`, which
+        can fail on upstream type errors (for example Buffer vs BlobPart).
+        Doc generation does not need a build, only type information.
+    --legacy-peer-deps: needed when the SDK ships a pnpm lockfile but we
+        install with npm (the case on master).
+    """
+    args = ["npm", "install", "--ignore-scripts"]
+    if (sdk_path / "pnpm-lock.yaml").exists():
+        args.append("--legacy-peer-deps")
+    return args
+
+
 def setup_typescript_project(weave_source):
     """Set up the TypeScript project and install dependencies."""
     sdk_path = Path(weave_source) / "sdks" / "node"
-    
+
     if not sdk_path.exists():
         print(f"TypeScript SDK not found at {sdk_path}", file=sys.stderr)
         sys.exit(1)
-    
+
     print(f"\nSetting up TypeScript project...")
     os.chdir(sdk_path)
-    
+
     try:
-        # Install dependencies
         print("  Installing dependencies...")
-        subprocess.run(["npm", "install"], check=True)
-
-        # Install typedoc and markdown plugin with compatible versions
+        subprocess.run(_npm_install_args(sdk_path), check=True)
+
         print("  Installing typedoc...")
-        subprocess.run([
-            "npm", "install", "--save-dev",
+        typedoc_install = ["npm", "install", "--save-dev", "--ignore-scripts"]
+        if (sdk_path / "pnpm-lock.yaml").exists():
+            typedoc_install.append("--legacy-peer-deps")
+        typedoc_install.extend([
             "typedoc@0.25.13",
-            "typedoc-plugin-markdown@3.17.1"
-        ], check=True)
-
+            "typedoc-plugin-markdown@3.17.1",
+        ])
+        subprocess.run(typedoc_install, check=True)
+
         print("  ✓ Dependencies installed")
-        
+
     except subprocess.CalledProcessError as e:
         print(f"✗ Failed to install dependencies: {e}", file=sys.stderr)
         sys.exit(1)
-    
+
     return sdk_path
 
 
@@ -153,7 +170,10 @@ def generate_typedoc(sdk_path, output_path):
         "excludeProtected": True,
         "excludeInternal": True,
         "disableSources": False,
-        "cleanOutputDir": True
+        "cleanOutputDir": True,
+        # Skip TypeScript type checking so upstream SDK type errors
+        # (for example Buffer vs BlobPart in weaveClient.ts) do not block docs.
+        "skipErrorChecking": True,
     }
 
     config_path = sdk_path / "typedoc.json"
@@ -174,6 +194,48 @@ def generate_typedoc(sdk_path, output_path):
             config_path.unlink()
 
 
+def escape_mdx_angle_brackets(content: str) -> str:
+    """
+    Escape raw angle brackets outside code so MDX does not parse them as JSX.
+
+    TypeDoc sometimes emits return descriptions like `Promise<boolean> - ...`
+    outside inline code. MDX interprets `<boolean>` as an HTML/JSX tag.
+    """
+    result_lines = []
+    in_fence = False
+    for line in content.split("\n"):
+        if line.strip().startswith("```"):
+            in_fence = not in_fence
+            result_lines.append(line)
+            continue
+        if in_fence:
+            result_lines.append(line)
+            continue
+        result_lines.append(_escape_angle_brackets_outside_inline_code(line))
+    return "\n".join(result_lines)
+
+
+def _escape_angle_brackets_outside_inline_code(line: str) -> str:
+    parts = re.split(r"(`[^`]*`)", line)
+    escaped = []
+    for i, part in enumerate(parts):
+        if i % 2 == 1:
+            escaped.append(part)
+        else:
+            escaped.append(_escape_raw_angle_brackets(part))
+    return "".join(escaped)
+
+
+def _escape_raw_angle_brackets(text: str) -> str:
+    def repl(match: re.Match[str]) -> str:
+        inner = match.group(1)
+        if inner.startswith("/"):
+            return match.group(0)
+        return f"&lt;{inner}&gt;"
+
+    return re.sub(r"(?<!\\)(?<!&lt;)<([^>\n]+)>", repl, text)
+
+
 def convert_to_mintlify_format(docs_dir):
     """Convert TypeDoc markdown to Mintlify MDX format."""
     print(f"\nConverting to Mintlify format...")
@@ -279,7 +341,9 @@ def fix_readme_anchor(match):
             # Links like [Dataset](classes/Dataset.md) are already relative
             # Just ensure .md extension is removed (already done above)
             pass
-
+
+        content = escape_mdx_angle_brackets(content)
+
         # Write as .mdx file with lowercase filename (avoid Git case sensitivity issues)
         lowercase_stem = md_file.stem.lower()
         mdx_file = md_file.parent / f"{lowercase_stem}.mdx"
@@ -356,6 +420,7 @@ def extract_members_to_separate_files(docs_path):
 ---
 
 {func_content.replace(f'### {func_name}', f'# {func_name}')}"""
+            func_file_content = escape_mdx_angle_brackets(func_file_content)
 
             # Write the function file with lowercase filename (avoid Git case sensitivity issues)
             func_filename = func_name.lower()
@@ -423,6 +488,7 @@ def extract_members_to_separate_files(docs_path):
 ---
 
 {alias_content.replace(f'### {alias_name}', f'# {alias_name}')}"""
+            alias_file_content = escape_mdx_angle_brackets(alias_file_content)
 
             # Write the type alias file with lowercase filename (avoid Git case sensitivity issues)
             alias_filename = alias_name.lower()
@@ -505,13 +571,20 @@ def cleanup_temp_dirs(*paths):
             shutil.rmtree(path, ignore_errors=True)
 
 
+def _resolve_weave_version() -> str:
+    """Resolve Weave ref from CLI arg, WEAVE_VERSION env var, or latest."""
+    if len(sys.argv) > 1:
+        return sys.argv[1]
+    return os.environ.get("WEAVE_VERSION", "latest")
+
+
 def main():
     """Main function."""
     # Check dependencies
     check_node_dependencies()
-    
-    # Get Weave version from environment or use latest
-    weave_version = os.environ.get("WEAVE_VERSION", "latest")
+
+    # Get Weave version from CLI arg, environment variable, or latest
+    weave_version = _resolve_weave_version()
 
     # Store the original working directory
     original_cwd = os.getcwd()

weave/reference/typescript-sdk.mdx

@@ -14,36 +14,69 @@ weave
 - [Dataset](./typescript-sdk/classes/dataset)
 - [Evaluation](./typescript-sdk/classes/evaluation)
 - [EvaluationLogger](./typescript-sdk/classes/evaluationlogger)
+- [LLM](./typescript-sdk/classes/llm)
 - [MessagesPrompt](./typescript-sdk/classes/messagesprompt)
 - [ObjectRef](./typescript-sdk/classes/objectref)
 - [ScoreLogger](./typescript-sdk/classes/scorelogger)
+- [Session](./typescript-sdk/classes/session)
 - [StringPrompt](./typescript-sdk/classes/stringprompt)
+- [SubAgent](./typescript-sdk/classes/subagent)
+- [Tool](./typescript-sdk/classes/tool)
+- [Turn](./typescript-sdk/classes/turn)
 - [WeaveClient](./typescript-sdk/classes/weaveclient)
 - [WeaveObject](./typescript-sdk/classes/weaveobject)
 
 ### Interfaces
 
 - [CallSchema](./typescript-sdk/interfaces/callschema)
 - [CallsFilter](./typescript-sdk/interfaces/callsfilter)
+- [GetCallsOptions](./typescript-sdk/interfaces/getcallsoptions)
+- [LLMInit](./typescript-sdk/interfaces/llminit)
+- [Message](./typescript-sdk/interfaces/message)
+- [Query](./typescript-sdk/interfaces/query)
+- [Reasoning](./typescript-sdk/interfaces/reasoning)
+- [SessionInit](./typescript-sdk/interfaces/sessioninit)
+- [SortBy](./typescript-sdk/interfaces/sortby)
+- [SubAgentInit](./typescript-sdk/interfaces/subagentinit)
+- [ToolInit](./typescript-sdk/interfaces/toolinit)
+- [TurnInit](./typescript-sdk/interfaces/turninit)
+- [Usage](./typescript-sdk/interfaces/usage)
 - [WeaveAudio](./typescript-sdk/interfaces/weaveaudio)
 - [WeaveImage](./typescript-sdk/interfaces/weaveimage)
 
 
 ### Type Aliases
 
+- [MessagePart](./typescript-sdk/type-aliases/messagepart)
+- [Modality](./typescript-sdk/type-aliases/modality)
 - [OpDecorator](./typescript-sdk/type-aliases/opdecorator)
 - [Op](./typescript-sdk/type-aliases/op)
+- [Role](./typescript-sdk/type-aliases/role)
 
 ### Functions
 
 - [createopenaiagentstracingprocessor](./typescript-sdk/functions/createopenaiagentstracingprocessor)
+- [createotelextension](./typescript-sdk/functions/createotelextension)
+- [endllm](./typescript-sdk/functions/endllm)
+- [endsession](./typescript-sdk/functions/endsession)
+- [endturn](./typescript-sdk/functions/endturn)
+- [flushotel](./typescript-sdk/functions/flushotel)
+- [getcurrentllm](./typescript-sdk/functions/getcurrentllm)
+- [getcurrentsession](./typescript-sdk/functions/getcurrentsession)
+- [getcurrentturn](./typescript-sdk/functions/getcurrentturn)
 - [init](./typescript-sdk/functions/init)
 - [instrumentopenaiagents](./typescript-sdk/functions/instrumentopenaiagents)
 - [login](./typescript-sdk/functions/login)
 - [op](./typescript-sdk/functions/op)
 - [patchrealtimesession](./typescript-sdk/functions/patchrealtimesession)
 - [requirecurrentcallstackentry](./typescript-sdk/functions/requirecurrentcallstackentry)
 - [requirecurrentchildsummary](./typescript-sdk/functions/requirecurrentchildsummary)
+- [runisolated](./typescript-sdk/functions/runisolated)
+- [startllm](./typescript-sdk/functions/startllm)
+- [startsession](./typescript-sdk/functions/startsession)
+- [startsubagent](./typescript-sdk/functions/startsubagent)
+- [starttool](./typescript-sdk/functions/starttool)
+- [startturn](./typescript-sdk/functions/startturn)
 - [weaveaudio](./typescript-sdk/functions/weaveaudio)
 - [weaveimage](./typescript-sdk/functions/weaveimage)
 - [withattributes](./typescript-sdk/functions/withattributes)
@@ -53,3 +86,6 @@ weave
 ## Type Aliases
 
 
+
+
+

weave/reference/typescript-sdk/classes/dataset.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Class: Dataset<R>"
+title: "Class: Dataset&lt;R&gt;"
 description: "TypeScript SDK reference"
 ---
 
@@ -93,7 +93,7 @@ const ref = await dataset.save()
 
 #### Defined in
 
-[dataset.ts:51](https://github.com/wandb/weave/blob/62f1e46098095776ee29b730ad10b3b3d1a68307/sdks/node/src/dataset.ts#L51)
+[dataset.ts:51](https://github.com/wandb/weave/blob/68509dddcf91f8cd4bfacf04fc6849c92bff20d6/sdks/node/src/dataset.ts#L51)
 
 ## Properties
 
@@ -107,7 +107,7 @@ const ref = await dataset.save()
 
 #### Defined in
 
-[weaveObject.ts:73](https://github.com/wandb/weave/blob/62f1e46098095776ee29b730ad10b3b3d1a68307/sdks/node/src/weaveObject.ts#L73)
+[weaveObject.ts:73](https://github.com/wandb/weave/blob/68509dddcf91f8cd4bfacf04fc6849c92bff20d6/sdks/node/src/weaveObject.ts#L73)
 
 ___
 
@@ -117,7 +117,7 @@ ___
 
 #### Defined in
 
-[dataset.ts:49](https://github.com/wandb/weave/blob/62f1e46098095776ee29b730ad10b3b3d1a68307/sdks/node/src/dataset.ts#L49)
+[dataset.ts:49](https://github.com/wandb/weave/blob/68509dddcf91f8cd4bfacf04fc6849c92bff20d6/sdks/node/src/dataset.ts#L49)
 
 ## Accessors
 
@@ -135,7 +135,7 @@ WeaveObject.description
 
 #### Defined in
 
-[weaveObject.ts:100](https://github.com/wandb/weave/blob/62f1e46098095776ee29b730ad10b3b3d1a68307/sdks/node/src/weaveObject.ts#L100)
+[weaveObject.ts:100](https://github.com/wandb/weave/blob/68509dddcf91f8cd4bfacf04fc6849c92bff20d6/sdks/node/src/weaveObject.ts#L100)
 
 ___
 
@@ -149,7 +149,7 @@ ___
 
 #### Defined in
 
-[dataset.ts:64](https://github.com/wandb/weave/blob/62f1e46098095776ee29b730ad10b3b3d1a68307/sdks/node/src/dataset.ts#L64)
+[dataset.ts:64](https://github.com/wandb/weave/blob/68509dddcf91f8cd4bfacf04fc6849c92bff20d6/sdks/node/src/dataset.ts#L64)
 
 ___
 
@@ -167,21 +167,21 @@ WeaveObject.name
 
 #### Defined in
 
-[weaveObject.ts:96](https://github.com/wandb/weave/blob/62f1e46098095776ee29b730ad10b3b3d1a68307/sdks/node/src/weaveObject.ts#L96)
+[weaveObject.ts:96](https://github.com/wandb/weave/blob/68509dddcf91f8cd4bfacf04fc6849c92bff20d6/sdks/node/src/weaveObject.ts#L96)
 
 ## Methods
 
 ### [asyncIterator]
 
-▸ **[asyncIterator]**(): `AsyncIterator`\<`any`, `any`, `undefined`\>
+▸ **[asyncIterator]**(): `AsyncIterator`\<`any`, `any`, `any`\>
 
 #### Returns
 
-`AsyncIterator`\<`any`, `any`, `undefined`\>
+`AsyncIterator`\<`any`, `any`, `any`\>
 
 #### Defined in
 
-[dataset.ts:68](https://github.com/wandb/weave/blob/62f1e46098095776ee29b730ad10b3b3d1a68307/sdks/node/src/dataset.ts#L68)
+[dataset.ts:68](https://github.com/wandb/weave/blob/68509dddcf91f8cd4bfacf04fc6849c92bff20d6/sdks/node/src/dataset.ts#L68)
 
 ___
 
@@ -201,7 +201,7 @@ ___
 
 #### Defined in
 
-[dataset.ts:74](https://github.com/wandb/weave/blob/62f1e46098095776ee29b730ad10b3b3d1a68307/sdks/node/src/dataset.ts#L74)
+[dataset.ts:74](https://github.com/wandb/weave/blob/68509dddcf91f8cd4bfacf04fc6849c92bff20d6/sdks/node/src/dataset.ts#L74)
 
 ___
 
@@ -215,7 +215,7 @@ ___
 
 #### Defined in
 
-[dataset.ts:60](https://github.com/wandb/weave/blob/62f1e46098095776ee29b730ad10b3b3d1a68307/sdks/node/src/dataset.ts#L60)
+[dataset.ts:60](https://github.com/wandb/weave/blob/68509dddcf91f8cd4bfacf04fc6849c92bff20d6/sdks/node/src/dataset.ts#L60)
 
 ___
 
@@ -233,4 +233,4 @@ ___
 
 #### Defined in
 
-[weaveObject.ts:77](https://github.com/wandb/weave/blob/62f1e46098095776ee29b730ad10b3b3d1a68307/sdks/node/src/weaveObject.ts#L77)
+[weaveObject.ts:77](https://github.com/wandb/weave/blob/68509dddcf91f8cd4bfacf04fc6849c92bff20d6/sdks/node/src/weaveObject.ts#L77)