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

.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_py.yml

@@ -6,11 +6,8 @@ on:
   push:
     branches:
       - main
-    paths:
-      - "py/**"
   pull_request:
-    paths:
-      - "py/**"
+
 env:
   UV_VERSION: "0.7.20"
 
@@ -38,16 +35,16 @@ jobs:
         run: python --version
 
       - name: Build
-        working-directory: py
+        working-directory: py/llama-cloud-services-py
         run: uv build
 
       - name: Test installing built package
         shell: bash
-        working-directory: py
+        working-directory: py/llama-cloud-services-py
         run: |
           uv venv
           uv pip install dist/*.whl
 
       - name: Test import
-        working-directory: py
+        working-directory: py/llama-cloud-services-py
         run: uv run -- python -c "import llama_cloud_services"

.github/workflows/build_package_ts.yml

@@ -1,36 +0,0 @@
-name: Build Package - TypeScript
-on:
-  push:
-    branches:
-      - main
-    paths:
-      - "ts/**"
-  pull_request:
-    paths:
-      - "ts/**"
-
-jobs:
-  pre_release:
-    name: Pre Release
-    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
-        working-directory: ts/llama_cloud_services/
-        run: pnpm run build

.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/claude-code.yml

@@ -1,95 +0,0 @@
-name: Claude Code
-
-on:
-  issue_comment:
-    types: [created]
-  pull_request_review_comment:
-    types: [created]
-  issues:
-    types: [opened, assigned]
-  pull_request_review:
-    types: [submitted]
-
-jobs:
-  claude:
-    if: |
-      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
-      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
-      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
-      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      pull-requests: read
-      issues: read
-      id-token: write
-    steps:
-      - name: Check repository access
-        id: check-access
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          # Get the user who triggered the event
-          case "${{ github.event_name }}" in
-            "issue_comment")
-              USER="${{ github.event.comment.user.login }}"
-              ;;
-            "pull_request_review_comment")
-              USER="${{ github.event.comment.user.login }}"
-              ;;
-            "pull_request_review")
-              USER="${{ github.event.review.user.login }}"
-              ;;
-            "issues")
-              USER="${{ github.event.issue.user.login }}"
-              ;;
-          esac
-
-          echo "Checking repository access for user: $USER"
-
-          # Check if user has write access to the repository
-          REPO="${{ github.repository }}"
-          if gh api repos/$REPO/collaborators/$USER/permission --jq '.permission' | grep -E "(admin|write)" > /dev/null 2>&1; then
-            echo "User $USER has write access to the repository"
-            echo "authorized=true" >> $GITHUB_OUTPUT
-          else
-            echo "User $USER does not have write access to the repository"
-            echo "authorized=false" >> $GITHUB_OUTPUT
-            exit 1
-          fi
-
-      - name: Checkout repository
-        if: steps.check-access.outputs.authorized == 'true'
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 1
-
-      - name: Run Claude Code
-        if: steps.check-access.outputs.authorized == 'true'
-        id: claude
-        uses: anthropics/claude-code-action@beta
-        with:
-          anthropic_api_key: ${{ secrets.ANTHROPIC_GITHUB_API_KEY }}
-
-          # Optional: Specify model (defaults to Claude Sonnet 4, uncomment for Claude Opus 4)
-          # model: "claude-opus-4-20250514"
-
-          # Optional: Customize the trigger phrase (default: @claude)
-          # trigger_phrase: "/claude"
-
-          # Optional: Trigger when specific user is assigned to an issue
-          # assignee_trigger: "claude-bot"
-
-          # Optional: Allow Claude to run specific commands
-          # Allow bash commands to be run, for things like running tests, linting, etc.
-          allowed_tools: "Bash(rg:*),Bash(find:*),Bash(grep:*),Bash(pnpm:*),Bash(npm:*),Bash(uv:*),Bash(pip:*),Bash(pipx:*),Bash(make:*),Bash(cd:*),WebFetch"
-
-          # Optional: Add custom instructions for Claude to customize its behavior for your project
-          # custom_instructions: |
-          #   Follow our coding standards
-          #   Ensure all new code has tests
-          #   Use TypeScript for new files
-
-          # Optional: Custom environment variables for Claude
-          # claude_env: |
-          #   NODE_ENV: test

.github/workflows/lint_format_build_ts.yml

@@ -1,14 +1,10 @@
-name: Lint - TypeScript
+name: Lint, Format and Build - TypeScript
 
 on:
   push:
     branches:
       - main
-    paths:
-      - "ts/**"
   pull_request:
-    paths:
-      - "ts/**"
 
 env:
   TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
@@ -22,16 +18,13 @@ jobs:
       - uses: actions/checkout@v4
       - uses: pnpm/action-setup@v4
         with:
-          version: 10
+          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
-        working-directory: ts/llama_cloud_services/
-        run: pnpm run lint
-      - name: Run Prettier
-        working-directory: ts/llama_cloud_services/
-        run: pnpm run format
+      - name: Run lint, formatting and building
+        run: pnpm pre-commit

.github/workflows/lint_py.yml

@@ -31,5 +31,5 @@ jobs:
 
       - name: Run linter
         shell: bash
-        working-directory: py
+        working-directory: py/llama-cloud-services-py
         run: uv run -- pre-commit run -a

.github/workflows/release_py.yml

@@ -24,33 +24,20 @@ jobs:
         with:
           version: ${{ env.UV_VERSION }}
 
-      - name: Set up Python
-        run: uv python install
+      - name: Install pnpm
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
 
-      - name: Display Python version
-        run: python --version
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: "ts/llama_cloud_services/.nvmrc"
 
-      - name: Build
-        working-directory: py
-        run: uv build
-
-      - name: Test installing built package
-        shell: bash
-        working-directory: py
-        run: |
-          uv venv
-          uv pip install dist/*.whl
-
-      - name: Publish package
-        shell: bash
-        working-directory: py
-        run: uv publish --token ${{ secrets.LLAMA_PARSE_PYPI_TOKEN }}
-
-      - name: Build and publish llama-parse
-        working-directory: py/llama_parse/
-        run: |
-          uv build
-          uv publish --token ${{ secrets.LLAMA_PARSE_PYPI_TOKEN }}
+      - 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

.github/workflows/release_ts.yml

@@ -22,12 +22,9 @@ jobs:
           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 Build
-        working-directory: ts/llama_cloud_services/
-        run: pnpm build
-
       - name: Build tarball
         run: |
           pnpm pack
@@ -39,11 +36,10 @@ jobs:
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
 
       - name: Release
-        working-directory: ts/llama_cloud_services
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: pnpm publish --access public --no-git-checks
+        run: pnpm release-ts
 
       - name: Create release
         uses: ncipollo/release-action@v1

.github/workflows/test_e2e_py.yml

@@ -1,38 +0,0 @@
-name: Test end-to-end - Python
-
-on:
-  pull_request:
-    paths:
-      - "py/**"
-
-env:
-  UV_VERSION: "0.7.20"
-  LLAMA_CLOUD_API_KEY: ${{ secrets.LLAMA_CLOUD_API_KEY }}
-
-jobs:
-  test_e2e:
-    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.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
-        run: uv run pytest unit_tests/ tests/ -v
-
-      - name: Remove virtual environment
-        working-directory: py
-        run: rm -rf .venv/

.github/workflows/test_py.yml

@@ -4,14 +4,11 @@ on:
   push:
     branches:
       - main
-    paths:
-      - "py/**"
   pull_request:
-    paths:
-      - "py/**"
 
 env:
   UV_VERSION: "0.7.20"
+  LLAMA_CLOUD_API_KEY: ${{ secrets.LLAMA_CLOUD_API_KEY }}
 
 jobs:
   test:
@@ -34,9 +31,9 @@ jobs:
         run: uv python install ${{ matrix.python-version }} && uv python pin ${{ matrix.python-version }}
 
       - name: Run Tests
-        working-directory: py
-        run: uv run pytest unit_tests/ -v
+        working-directory: py/llama-cloud-services-py
+        run: uv run -- pytest tests/**/test_*.py
 
       - name: Remove virtual environment
