ci: add a changeset release action; docs: contributing update

* feat: add ts examples (clean)

* chore: correct title

.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "restricted",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.github/workflows/build_package.yml

@@ -1,48 +0,0 @@
-name: Build Package
-
-# Build package on its own without additional pip install
-
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-
-env:
-  POETRY_VERSION: "1.6.1"
-
-jobs:
-  build:
-    runs-on: ${{ matrix.os }}
-    strategy:
-      # You can use PyPy versions in python-version.
-      # For example, pypy-2.7 and pypy-3.8
-      matrix:
-        os: [ubuntu-latest, windows-latest]
-        python-version: ["3.9"]
-    steps:
-      - uses: actions/checkout@v4
-      - name: Set up python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python-version }}
-      - name: Install Poetry
-        uses: snok/install-poetry@v1
-        with:
-          version: ${{ env.POETRY_VERSION }}
-      - name: Install deps
-        shell: bash
-        run: poetry install
-      - name: Ensure lock works
-        shell: bash
-        run: poetry lock
-      - name: Build
-        shell: bash
-        run: poetry build
-      - name: Test installing built package
-        shell: bash
-        run: python -m pip install .
-      - name: Test import
-        shell: bash
-        working-directory: ${{ vars.RUNNER_TEMP }}
-        run: python -c "import llama_cloud_services"

.github/workflows/build_package_py.yml

