docs: add vercel build (#3290)

.github/workflows/codespell.yml

@@ -9,7 +9,11 @@
     
     permissions:
       contents: read
-    
+
+    defaults:
+      run:
+        working-directory: docs
+
     jobs:
       codespell:
         name: (Check for spelling errors)
@@ -26,7 +30,7 @@
           - name: Extract Ignore Words List
             run: |
               # Use a Python script to extract the ignore words list from pyproject.toml
-              python .github/workflows/extract_ignored_words_list.py
+              python ../.github/workflows/extract_ignored_words_list.py
             id: extract_ignore_words
     
           - name: Codespell

.github/workflows/deploy_docs.yml

@@ -21,6 +21,10 @@ concurrency:
   group: "pages"
   cancel-in-progress: false
 
+defaults:
+  run:
+    working-directory: docs
+
 jobs:
   get-changed-files:
     runs-on: ubuntu-latest
@@ -96,13 +100,13 @@ jobs:
               --check-links-ignore "https://python\.langchain\.com/.*" \
               --check-links-ignore "https://openai\.com/.*" \
               --check-links-ignore "https://pepy\.tech/.*" \
-              --check-links $(find docs/site -name "index.html" | grep -v 'storm/index.html') 
+              --check-links $(find site -name "index.html" | grep -v 'storm/index.html')
               
           else
             echo "Fetching changes from origin/main..."
             git fetch origin main
             echo "Checking for changed notebook files..."
-            CHANGED_FILES=$(git diff --name-only --diff-filter=d origin/main | grep 'docs/docs/.*\.ipynb$' | grep -v 'storm.ipynb' | sed -E 's|^docs/docs/|docs/site/|; s/\.ipynb$/\/index.html/' || true)
+            CHANGED_FILES=$(git diff --name-only --diff-filter=d origin/main | grep 'docs/docs/.*\.ipynb$' | grep -v 'storm.ipynb' | sed -E 's|^docs/docs/|site/|; s/\.ipynb$/\/index.html/' || true)
             echo "Changed files: ${CHANGED_FILES}"
             if [ -n "${CHANGED_FILES}" ]; then
               echo "Running link check on HTML files matching changed notebook files..."
@@ -130,7 +134,7 @@ jobs:
         if: github.ref == 'refs/heads/main'
         uses: actions/upload-pages-artifact@v3
         with:
-          path: ./docs/site/
+          path: ./site/
 
       - name: Deploy to GitHub Pages
         if: github.ref == 'refs/heads/main'

.github/workflows/extract_ignored_words_list.py

@@ -1,6 +1,6 @@
 import toml
 
-pyproject_toml = toml.load("libs/langgraph/pyproject.toml")
+pyproject_toml = toml.load("../libs/langgraph/pyproject.toml")
 
 # Extract the ignore words list (adjust the key as per your TOML structure)
 ignore_words_list = (

.github/workflows/run_notebooks.yml

@@ -11,6 +11,10 @@ on:
   schedule:
     - cron: '0 13 * * *'
 
+defaults:
+  run:
+    working-directory: docs
+
 jobs:
   build:
     runs-on: ubuntu-latest
@@ -39,14 +43,14 @@ jobs:
 
       - name: Pre-download tiktoken files
         run: |
-          poetry run python docs/_scripts/download_tiktoken.py
+          poetry run python _scripts/download_tiktoken.py
 
       - name: Prepare notebooks
         run: |
           if [ "${{ matrix.lib-version }}" = "development" ]; then
-            poetry run python docs/_scripts/prepare_notebooks_for_ci.py --comment-install-cells
+            poetry run python _scripts/prepare_notebooks_for_ci.py --comment-install-cells
           else
-            poetry run python docs/_scripts/prepare_notebooks_for_ci.py
+            poetry run python _scripts/prepare_notebooks_for_ci.py
           fi
 
       - name: Run notebooks
@@ -63,12 +67,12 @@ jobs:
         run: |
           if [ "${{ github.event_name }}" = "workflow_dispatch" ] || [ "${{ github.event_name }}" = "schedule" ]; then
             echo "Running all notebooks"
-            ./docs/_scripts/execute_notebooks.sh
+            ./_scripts/execute_notebooks.sh
           else
-            CHANGED_FILES=$(echo '${{ inputs.changed-files }}' | tr ' ' '\n' | grep '\.ipynb$' || true)
+            CHANGED_FILES=$(echo '${{ inputs.changed-files }}' | tr ' ' '\n' | sed 's|^docs/docs/|docs/|' | grep '\.ipynb$' || true)
             if [ -n "$CHANGED_FILES" ]; then
               echo "Running changed notebooks: $CHANGED_FILES"
-              ./docs/_scripts/execute_notebooks.sh $CHANGED_FILES
+              ./_scripts/execute_notebooks.sh $CHANGED_FILES
             else
               echo "No notebook files changed, skipping execution"
             fi

.gitignore

@@ -179,3 +179,4 @@ Untitled*.ipynb
 Chinook.db
 
 libs/langgraph/out
+.vercel

Makefile

@@ -1,39 +0,0 @@
-.PHONY: lint-docs format-docs build-docs serve-docs serve-clean-docs clean-docs codespell build-typedoc
-
-build-typedoc:
-	cd libs/sdk-js && yarn install --include-dev && yarn typedoc
-	cd libs/sdk-js && yarn --silent concat-md --decrease-title-levels --ignore=js_ts_sdk_ref.md --start-title-level-at 2 docs > ../../docs/docs/cloud/reference/sdk/js_ts_sdk_ref.md 2>/dev/null
-	#  Add links to the monorepo
-	sed -e '1,10s|@langchain/langgraph-sdk|[@langchain/langgraph-sdk](https://github.com/langchain-ai/langgraph/tree/main/libs/sdk-js)|g' docs/docs/cloud/reference/sdk/js_ts_sdk_ref.md > temp_file && mv temp_file docs/docs/cloud/reference/sdk/js_ts_sdk_ref.md
-
-build-docs: build-typedoc
-	poetry run python -m mkdocs build --clean -f docs/mkdocs.yml --strict
-
-serve-clean-docs: clean-docs
-	poetry run python -m mkdocs serve -c -f docs/mkdocs.yml --strict -w ./libs/langgraph
-
-serve-docs: build-typedoc
-	poetry run python -m mkdocs serve -f docs/mkdocs.yml -w ./libs/langgraph  -w ./libs/checkpoint -w ./libs/sdk-py --dirty
-
-clean-docs:
-	find ./docs/docs -name "*.ipynb" -type f -delete
-	rm -rf docs/site
-
-## Run format against the project documentation.
-format-docs:
-	poetry run ruff format docs/docs
-	poetry run ruff check --fix docs/docs
-
-# Check the docs for linting violations
-lint-docs:
-	poetry run ruff format --check docs/docs
-	poetry run ruff check docs/docs
-
-codespell:
-	./docs/codespell_notebooks.sh .
-
-start-services:
-	docker compose -f docs/test-compose.yml up -V --force-recreate --wait --remove-orphans
-
-stop-services:
-	docker compose -f docs/test-compose.yml down

docs/.gitignore

@@ -1,2 +1,3 @@
 site/
 docs/cloud/reference/sdk/js_ts_sdk_ref.md
+.vercel

docs/Makefile

@@ -0,0 +1,47 @@
+.PHONY: lint-docs format-docs build-docs serve-docs serve-clean-docs clean-docs codespell build-typedoc
+
+build-typedoc:
+	cd ../libs/sdk-js && yarn install --include-dev && yarn typedoc
+	cd ../libs/sdk-js && yarn --silent concat-md --decrease-title-levels --ignore=js_ts_sdk_ref.md --start-title-level-at 2 docs > ../../docs/docs/cloud/reference/sdk/js_ts_sdk_ref.md 2>/dev/null
+	#  Add links to the monorepo
+	sed -e '1,10s|@langchain/langgraph-sdk|[@langchain/langgraph-sdk](https://github.com/langchain-ai/langgraph/tree/main/libs/sdk-js)|g' docs/cloud/reference/sdk/js_ts_sdk_ref.md > temp_file && mv temp_file docs/cloud/reference/sdk/js_ts_sdk_ref.md
+
+build-docs: build-typedoc
+	poetry run python -m mkdocs build --clean -f mkdocs.yml --strict
+
+install-vercel-deps:
+	curl -sSL https://install.python-poetry.org | python3 -
+	poetry self update 1.8.5
+
+vercel-build-docs: install-vercel-deps
+	poetry install
+	make build-docs
+
+serve-clean-docs: clean-docs
+	poetry run python -m mkdocs serve -c -f mkdocs.yml --strict -w ../libs/langgraph
+
+serve-docs: build-typedoc
+	poetry run python -m mkdocs serve -f mkdocs.yml -w ../libs/langgraph  -w ../libs/checkpoint -w ../libs/sdk-py --dirty
+
+clean-docs:
+	find ./docs -name "*.ipynb" -type f -delete
+	rm -rf site
+
+## Run format against the project documentation.
+format-docs:
+	poetry run ruff format docs
+	poetry run ruff check --fix docs
+
+# Check the docs for linting violations
+lint-docs:
+	poetry run ruff format --check docs
+	poetry run ruff check docs
+
+codespell:
+	./codespell_notebooks.sh .
+
+start-services:
+	docker compose -f test-compose.yml up -V --force-recreate --wait --remove-orphans
+
+stop-services:
+	docker compose -f test-compose.yml down

docs/README.md

@@ -19,23 +19,21 @@ make serve-docs
 If you would like to automatically execute all of the notebooks, to mimic the "Run notebooks" GHA, you can run:
 
 ```bash
-python docs/_scripts/prepare_notebooks_for_ci.py
-./docs/_scripts/execute_notebooks.sh
+python _scripts/prepare_notebooks_for_ci.py
+./_scripts/execute_notebooks.sh
 ```
 
 **Note**: if you want to run the notebooks without `%pip install` cells, you can run:
 
 ```bash
-python docs/_scripts/prepare_notebooks_for_ci.py --comment-install-cells
-./docs/_scripts/execute_notebooks.sh
+python _scripts/prepare_notebooks_for_ci.py --comment-install-cells
+./_scripts/execute_notebooks.sh
 ```
 
 `prepare_notebooks_for_ci.py` script will add VCR cassette context manager for each cell in the notebook, so that:
 * when the notebook is run for the first time, cells with network requests will be recorded to a VCR cassette file
 * when the notebook is run subsequently, the cells with network requests will be replayed from the cassettes
 
-**Note**: this is currently limited only to the notebooks in `docs/docs/how-tos`
-
 ## Adding new notebooks
 
 If you are adding a notebook with API requests, it's **recommended** to record network requests so that they can be subsequently replayed. If this is not done, the notebook runner will make API requests every time the notebook is run, which can be costly and slow.
@@ -48,14 +46,14 @@ Then, run
 jupyter execute <path_to_notebook>
 ```
 
-Once the notebook is executed, you should see the new VCR cassettes recorded in `docs/cassettes` directory and discard the updated notebook.
+Once the notebook is executed, you should see the new VCR cassettes recorded in `cassettes` directory and discard the updated notebook.
 
 ## Updating existing notebooks
 
-If you are updating an existing notebook, please make sure to remove any existing cassettes for the notebook in `docs/cassettes` directory (each cassette is prefixed with the notebook name), and then run the steps from the "Adding new notebooks" section above.
+If you are updating an existing notebook, please make sure to remove any existing cassettes for the notebook in `cassettes` directory (each cassette is prefixed with the notebook name), and then run the steps from the "Adding new notebooks" section above.
 
 To delete cassettes for a notebook, you can run:
 
 ```bash
-rm docs/cassettes/<notebook_name>*
+rm cassettes/<notebook_name>*
 ```

docs/_scripts/execute_notebooks.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 # Read the list of notebooks to skip from the JSON file
-SKIP_NOTEBOOKS=$(python -c "import json; print('\n'.join(json.load(open('docs/notebooks_no_execution.json'))))")
+SKIP_NOTEBOOKS=$(python -c "import json; print('\n'.join(json.load(open('notebooks_no_execution.json'))))")
 
 # Function to execute a single notebook
 execute_notebook() {
@@ -27,7 +27,7 @@ if [ $# -gt 0 ]; then
     notebooks=$(echo "$@" | tr ' ' '\n' | grep -vFf <(echo "$SKIP_NOTEBOOKS"))
 else
     # Find all notebooks and filter out those in the skip list
-    notebooks=$(find docs/docs/tutorials docs/docs/how-tos -name "*.ipynb" | grep -v ".ipynb_checkpoints" | grep -vFf <(echo "$SKIP_NOTEBOOKS"))
+    notebooks=$(find docs/tutorials docs/how-tos -name "*.ipynb" | grep -v ".ipynb_checkpoints" | grep -vFf <(echo "$SKIP_NOTEBOOKS"))
 fi
 
 # Execute notebooks sequentially

docs/_scripts/prepare_notebooks_for_ci.py

@@ -7,7 +7,7 @@ import click
 import nbformat
 
 logger = logging.getLogger(__name__)
-NOTEBOOK_DIRS = ("docs/docs/how-tos","docs/docs/tutorials")
+NOTEBOOK_DIRS = ("docs/how-tos","docs/tutorials")
 DOCS_PATH = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 CASSETTES_PATH = os.path.join(DOCS_PATH, "cassettes")
 
@@ -19,37 +19,37 @@ BLOCKLIST_COMMANDS = (
 )
 
 NOTEBOOKS_NO_CASSETTES = (
-    "docs/docs/how-tos/visualization.ipynb",
-    "docs/docs/how-tos/many-tools.ipynb"
+    "docs/how-tos/visualization.ipynb",
+    "docs/how-tos/many-tools.ipynb"
 )
 
 NOTEBOOKS_NO_EXECUTION = [
     # this uses a user provided project name for langsmith
-    "docs/docs/tutorials/tnt-llm/tnt-llm.ipynb",
+    "docs/tutorials/tnt-llm/tnt-llm.ipynb",
     # this uses langsmith datasets
-    "docs/docs/tutorials/chatbot-simulation-evaluation/langsmith-agent-simulation-evaluation.ipynb",
+    "docs/tutorials/chatbot-simulation-evaluation/langsmith-agent-simulation-evaluation.ipynb",
     # this uses browser APIs
-    "docs/docs/tutorials/web-navigation/web_voyager.ipynb",
+    "docs/tutorials/web-navigation/web_voyager.ipynb",
     # these RAG guides use an ollama model
-    "docs/docs/tutorials/rag/langgraph_adaptive_rag_local.ipynb",
-    "docs/docs/tutorials/rag/langgraph_crag_local.ipynb",
-    "docs/docs/tutorials/rag/langgraph_self_rag_local.ipynb",
+    "docs/tutorials/rag/langgraph_adaptive_rag_local.ipynb",
+    "docs/tutorials/rag/langgraph_crag_local.ipynb",
+    "docs/tutorials/rag/langgraph_self_rag_local.ipynb",
     # this loads a massive dataset from gcp
-    "docs/docs/tutorials/usaco/usaco.ipynb",
+    "docs/tutorials/usaco/usaco.ipynb",
     # TODO: figure out why autogen notebook is not runnable (they are just hanging. possible due to code execution?)
-    "docs/docs/how-tos/autogen-integration.ipynb",
-    "docs/docs/how-tos/autogen-integration-functional.ipynb",
+    "docs/how-tos/autogen-integration.ipynb",
+    "docs/how-tos/autogen-integration-functional.ipynb",
     # TODO: need to update these notebooks to make sure they are runnable in CI
-    "docs/docs/tutorials/storm/storm.ipynb",  # issues only when running with VCR
-    "docs/docs/tutorials/lats/lats.ipynb",  # issues only when running with VCR
-    "docs/docs/tutorials/rag/langgraph_crag.ipynb",  # flakiness from tavily
-    "docs/docs/tutorials/rag/langgraph_adaptive_rag.ipynb",  # flakiness only when running in GHA 
-    "docs/docs/tutorials/rag/langgraph_self_rag.ipynb",  # flakiness only when running in GHA
-    "docs/docs/tutorials/rag/langgraph_agentic_rag.ipynb",  # flakiness only when running in GHA
-    "docs/docs/how-tos/map-reduce.ipynb",  # flakiness from structured output, only when running with VCR
-    "docs/docs/tutorials/tot/tot.ipynb",
-    "docs/docs/how-tos/visualization.ipynb",
-    "docs/docs/tutorials/llm-compiler/LLMCompiler.ipynb"
+    "docs/tutorials/storm/storm.ipynb",  # issues only when running with VCR
+    "docs/tutorials/lats/lats.ipynb",  # issues only when running with VCR
+    "docs/tutorials/rag/langgraph_crag.ipynb",  # flakiness from tavily
+    "docs/tutorials/rag/langgraph_adaptive_rag.ipynb",  # flakiness only when running in GHA 
+    "docs/tutorials/rag/langgraph_self_rag.ipynb",  # flakiness only when running in GHA
+    "docs/tutorials/rag/langgraph_agentic_rag.ipynb",  # flakiness only when running in GHA
+    "docs/how-tos/map-reduce.ipynb",  # flakiness from structured output, only when running with VCR
+    "docs/tutorials/tot/tot.ipynb",
+    "docs/how-tos/visualization.ipynb",
+    "docs/tutorials/llm-compiler/LLMCompiler.ipynb"
 ]
 
 
@@ -217,7 +217,7 @@ def process_notebooks(should_comment_install_cells: bool) -> None:
                 except Exception as e:
                     logger.error(f"Error processing {notebook_path}: {e}")
     
-    with open(os.path.join(DOCS_PATH, "notebooks_no_execution.json"), "w") as f:
+    with open("notebooks_no_execution.json", "w") as f:
         json.dump(NOTEBOOKS_NO_EXECUTION, f)
 
 

docs/docs/how-tos/agent-handoffs.ipynb

@@ -83,18 +83,10 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": null,
    "id": "b4864843-00a1-4c88-9a7c-c34e6c31c548",
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "ANTHROPIC_API_KEY:  ········\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "import getpass\n",
     "import os\n",

docs/docs/index.md

@@ -3,4 +3,4 @@ hide_comments: true
 title: Home
 ---
 
-{!README.md!}
+{!../README.md!}

docs/docs/tutorials/introduction.ipynb

@@ -35,18 +35,10 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": null,
    "id": "705d4020-6ee8-44cc-b1a5-8c34e7172fc7",
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "ANTHROPIC_API_KEY:  ········\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "import getpass\n",
     "import os\n",
@@ -2472,7 +2464,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.4"
+   "version": "3.12.3"
   }
  },
  "nbformat": 4,

docs/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "docs",
+  "version": "1.0.0",
+  "license": "MIT",
+  "scripts": {
+    "build": "echo 'export PATH=$PATH:/vercel/.local/bin:$PATH' > ~/.bashrc && source ~/.bashrc && make vercel-build-docs"
+  }
+}

docs/poetry.lock

@@ -1,4 +1,4 @@
-# This file is automatically @generated by Poetry 1.8.3 and should not be changed by hand.
+# This file is automatically @generated by Poetry 1.8.5 and should not be changed by hand.
 
 [[package]]
 name = "aiohappyeyeballs"
@@ -3050,7 +3050,7 @@ langgraph-sdk = "^0.1.42"
 
 [package.source]
 type = "directory"
-url = "libs/langgraph"
+url = "../libs/langgraph"
 
 [[package]]
 name = "langgraph-checkpoint"
@@ -3067,7 +3067,7 @@ msgpack = "^1.1.0"
 
 [package.source]
 type = "directory"
-url = "libs/checkpoint"
+url = "../libs/checkpoint"
 
 [[package]]
 name = "langgraph-checkpoint-mongodb"
@@ -3103,7 +3103,7 @@ psycopg-pool = "^3.2.0"
 
 [package.source]
 type = "directory"
-url = "libs/checkpoint-postgres"
+url = "../libs/checkpoint-postgres"
 
 [[package]]
 name = "langgraph-checkpoint-sqlite"
@@ -3120,7 +3120,7 @@ langgraph-checkpoint = "^2.0.10"
 
 [package.source]
 type = "directory"
-url = "libs/checkpoint-sqlite"
+url = "../libs/checkpoint-sqlite"
 
 [[package]]
 name = "langgraph-sdk"
@@ -3137,7 +3137,7 @@ orjson = ">=3.10.1"
 
 [package.source]
 type = "directory"
-url = "libs/sdk-py"
+url = "../libs/sdk-py"
 
 [[package]]
 name = "langsmith"
@@ -7487,4 +7487,4 @@ type = ["pytest-mypy"]
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.10"
-content-hash = "5df4a9a753999458fc4154797633a64ae4c6da9986cb2ed6b03ea86d23684a7f"
+content-hash = "15daa424aca22c2e42fb967d97a7cdd1786a57d2e3523934c7a54dcc48e4cacb"

docs/pyproject.toml

@@ -11,11 +11,11 @@ python = "^3.10"
 aiohappyeyeballs = "2.4.3"
 
 [tool.poetry.group.docs.dependencies]
-langgraph = { path = "libs/langgraph/", develop = true }
-langgraph-checkpoint = { path = "libs/checkpoint/", develop = true }
-langgraph-checkpoint-sqlite = { path = "libs/checkpoint-sqlite", develop = true }
-langgraph-checkpoint-postgres = { path = "libs/checkpoint-postgres", develop = true }
-langgraph-sdk = {path = "libs/sdk-py", develop = true}
+langgraph = { path = "../libs/langgraph/", develop = true }
+langgraph-checkpoint = { path = "../libs/checkpoint/", develop = true }
+langgraph-checkpoint-sqlite = { path = "../libs/checkpoint-sqlite", develop = true }
+langgraph-checkpoint-postgres = { path = "../libs/checkpoint-postgres", develop = true }
+langgraph-sdk = {path = "../libs/sdk-py", develop = true}
 mkdocs = "^1.6.0"
 mkdocs-autorefs = ">=1.0.1,<1.1.0"
 mkdocstrings = "^0.25.1"

docs/vercel.json

@@ -0,0 +1,4 @@
+{
+  "buildCommand": "yarn build",
+  "outputDirectory": "site"
+}