-        working-directory: py
+        working-directory: py/llama-cloud-services-py
         run: rm -rf .venv/

.github/workflows/test_ts.yml

@@ -4,11 +4,9 @@ on:
   push:
     branches:
       - main
-    paths:
-      - "ts/**"
   pull_request:
-    paths:
-      - "ts/**"
+    branches:
+      - main
 
 env:
   TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
@@ -17,8 +15,7 @@ env:
   LLAMA_CLOUD_API_KEY: ${{ secrets.LLAMA_CLOUD_API_KEY }}
 
 jobs:
-  test:
-    name: Test - TypeScript
+  lint:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -30,13 +27,8 @@ jobs:
         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 Build
+      - name: Run tests
         working-directory: ts/llama_cloud_services/
-        run: pnpm build
-      - name: Run Tests
-        working-directory: ts/llama_cloud_services/
-        run: pnpm test
-      - name: Run e2e tests
-        working-directory: ts/e2e-tests/
-        run: pnpm test
+        run: pnpm test --run

.gitignore

@@ -9,3 +9,5 @@ __pycache__/
 node_modules/
 .turbo/
 dist/
+pnpm-lock.yaml
+.venv/

.pre-commit-config.yaml

@@ -15,7 +15,6 @@ repos:
       - id: end-of-file-fixer
       - id: mixed-line-ending
       - id: trailing-whitespace