@@ -0,0 +1,50 @@
+name: Build Package - Python
+
+# Build package on its own without additional pip install
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+env:
+  UV_VERSION: "0.7.20"
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      # You can use PyPy versions in python-version.
+      # For example, pypy-2.7 and pypy-3.8
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.9"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: ${{ env.UV_VERSION }}
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Display Python version
+        run: python --version
+
+      - name: Build
+        working-directory: py/llama-cloud-services-py
+        run: uv build
+
+      - name: Test installing built package
+        shell: bash
+        working-directory: py/llama-cloud-services-py
+        run: |
+          uv venv
+          uv pip install dist/*.whl
+
+      - name: Test import
+        working-directory: py/llama-cloud-services-py
+        run: uv run -- python -c "import llama_cloud_services"

.github/workflows/changeset_release.yml

@@ -0,0 +1,67 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v3
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ".nvmrc"
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Add auth token to .npmrc file
+        run: |
+          cat << EOF >> ".npmrc"
+            //registry.npmjs.org/:_authToken=$NPM_TOKEN
+          EOF
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Get changeset status
+        id: get-changeset-status
+        run: |
+          pnpm changeset status --output .changeset/status.json
+          new_version=$(jq -r '.releases[0].newVersion' < .changeset/status.json)
+          rm -v .changeset/status.json
+          echo "new-version=${new_version}" >> "$GITHUB_OUTPUT"
+
+      - name: Create Release Pull Request or Publish to npm
+        id: changesets
+        uses: changesets/action@v1
+        with:
+          commit: Release ${{ steps.get-changeset-status.outputs.new-version }}
+          title: Release ${{ steps.get-changeset-status.outputs.new-version }}
+          # bump versions
+          version: pnpm new-version
+          # build package and call changeset publish
+          publish: pnpm release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          LLAMA_PARSE_PYPI_TOKEN: ${{ secrets.LLAMA_PARSE_PYPI_TOKEN }}
+          UV_PUBLISH_TOKEN: ${{ secrets.LLAMA_PARSE_PYPI_TOKEN }}

.github/workflows/lint_format_build_ts.yml

@@ -0,0 +1,30 @@
+name: Lint, Format and Build - TypeScript
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+env:
+  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+  TURBO_TEAM: ${{ vars.TURBO_TEAM }}
+  TURBO_REMOTE_ONLY: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: "10.12.4"
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: "ts/llama_cloud_services/.nvmrc"
+      - name: Install dependencies
+        working-directory: ts/llama_cloud_services/
+        run: pnpm install --no-frozen-lockfile
+      - name: Run lint, formatting and building
+        run: pnpm pre-commit

.github/workflows/lint_py.yml

@@ -1,4 +1,4 @@
-name: Linting
+name: Lint - Python
 
 on:
   push:
@@ -7,7 +7,7 @@ on:
   pull_request:
 
 env:
-  POETRY_VERSION: "1.6.1"
+  UV_VERSION: "0.7.20"
 
 jobs:
   build:
@@ -21,17 +21,15 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: ${{ github.event_name == 'pull_request' && 2 || 0 }}
-      - name: Set up python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
         with:
-          python-version: ${{ matrix.python-version }}
-      - name: Install Poetry
-        uses: snok/install-poetry@v1
-        with:
-          version: ${{ env.POETRY_VERSION }}
-      - name: Install pre-commit
-        shell: bash
-        run: poetry run pip install pre-commit
+          version: ${{ env.UV_VERSION }}
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+
       - name: Run linter
         shell: bash
-        run: poetry run make lint
+        working-directory: py/llama-cloud-services-py
+        run: uv run -- pre-commit run -a

.github/workflows/publish_release.yml

@@ -1,83 +0,0 @@
-name: Publish llama-parse to PyPI / GitHub
-
-on:
-  push:
-    tags:
-      - "v*"
-
-  workflow_dispatch:
-
-env:
-  POETRY_VERSION: "1.6.1"
-  PYTHON_VERSION: "3.9"
-
-jobs:
-  build-n-publish:
-    name: Build and publish to PyPI
-    if: github.repository == 'run-llama/llama_cloud_services'
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v4
-      - name: Set up python ${{ env.PYTHON_VERSION }}
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ env.PYTHON_VERSION }}
-
-      - name: Install Poetry
-        uses: snok/install-poetry@v1
-        with:
-          version: ${{ env.POETRY_VERSION }}
-
-      - name: Install deps
-        shell: bash
-        run: pip install -e .
-
-      - name: Build and publish llama-cloud-services
-        uses: JRubics/poetry-publish@v2.1
-        with:
-          pypi_token: ${{ secrets.LLAMA_PARSE_PYPI_TOKEN }}
-          poetry_install_options: "--without dev"
-
-      - name: Wait for PyPI to update
-        run: |
-          sleep 60
-
-      - name: Update llama-parse lock file
-        run: |
-          cd llama_parse && poetry lock
-
-      - name: Build and publish llama-parse
-        uses: JRubics/poetry-publish@v2.1
-        with:
-          package_directory: "./llama_parse"
-          pypi_token: ${{ secrets.LLAMA_PARSE_PYPI_TOKEN }}
-          poetry_install_options: "--without dev"
-
-      - name: Create GitHub Release
-        id: create_release
-        uses: actions/create-release@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # This token is provided by Actions, you do not need to create your own token
-        with:
-          tag_name: ${{ github.ref }}
-          release_name: ${{ github.ref }}
-          draft: false
-          prerelease: false
-
-      - name: Get Asset name
-        run: |
-          export PKG=$(ls dist/ | grep tar)
-          set -- $PKG
-          echo "name=$1" >> $GITHUB_ENV
-
-      - name: Upload Release Asset (sdist) to GitHub
-        id: upload-release-asset
-        uses: actions/upload-release-asset@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          upload_url: ${{ steps.create_release.outputs.upload_url }}
-          asset_path: dist/${{ env.name }}
-          asset_name: ${{ env.name }}
-          asset_content_type: application/zip

.github/workflows/release_py.yml

@@ -0,0 +1,53 @@
+name: Publish Release - Python
+
+on:
+  push:
+    tags:
+      - "v*"
+
+  workflow_dispatch:
+
+env:
+  UV_VERSION: "0.7.20"
+
+jobs:
+  build-n-publish:
+    name: Build and publish to PyPI
+    if: github.repository == 'run-llama/llama_cloud_services'
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: ${{ env.UV_VERSION }}
+
+      - name: Install pnpm
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: "ts/llama_cloud_services/.nvmrc"
+
+      - name: Publish llama-cloud-services and llama-parse
+        run: pnpm release-py
+        env:
+          LLAMA_PARSE_PYPI_TOKEN: ${{ secrets.LLAMA_PARSE_PYPI_TOKEN }}
+
+      - name: Create GitHub Release
+        id: create_release
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # This token is provided by Actions, you do not need to create your own token
+        with:
+          tag_name: ${{ github.ref }}
+          release_name: ${{ github.ref }} - LlamaCloud Services PY
+          artifacts: "py/**/dist/*"
+          generateReleaseNotes: true
+          draft: false
+          prerelease: false

.github/workflows/release_ts.yml

@@ -0,0 +1,50 @@
+name: Publish Release - TypeScript
+
+on:
+  push:
+    tags:
+      - "llama-cloud-services@*"
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: "ts/llama_cloud_services/.nvmrc"
+
+      - name: Install dependencies
+        working-directory: ts/llama_cloud_services
+        run: pnpm install --no-frozen-lockfile
+
+      - name: Build tarball
+        run: |
+          pnpm pack
+        working-directory: ts/llama_cloud_services
+
+      - name: Setup npm authentication
+        run: echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: pnpm release-ts
+
+      - name: Create release
+        uses: ncipollo/release-action@v1
+        with:
+          artifacts: "ts/llama_cloud_services/llama-cloud-services*.tgz"
+          name: Release ${{ github.ref }} - LlamaCloud Services TS
+          bodyFile: "ts/llama_cloud_services/CHANGELOG.md"
+          token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test_py.yml

@@ -0,0 +1,39 @@
+name: Test - Python
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+env:
+  UV_VERSION: "0.7.20"
+  LLAMA_CLOUD_API_KEY: ${{ secrets.LLAMA_CLOUD_API_KEY }}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      # You can use PyPy versions in python-version.
+      # For example, pypy-2.7 and pypy-3.8
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: ${{ env.UV_VERSION }}
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }} && uv python pin ${{ matrix.python-version }}
+
+      - name: Run Tests
+        working-directory: py/llama-cloud-services-py
+        run: uv run -- pytest tests/**/test_*.py
+
+      - name: Remove virtual environment
+        working-directory: py/llama-cloud-services-py
+        run: rm -rf .venv/

