ci: correct changeset actions

.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/release.yml

@@ -0,0 +1,52 @@
+name: Publish - Changeset
+
+on:
+  push:
+    branches: [main]
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  publish:
+    name: Publish
+    runs-on: ubuntu-latest
+    # Only run if this is a merge commit and the PR was authored by github-actions[bot]
+    if: ${{ github.event.head_commit.message != null && startsWith(github.event.head_commit.message, 'Merge pull request') && contains(github.event.head_commit.message, '/changeset-release/main') }}
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v3
+        with:
+          version: 10
+
+      - 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: "ts/llama_cloud_services/.nvmrc"
+
+      - name: Install dependencies
+        run: pnpm install --no-frozen-lockfile
+
+      - 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: Publish packages based on changesets
+        run: |
+          pnpm run release
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          PYPI_TOKEN: ${{ secrets.LLAMA_PARSE_PYPI_TOKEN }}

.github/workflows/version_bump.yml

@@ -0,0 +1,47 @@
+name: Version Bump - Changeset
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  version:
+    name: Version Bump
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v4
+        with:
+          # Need to fetch full history for changesets
+          fetch-depth: 0
+
+      - uses: pnpm/action-setup@v3
+        with:
+          version: 10
+
+      - 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: "ts/cute_cats_terminal/.nvmrc"
+
+      - name: Install dependencies
+        run: pnpm install --no-frozen-lockfile
+
+      - name: Create Release Pull Request
+        id: changesets
+        uses: changesets/action@v1
+        with:
+          version: pnpm run version
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

CONTRIBUTING.md