-        exclude: ^ts/llama_cloud_services/src/client/
   - repo: https://github.com/charliermarsh/ruff-pre-commit
     rev: v0.1.5
 
@@ -34,7 +33,7 @@ repos:
     rev: v1.0.1
     hooks:
       - id: mypy
-        exclude: ^py/tests|^py/unit_tests
+        exclude: ^py/llama-cloud-services-py/tests/
         additional_dependencies:
           [
             "types-requests",
@@ -64,13 +63,13 @@ repos:
     rev: v3.0.3
     hooks:
       - id: prettier
-        exclude: ^(uv.lock|ts/llama_cloud_services/pnpm-lock.yaml|ts/e2e-tests)
+        exclude: uv.lock
   - repo: https://github.com/codespell-project/codespell
     rev: v2.2.6
     hooks:
       - id: codespell
         additional_dependencies: [tomli]
-        exclude: ^(uv.lock|docs|ts|examples|pnpm-lock.yaml)
+        exclude: ^(uv.lock|docs|ts)
         args:
           [
             "--ignore-words-list",
@@ -87,4 +86,4 @@ repos:
       - id: toml-sort-fix
         exclude: ".*uv.lock"
 
-exclude: ^(.github/ISSUE_TEMPLATE|ts/llama_cloud_services/src/client|pnpm-lock.yaml)
+exclude: .github/ISSUE_TEMPLATE

CONTRIBUTING.md

@@ -1,33 +1,167 @@
-# Python
+# Contribute to `llama-cloud-services`
 
-## Installation
+## Common Patterns
 
-This project uses uv. Create a virtual environment, and run `uv sync`
+### Issues
 
-## Versioning (Maintainers only)
+One of the forms of contribution can be issues.
 
-Before merging your changes, make sure to bump the versions.
+Issues should be used when there are bugs or feature request you would like to bring to the attention of the maintainers.
 
-Make a version bump to `pyproject.toml`. If the underlying dependency on the llamacloud platform OpenAPI
-sdk needs bumping, make sure to bring that in as well. If updating dependencies, run `uv lock`.
+When opening an issue:
 
-The legacy `llama_parse` package re-exports some of `llama_cloud_services` in the old namespace. The
-versions need to be kept consistent to sidecar it with `llama_cloud_services`. Bump it's version in `llama_parse/pyproject.toml`, and also bump it's dependency version of `llama-cloud-services` to match.
+- 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.
 
-**Note**: Don't worry about updating the `llama_parse/poetry.lock` file when bumping versions. The GitHub action will automatically run `poetry lock` for the llama_parse package during the build process (though it doesn't commit the updated lockfile back to the repo).
+### Pull requests
 
-You can also do this with `./scripts/version-bump.py set 0.x.x` if you have `uv` installed.
+In order to open a valid pull request:
 
-Once the change is merged, push a tag `git tag -a v0.x.x -m 0.x.x` and `git push origin 0.x.x`.
+- 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
 
-This tagging step can be done with `./scripts/version-bump tag`.
+## Python
 
-# Typescript
+### Set Up
 
-## Installation
+The two python packages, which can be found under `py/llama-cloud-services-py/`, are:
 
-...
+- `llama-cloud-services`
+- `llama-parse`
 
-## Versioning
+> [!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.

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!