.github/workflows/test_ts.yml

@@ -0,0 +1,34 @@
+name: Lint - TypeScript
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+env:
+  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+  TURBO_TEAM: ${{ vars.TURBO_TEAM }}
+  TURBO_REMOTE_ONLY: true
+  LLAMA_CLOUD_API_KEY: ${{ secrets.LLAMA_CLOUD_API_KEY }}
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: "ts/llama_cloud_services/.nvmrc"
+      - name: Install dependencies
+        working-directory: ts/llama_cloud_services/
+        run: pnpm install --no-frozen-lockfile
+      - name: Run tests
+        working-directory: ts/llama_cloud_services/
+        run: pnpm test --run

.github/workflows/unit_test.yml

@@ -1,40 +0,0 @@
-name: Unit Testing
-
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-
-env:
-  POETRY_VERSION: "1.6.1"
-  LLAMA_CLOUD_API_KEY: ${{ secrets.LLAMA_CLOUD_API_KEY }}
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    strategy:
-      # You can use PyPy versions in python-version.
-      # For example, pypy-2.7 and pypy-3.8
-      matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: Set up python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python-version }}
-      - name: Install Poetry
-        uses: snok/install-poetry@v1
-        with:
-          version: ${{ env.POETRY_VERSION }}
-      - name: Install deps
-        shell: bash
-        run: poetry install --with dev
-      - name: Run testing
-        env:
-          CI: true
-        shell: bash
-        run: poetry run pytest tests

.gitignore

@@ -5,3 +5,9 @@ __pycache__/
 .idea
 .env*
 .ipynb_checkpoints*
+*_cache/
+node_modules/
+.turbo/
+dist/
+pnpm-lock.yaml
+.venv/

.pre-commit-config.yaml

@@ -21,19 +21,19 @@ repos:
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
-        exclude: ".*poetry.lock"
+        exclude: ".*uv.lock"
   - repo: https://github.com/psf/black-pre-commit-mirror
     rev: 23.10.1
     hooks:
       - id: black-jupyter
         name: black-src
         alias: black
-        exclude: ".*poetry.lock"
+        exclude: ".*uv.lock"
   - repo: https://github.com/pre-commit/mirrors-mypy
     rev: v1.0.1
     hooks:
       - id: mypy