@@ -1,33 +1,166 @@
-# 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/`, 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/tests/` (end to end) and `py/unit_tests/` (unit tests, no API key required) and you can execute them with:
+
+```bash
+pytest tests/ unit_tests/
+```
+
+### 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/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
+```
+
+## 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. See [version_bump_and_release](./.github/workflows/version_bump_and_release.yml) action to better understand the process.
+
+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.

package.json

@@ -0,0 +1,19 @@
+{
+  "name": "llama_cloud_services",
+  "version": "1.0.0",
+  "private": "true",
+  "license": "MIT",
+  "scripts": {
+    "pre-commit-version": "pnpm changeset",
+    "version": "pnpm version-ts && pnpm version-py",
+    "release": "pnpm release-ts && pnpm release-py",
+    "release-ts": "pnpm run --filter llama-cloud-services release",
+    "release-py": "pnpm run --filter @llama_cloud_services/py release",
+    "version-ts": "pnpm run --filter llama-cloud-services version",
+    "version-py": "pnpm run --filter @llama_cloud_services/py version"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.5",
+    "changesets": "^1.0.2"
+  }
+}

pnpm-workspace.yaml

@@ -1,2 +1,3 @@
 packages:
-  - "ts/**"
+  - "ts/*"
+  - "py/"

py/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@llama_cloud_services/py",
+  "version": "0.6.55",
+  "private": "true",
+  "license": "MIT",
+  "scripts": {
+    "version": "cd .. && pnpm changeset version && bash py/scripts/new_version.sh",
+    "release": "bash scripts/release.sh"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.5",
+    "changesets": "^1.0.2"
+  }
+}

py/scripts/new_version.py

@@ -0,0 +1,34 @@
+import toml  # type: ignore [import]
+import json
+
+
+def change_parse_dep(data: dict, version: str) -> dict:
+    dep, ver = (
+        data["project"]["dependencies"][0].split(">=")[0],
+        data["project"]["dependencies"][0].split(">=")[1],
+    )
+    ver = version
+    dependency = dep + ">=" + ver
+    data["project"]["dependencies"].insert(0, dependency)
+    data["project"]["dependencies"].pop(1)
+    return data
+
+
+with open("py/package.json", "r") as p:
+    package_data = json.load(p)
+
+with open("py/pyproject.toml", "r") as t:
+    toml_data = toml.load(t)
+
+with open("py/llama_parse/pyproject.toml", "r") as pt:
+    parse_toml_data = toml.load(pt)
+
+toml_data["project"]["version"] = package_data["version"]
+parse_toml_data["project"]["version"] = package_data["version"]
+parse_toml_data = change_parse_dep(parse_toml_data, package_data["version"])
+
+with open("py/pyproject.toml", "w") as w:
+    toml.dump(toml_data, w)
+
+with open("py/llama_parse/pyproject.toml", "w") as pw:
+    toml.dump(parse_toml_data, pw)

py/scripts/new_version.sh

@@ -0,0 +1,22 @@
+# create uv virtual environment
+uv venv
+source .venv/bin/activate
+
+# install toml
+uv pip install -r py/scripts/requirements.txt
+
+# run version change
+uv run -- python3 py/scripts/new_version.py
+
+# test version change
+status_code=$(uv run -- python3 py/scripts/test_new_version.py) # returns 0 if the versions are the same, 1 if they are not
+
+if [ "$status_code" -eq 1 ]; then
+   echo "Versions do not match, the version change failed..."
+   exit 1
+elif [ "$status_code" -eq 0 ]; then
+   # lock the version changes
+   cd py/ && uv lock
+   echo "Versions successfully changed"
+   exit 0
+fi

py/scripts/pre_release_check.py

@@ -0,0 +1,21 @@
+import toml  # type: ignore [import]
+import requests
+
+
+def get_latest_version(package_name: str) -> str:
+    url = f"https://pypi.org/pypi/{package_name}/json"
+    response = requests.get(url)
+    if response.status_code == 200:
+        data = response.json()
+        return data["info"]["version"]
+    else:
+        raise Exception(f"Package '{package_name}' not found on PyPI.")
+
+
+with open("pyproject.toml", "r") as t:
+    toml_data = toml.load(t)
+
+if toml_data["project"]["version"] == get_latest_version("llama-cloud-services"):
+    print("1")
+else:
+    print("0")

py/scripts/release.sh

@@ -0,0 +1,36 @@
+# initialize pypi_token
+pypi_token="no_token"
+
+while
+    [[ $# -gt 0 ]] \
+        ;
+do
+    case "$1" in
+    -t | --token)
+        pypi_token="$2"
+    esac
+done
+
+if [[ $pypi_token == "no_token" ]]; then
+    if [[ $LLAMA_PARSE_PYPI_TOKEN == "" ]]; then
+        echo "No token provided and no token in the environment, exiting..."
+        exit 1
+    else
+        pypi_token="$LLAMA_PARSE_PYPI_TOKEN"
+    fi
+fi
+
+# check pre-release
+uv venv && source .venv/bin/activate && uv pip install -r scripts/requirements.txt
+do_not_release=$(python3 scripts/pre_release_check.py)
+
+if [ "$do_not_release" -eq 1 ]; then
+   echo "Nothing to release"
+   exit 0
+else
+    # build and publish llama_cloud_services
+    ## build
+    uv build
+    ## publish
+    uv publish --token $pypi_token
+fi

py/scripts/requirements.txt

@@ -0,0 +1,2 @@
+toml
+requests

py/scripts/test_new_version.py

@@ -0,0 +1,32 @@
+import toml  # type: ignore [import]
+import json
+
+
+def test_versions_equal(
+    package_data: dict, toml_data: dict, parse_toml_data: dict
+) -> None:
+    llama_cloud_version = toml_data["project"]["version"]
+    package_version = package_data["version"]
+    parse_version = parse_toml_data["project"]["version"]
+    parse_dep_version = parse_toml_data["project"]["dependencies"][0].split(">=")[1]
+    try:
+        assert (
+            llama_cloud_version == package_version
+            and llama_cloud_version == parse_version
+            and llama_cloud_version == parse_dep_version
+        )
+        print("0")
+    except AssertionError:
+        print("1")
+
+
+with open("py/package.json", "r") as p:
+    package_data = json.load(p)
+
+with open("py/pyproject.toml", "r") as t:
+    toml_data = toml.load(t)
+
+with open("py/llama_parse/pyproject.toml", "r") as pt:
+    parse_toml_data = toml.load(pt)
+
+test_versions_equal(package_data, toml_data, parse_toml_data)

ts/llama_cloud_services/package.json

@@ -12,7 +12,9 @@
     "test": "vitest run --testTimeout=60000",
     "test:watch": "vitest --watch",
     "test:ui": "vitest --ui",
-    "test:coverage": "vitest --coverage"
+    "test:coverage": "vitest --coverage",
+    "version": "cd .. && pnpm changeset version",
+    "release": "pnpm run build && cd .. && pnpm changeset publish"
   },
   "files": [
     "openapi.json",