-        exclude: ^tests/
+        exclude: ^py/llama-cloud-services-py/tests/
         additional_dependencies:
           [
             "types-requests",
@@ -63,13 +63,13 @@ repos:
     rev: v3.0.3
     hooks:
       - id: prettier
-        exclude: poetry.lock
+        exclude: uv.lock
   - repo: https://github.com/codespell-project/codespell
     rev: v2.2.6
     hooks:
       - id: codespell
         additional_dependencies: [tomli]
-        exclude: ^(poetry.lock|examples)
+        exclude: ^(uv.lock|docs|ts)
         args:
           [
             "--ignore-words-list",
@@ -84,6 +84,6 @@ repos:
     rev: v0.23.1
     hooks:
       - id: toml-sort-fix
-        exclude: ".*poetry.lock"
+        exclude: ".*uv.lock"
 
 exclude: .github/ISSUE_TEMPLATE

CONTRIBUTING.md

@@ -0,0 +1,167 @@
+# Contribute to `llama-cloud-services`
+
+## Common Patterns
+
+### Issues
+
+One of the forms of contribution can be issues.
+
+Issues should be used when there are bugs or feature request you would like to bring to the attention of the maintainers.
+
+When opening an issue:
+
+- preferably, use the provided templates
+- check for other issues (closed and open) to avoid duplicates
+- try to be detailed and specific, reporting all the pieces the maintainer would need to have in order to reproduce your issue.
+
+### Pull requests
+
+In order to open a valid pull request:
+
+- Fork the repository
+- Checkout a secondary branch (common prefixes for secondary branches include: `fix`, `feat`, `chore`, `docs`). We tend to prefer the naming convention that uses `/`, such as: `fix/your-awesome-bug-fix`.
+- Add and commit the changes to the secondary branch, following language-specific logic (see below)
+- When the changes are pushed to your branch, open a pull request
+
+## Python
+
+### Set Up
+
+The two python packages, which can be found under `py/llama-cloud-services-py/`, are:
+
+- `llama-cloud-services`
+- `llama-parse`
+
+> [!NOTE]
+>
+> `llama-parse` mostly re-exports from `llama-cloud-services`, so you should not modify that directly.
+
+These packages are managed through [uv](https://docs.astral.sh/uv/), so make sure to have uv [installed](https://docs.astral.sh/uv/getting-started/installation/).
+
+### Tests
+
+It is important to make sure all tests pass after your changes, and cover new features with suitable unit tests.
+
+Tests are found in `py/llama-cloud-services-py/tests/` and you can execute them with:
+
+```bash
+pytest tests/**/test_*.py
+```
+
+### Pre-Commit Versioning
+
+Once you made your changes and tested them, **prior to committing** you should run (from the root folder) this command to automatically bump the version of python packages:
+
+```bash
+pnpm pre-commit-version
+```
+
+this will prompt you to choose what package's version you want to bump and what kind of bump you want to perform. Choose `@llama_cloud_services/llama-cloud-services-py` for python and choose the version bump according to the type of changing you made.
+
+### Pre-commit checks
+
+Before you commit, your files should pass the linting and formatting requirements. In order to do that, you should have `pre-commit` installed and set-up in your repository:
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+Once you have that set up, the files will be automatically linted and formatted according to the requirements.
+
+## TypeScript
+
+### Set Up
+
+The TypeScript package, which can be found under `ts/llama_cloud_services/`, is managed through [`pnpm`](https://pnpm.io), so make sure to have it [installed](https://pnpm.io/installation).
+
+In order to be able to run and test the package, make sure to install all the dependencies:
+
+```bash
+pnpm install
+```
+
+### Activate Test Mode
+
+In order to activate test mode (to dynamically test your changes while you are performing them) you can use:
+
+```bash
+pnpm turbo run dev
+```
+
+### Test
+
+It is important to make sure all tests pass after your changes, and cover new features with suitable unit tests.
+
+Tests are found in `ts/llama_cloud_services/tests/` and you can execute them with:
+
+```bash
+pnpm test
+```
+
+### Pre-Commit Versioning
+
+Once you made your changes and tested them, **prior to committing** you should run (from the root folder) two commands to automatically bump the version of python packages:
+
+```bash
+pnpm pre-commit-version
+```
+
+This will prompt you to choose what package's version you want to bump and what kind of bump you want to perform. Choose `llama-cloud-services` for TypeScript and choose the version bump according to the type of changing you made.
+
+### Pre-commit checks
+
+Before you commit, your files should pass the linting and formatting requirements. In order to do that, run (from the root folder):
+
+```bash
+pnpm pre-commit
+```
+
+The files will be then automatically linted and formatted according to the requirements.
+
+## TypeScript _and_ Python
+
+If you change **both PY and TS**, for versioning run:
+
+```bash
+pnpm pre-commit-version # choose both packages
+pnpm new-version # bumps the version for both packages
+```
+
+## Release (maintainers only)
+
+Every push to main might trigger a release.
+
+Whether a release is pushed out or not depends on the presence of versioning files in `.changesets`: if you want a release to be packaged, then, you need to always run `pnpm pre-commit-version` prior to merging a pull request into main.
+
+You can, nevertheless, manually set up language-specific releases, using the logic reported below.
+
+### Python
+
+To release `llama-cloud-services` and `llama-parse` in Python, run:
+
+```bash
+git checkout main
+git pull
+git tag <your-version> # e.g. v0.7.0
+git push <your-version>
+```
+
+> [!NOTE]
+>
+> The tag must start with `v`
+
+This will trigger the release workflow automatically.
+
+### TypeScript
+
+To release `llama-cloud-services` in TypeScript, run:
+
+```bash
+git checkout main
+git pull
+git tag llama-cloud-services@<your-version> # e.g. llama-cloud-services@0.3.0
+git push origin llama-cloud-services@<your-version>
+```
+
+This will trigger the release workflow automatically.

README.md

@@ -11,6 +11,7 @@ This includes:
 - [LlamaParse](./parse.md) - A GenAI-native document parser that can parse complex document data for any downstream LLM use case (Agents, RAG, data processing, etc.).
 - [LlamaReport (beta/invite-only)](./report.md) - A prebuilt agentic report builder that can be used to build reports from a variety of data sources.
 - [LlamaExtract](./extract.md) - A prebuilt agentic data extractor that can be used to transform data into a structured JSON representation.
+- [LlamaCloud Index](./index.md) - A widely customizable and fully automated document ingestion pipeline that also serves retrieval purposes.
 
 ## Getting Started
 
@@ -25,11 +26,19 @@ Then, get your API key from [LlamaCloud](https://cloud.llamaindex.ai/).
 Then, you can use the services in your code:
 
 ```python
-from llama_cloud_services import LlamaParse, LlamaReport, LlamaExtract
+from llama_cloud_services import (
+    LlamaParse,
+    LlamaReport,
+    LlamaExtract,
+    LlamaCloudIndex,
+)
 
 parser = LlamaParse(api_key="YOUR_API_KEY")
 report = LlamaReport(api_key="YOUR_API_KEY")
 extract = LlamaExtract(api_key="YOUR_API_KEY")
+index = LlamaCloudIndex(
+    "my_first_index", project_name="default", api_key="YOUR_API_KEY"
+)
 ```
 
 See the quickstart guides for each service for more information:
@@ -37,6 +46,7 @@ See the quickstart guides for each service for more information:
 - [LlamaParse](./parse.md)
 - [LlamaReport (beta/invite-only)](./report.md)
 - [LlamaExtract](./extract.md)
+- [LlamaCloud Index](./index.md)
 
 ## Switch to EU SaaS 🇪🇺
 
@@ -55,6 +65,12 @@ from llama_cloud_services import (
 parser = LlamaParse(api_key="YOUR_API_KEY", base_url=EU_BASE_URL)
 report = LlamaReport(api_key="YOUR_API_KEY", base_url=EU_BASE_URL)
 extract = LlamaExtract(api_key="YOUR_API_KEY", base_url=EU_BASE_URL)
+index = LlamaCloudIndex(
+    "my_first_index",
+    project_name="default",
+    api_key="YOUR_API_KEY",
+    base_url=EU_BASE_URL,
+)
 ```
 
 ## Documentation

docs/examples-py/README.md

@@ -0,0 +1,9 @@
+# LlamaCloud Services Examples - Python
+
+In this folder you will find several python notebooks with examples regarding:
+
+- [LlamaParse](./parse/)
+- [LlamaExtract](./extract/)
+- [LlamaReport](./report/)
+
+Follow the instructions of each notebook to get started!

docs/examples-py/parse/demo_table_extraction.ipynb

@@ -0,0 +1,516 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Table Extraction with LlamaParse\n",
+    "\n",
+    "This notebook will show you how to extract tables and save them as CSV files thanks to LlamaParse advanced parsing capabilities."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**1. Install needed dependencies**"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "! pip install llama-cloud-services pandas"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**2. Set you LLAMA_CLOUD_API_KEY as env variable**"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "LLAMA_CLOUD_API_KEY: ··········\n"
+     ]
+    }
+   ],
+   "source": [
+    "import os\n",
+    "from getpass import getpass\n",
+    "\n",
+    "os.environ[\"LLAMA_CLOUD_API_KEY\"] = getpass(\"LLAMA_CLOUD_API_KEY: \")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**3. Initialiaze the parser**"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from llama_cloud_services import LlamaParse\n",
+    "\n",
+    "parser = LlamaParse(result_type=\"markdown\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**4. Get data**\n",
+    "\n",
+    "This is a PDF with _lots_ of tables!"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "--2025-07-16 16:20:41--  https://assets.accessible-digital-documents.com/uploads/2017/01/sample-tables.pdf\n",
+      "Resolving assets.accessible-digital-documents.com (assets.accessible-digital-documents.com)... 3.166.135.2, 3.166.135.62, 3.166.135.51, ...\n",
+      "Connecting to assets.accessible-digital-documents.com (assets.accessible-digital-documents.com)|3.166.135.2|:443... connected.\n",
+      "HTTP request sent, awaiting response... 200 OK\n",
+      "Length: 145494 (142K) [application/pdf]\n",
+      "Saving to: ‘sample-tables.pdf’\n",
+      "\n",
+      "sample-tables.pdf   100%[===================>] 142.08K  --.-KB/s    in 0.04s   \n",
+      "\n",
+      "2025-07-16 16:20:41 (3.72 MB/s) - ‘sample-tables.pdf’ saved [145494/145494]\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "! wget https://assets.accessible-digital-documents.com/uploads/2017/01/sample-tables.pdf"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**5. Parse document**"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Started parsing the file under job_id b53949f7-9017-4b6a-b30c-be6227271ed2\n"
+     ]
+    }
+   ],
+   "source": [
+    "json_result = parser.get_json_result(\"sample-tables.pdf\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**6. Get tables!**"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "tables = parser.get_tables(json_result, \"tables/\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**7. Load tables**\n",
+    "\n",
+    "Let's show one example table!"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/vnd.google.colaboratory.intrinsic+json": {
+       "summary": "{\n  \"name\": \"display(df\",\n  \"rows\": 8,\n  \"fields\": [\n    {\n      \"column\": \"Rainfall\",\n      \"properties\": {\n        \"dtype\": \"string\",\n        \"num_unique_values\": 5,\n        \"samples\": [\n          \"Average\",\n          \"\",\n          \"24 hour high\"\n        ],\n        \"semantic_type\": \"\",\n        \"description\": \"\"\n      }\n    },\n    {\n      \"column\": \"Americas\",\n      \"properties\": {\n        \"dtype\": \"number\",\n        \"std\": 908,\n        \"min\": 9,\n        \"max\": 2010,\n        \"num_unique_values\": 8,\n        \"samples\": [\n          104,\n          133,\n          2010\n        ],\n        \"semantic_type\": \"\",\n        \"description\": \"\"\n      }\n    },\n    {\n      \"column\": \"Asia\",\n      \"properties\": {\n        \"dtype\": \"object\",\n        \"num_unique_values\": 7,\n        \"samples\": [\n          \"\",\n          201.0,\n          28.0\n        ],\n        \"semantic_type\": \"\",\n        \"description\": \"\"\n      }\n    },\n    {\n      \"column\": \"Europe\",\n      \"properties\": {\n        \"dtype\": \"object\",\n        \"num_unique_values\": 7,\n        \"samples\": [\n          \"\",\n          193.0,\n          29.0\n        ],\n        \"semantic_type\": \"\",\n        \"description\": \"\"\n      }\n    },\n    {\n      \"column\": \"Africa\",\n      \"properties\": {\n        \"dtype\": \"object\",\n        \"num_unique_values\": 7,\n        \"samples\": [\n          \"\",\n          144.0,\n          20.0\n        ],\n        \"semantic_type\": \"\",\n        \"description\": \"\"\n      }\n    }\n  ]\n}",
+       "type": "dataframe"
+      },
+      "text/html": [
+       "\n",
+       "  <div id=\"df-94a74c8f-1062-4a80-8d3f-32f0fbadf7bb\" class=\"colab-df-container\">\n",
+       "    <div>\n",
+       "<style scoped>\n",
+       "    .dataframe tbody tr th:only-of-type {\n",
+       "        vertical-align: middle;\n",
+       "    }\n",
+       "\n",
+       "    .dataframe tbody tr th {\n",
+       "        vertical-align: top;\n",
+       "    }\n",
+       "\n",
+       "    .dataframe thead th {\n",
+       "        text-align: right;\n",
+       "    }\n",
+       "</style>\n",
+       "<table border=\"1\" class=\"dataframe\">\n",
+       "  <thead>\n",
+       "    <tr style=\"text-align: right;\">\n",
+       "      <th></th>\n",
+       "      <th>Rainfall</th>\n",
+       "      <th>Americas</th>\n",
+       "      <th>Asia</th>\n",
+       "      <th>Europe</th>\n",
+       "      <th>Africa</th>\n",
+       "    </tr>\n",
+       "  </thead>\n",
+       "  <tbody>\n",
+       "    <tr>\n",
+       "      <th>0</th>\n",
+       "      <td>(inches)</td>\n",
+       "      <td>2010</td>\n",
+       "      <td></td>\n",
+       "      <td></td>\n",
+       "      <td></td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>1</th>\n",
+       "      <td>Average</td>\n",
+       "      <td>104</td>\n",
+       "      <td>201.0</td>\n",
+       "      <td>193.0</td>\n",
+       "      <td>144.0</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>2</th>\n",
+       "      <td>24 hour high</td>\n",
+       "      <td>15</td>\n",
+       "      <td>26.0</td>\n",
+       "      <td>27.0</td>\n",
+       "      <td>18.0</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>3</th>\n",
+       "      <td>12 hour high</td>\n",
+       "      <td>9</td>\n",
+       "      <td>10.0</td>\n",
+       "      <td>11.0</td>\n",
+       "      <td>12.0</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>4</th>\n",
+       "      <td></td>\n",
+       "      <td>2009</td>\n",
+       "      <td></td>\n",
+       "      <td></td>\n",
+       "      <td></td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>5</th>\n",
+       "      <td>Average</td>\n",
+       "      <td>133</td>\n",
+       "      <td>244.0</td>\n",
+       "      <td>155.0</td>\n",
+       "      <td>166.0</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>6</th>\n",
+       "      <td>24 hour high</td>\n",
+       "      <td>27</td>\n",
+       "      <td>28.0</td>\n",
+       "      <td>29.0</td>\n",
+       "      <td>20.0</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>7</th>\n",
+       "      <td>12 hour high</td>\n",
+       "      <td>11</td>\n",
+       "      <td>12.0</td>\n",
+       "      <td>13.0</td>\n",
+       "      <td>16.0</td>\n",
+       "    </tr>\n",
+       "  </tbody>\n",
+       "</table>\n",
+       "</div>\n",
+       "    <div class=\"colab-df-buttons\">\n",
+       "\n",
+       "  <div class=\"colab-df-container\">\n",
+       "    <button class=\"colab-df-convert\" onclick=\"convertToInteractive('df-94a74c8f-1062-4a80-8d3f-32f0fbadf7bb')\"\n",
+       "            title=\"Convert this dataframe to an interactive table.\"\n",
+       "            style=\"display:none;\">\n",
+       "\n",
+       "  <svg xmlns=\"http://www.w3.org/2000/svg\" height=\"24px\" viewBox=\"0 -960 960 960\">\n",
+       "    <path d=\"M120-120v-720h720v720H120Zm60-500h600v-160H180v160Zm220 220h160v-160H400v160Zm0 220h160v-160H400v160ZM180-400h160v-160H180v160Zm440 0h160v-160H620v160ZM180-180h160v-160H180v160Zm440 0h160v-160H620v160Z\"/>\n",
+       "  </svg>\n",
+       "    </button>\n",
+       "\n",
+       "  <style>\n",
+       "    .colab-df-container {\n",
+       "      display:flex;\n",
+       "      gap: 12px;\n",
+       "    }\n",
+       "\n",
+       "    .colab-df-convert {\n",
+       "      background-color: #E8F0FE;\n",
+       "      border: none;\n",
+       "      border-radius: 50%;\n",
+       "      cursor: pointer;\n",
+       "      display: none;\n",
+       "      fill: #1967D2;\n",
+       "      height: 32px;\n",
+       "      padding: 0 0 0 0;\n",
+       "      width: 32px;\n",
+       "    }\n",
+       "\n",
+       "    .colab-df-convert:hover {\n",
+       "      background-color: #E2EBFA;\n",
+       "      box-shadow: 0px 1px 2px rgba(60, 64, 67, 0.3), 0px 1px 3px 1px rgba(60, 64, 67, 0.15);\n",
+       "      fill: #174EA6;\n",
+       "    }\n",
+       "\n",
+       "    .colab-df-buttons div {\n",
+       "      margin-bottom: 4px;\n",
+       "    }\n",
+       "\n",
+       "    [theme=dark] .colab-df-convert {\n",
+       "      background-color: #3B4455;\n",
+       "      fill: #D2E3FC;\n",
+       "    }\n",
+       "\n",
+       "    [theme=dark] .colab-df-convert:hover {\n",
+       "      background-color: #434B5C;\n",
+       "      box-shadow: 0px 1px 3px 1px rgba(0, 0, 0, 0.15);\n",
+       "      filter: drop-shadow(0px 1px 2px rgba(0, 0, 0, 0.3));\n",
+       "      fill: #FFFFFF;\n",
+       "    }\n",
+       "  </style>\n",
+       "\n",
+       "    <script>\n",
+       "      const buttonEl =\n",
+       "        document.querySelector('#df-94a74c8f-1062-4a80-8d3f-32f0fbadf7bb button.colab-df-convert');\n",
+       "      buttonEl.style.display =\n",
+       "        google.colab.kernel.accessAllowed ? 'block' : 'none';\n",
+       "\n",
+       "      async function convertToInteractive(key) {\n",
+       "        const element = document.querySelector('#df-94a74c8f-1062-4a80-8d3f-32f0fbadf7bb');\n",
+       "        const dataTable =\n",
+       "          await google.colab.kernel.invokeFunction('convertToInteractive',\n",
+       "                                                    [key], {});\n",
+       "        if (!dataTable) return;\n",
+       "\n",
+       "        const docLinkHtml = 'Like what you see? Visit the ' +\n",
+       "          '<a target=\"_blank\" href=https://colab.research.google.com/notebooks/data_table.ipynb>data table notebook</a>'\n",
+       "          + ' to learn more about interactive tables.';\n",
+       "        element.innerHTML = '';\n",
+       "        dataTable['output_type'] = 'display_data';\n",
+       "        await google.colab.output.renderOutput(dataTable, element);\n",
+       "        const docLink = document.createElement('div');\n",
+       "        docLink.innerHTML = docLinkHtml;\n",
+       "        element.appendChild(docLink);\n",
+       "      }\n",
+       "    </script>\n",
+       "  </div>\n",
+       "\n",
+       "\n",
+       "    <div id=\"df-54b2aa43-838b-47d3-9209-2fb18153cf87\">\n",
+       "      <button class=\"colab-df-quickchart\" onclick=\"quickchart('df-54b2aa43-838b-47d3-9209-2fb18153cf87')\"\n",
+       "                title=\"Suggest charts\"\n",
+       "                style=\"display:none;\">\n",
+       "\n",
+       "<svg xmlns=\"http://www.w3.org/2000/svg\" height=\"24px\"viewBox=\"0 0 24 24\"\n",
+       "     width=\"24px\">\n",
+       "    <g>\n",
+       "        <path d=\"M19 3H5c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2V5c0-1.1-.9-2-2-2zM9 17H7v-7h2v7zm4 0h-2V7h2v10zm4 0h-2v-4h2v4z\"/>\n",
+       "    </g>\n",
+       "</svg>\n",
+       "      </button>\n",
+       "\n",
+       "<style>\n",
+       "  .colab-df-quickchart {\n",
+       "      --bg-color: #E8F0FE;\n",
+       "      --fill-color: #1967D2;\n",
+       "      --hover-bg-color: #E2EBFA;\n",
+       "      --hover-fill-color: #174EA6;\n",
+       "      --disabled-fill-color: #AAA;\n",
+       "      --disabled-bg-color: #DDD;\n",
+       "  }\n",
+       "\n",
+       "  [theme=dark] .colab-df-quickchart {\n",
+       "      --bg-color: #3B4455;\n",
+       "      --fill-color: #D2E3FC;\n",
+       "      --hover-bg-color: #434B5C;\n",
+       "      --hover-fill-color: #FFFFFF;\n",
+       "      --disabled-bg-color: #3B4455;\n",
+       "      --disabled-fill-color: #666;\n",
+       "  }\n",
+       "\n",
+       "  .colab-df-quickchart {\n",
+       "    background-color: var(--bg-color);\n",
+       "    border: none;\n",
+       "    border-radius: 50%;\n",
+       "    cursor: pointer;\n",
+       "    display: none;\n",
+       "    fill: var(--fill-color);\n",
+       "    height: 32px;\n",
+       "    padding: 0;\n",
+       "    width: 32px;\n",
+       "  }\n",
+       "\n",
+       "  .colab-df-quickchart:hover {\n",
+       "    background-color: var(--hover-bg-color);\n",
+       "    box-shadow: 0 1px 2px rgba(60, 64, 67, 0.3), 0 1px 3px 1px rgba(60, 64, 67, 0.15);\n",
+       "    fill: var(--button-hover-fill-color);\n",
+       "  }\n",
+       "\n",
+       "  .colab-df-quickchart-complete:disabled,\n",
+       "  .colab-df-quickchart-complete:disabled:hover {\n",
+       "    background-color: var(--disabled-bg-color);\n",
+       "    fill: var(--disabled-fill-color);\n",
+       "    box-shadow: none;\n",
+       "  }\n",
+       "\n",
+       "  .colab-df-spinner {\n",
+       "    border: 2px solid var(--fill-color);\n",
+       "    border-color: transparent;\n",
+       "    border-bottom-color: var(--fill-color);\n",
+       "    animation:\n",
+       "      spin 1s steps(1) infinite;\n",
+       "  }\n",
+       "\n",
+       "  @keyframes spin {\n",
+       "    0% {\n",
+       "      border-color: transparent;\n",
+       "      border-bottom-color: var(--fill-color);\n",
+       "      border-left-color: var(--fill-color);\n",
+       "    }\n",
+       "    20% {\n",
+       "      border-color: transparent;\n",
+       "      border-left-color: var(--fill-color);\n",
+       "      border-top-color: var(--fill-color);\n",
+       "    }\n",
+       "    30% {\n",
+       "      border-color: transparent;\n",
+       "      border-left-color: var(--fill-color);\n",
+       "      border-top-color: var(--fill-color);\n",
+       "      border-right-color: var(--fill-color);\n",
+       "    }\n",
+       "    40% {\n",
+       "      border-color: transparent;\n",
+       "      border-right-color: var(--fill-color);\n",
+       "      border-top-color: var(--fill-color);\n",
+       "    }\n",
+       "    60% {\n",
+       "      border-color: transparent;\n",
+       "      border-right-color: var(--fill-color);\n",
+       "    }\n",
+       "    80% {\n",
+       "      border-color: transparent;\n",
+       "      border-right-color: var(--fill-color);\n",
+       "      border-bottom-color: var(--fill-color);\n",
+       "    }\n",
+       "    90% {\n",
+       "      border-color: transparent;\n",
+       "      border-bottom-color: var(--fill-color);\n",
+       "    }\n",
+       "  }\n",
+       "</style>\n",
+       "\n",
+       "      <script>\n",
+       "        async function quickchart(key) {\n",
+       "          const quickchartButtonEl =\n",
+       "            document.querySelector('#' + key + ' button');\n",
+       "          quickchartButtonEl.disabled = true;  // To prevent multiple clicks.\n",
+       "          quickchartButtonEl.classList.add('colab-df-spinner');\n",
+       "          try {\n",
+       "            const charts = await google.colab.kernel.invokeFunction(\n",
+       "                'suggestCharts', [key], {});\n",
+       "          } catch (error) {\n",
+       "            console.error('Error during call to suggestCharts:', error);\n",
+       "          }\n",
+       "          quickchartButtonEl.classList.remove('colab-df-spinner');\n",
+       "          quickchartButtonEl.classList.add('colab-df-quickchart-complete');\n",
+       "        }\n",
+       "        (() => {\n",
+       "          let quickchartButtonEl =\n",
+       "            document.querySelector('#df-54b2aa43-838b-47d3-9209-2fb18153cf87 button');\n",
+       "          quickchartButtonEl.style.display =\n",
+       "            google.colab.kernel.accessAllowed ? 'block' : 'none';\n",
+       "        })();\n",
+       "      </script>\n",
+       "    </div>\n",
+       "\n",
+       "    </div>\n",
+       "  </div>\n"
+      ],
+      "text/plain": [
+       "       Rainfall  Americas   Asia Europe Africa\n",
+       "0      (inches)      2010                     \n",
+       "1       Average       104  201.0  193.0  144.0\n",
+       "2  24 hour high        15   26.0   27.0   18.0\n",
+       "3  12 hour high         9   10.0   11.0   12.0\n",
+       "4                    2009                     \n",
+       "5       Average       133  244.0  155.0  166.0\n",
+       "6  24 hour high        27   28.0   29.0   20.0\n",
+       "7  12 hour high        11   12.0   13.0   16.0"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "import pandas as pd\n",
+    "from IPython.display import display\n",
+    "\n",
+    "df = pd.read_csv(\n",
+    "    \"/content/tables/table_2025_16_07_16_30_01_569.csv\",\n",
+    ")\n",
+    "display(df.fillna(\"\"))"
+   ]
+  }
+ ],
+ "metadata": {
+  "colab": {
+   "provenance": []
+  },
+  "kernelspec": {
+   "display_name": "Python 3",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}