chore: bump ts version for parse (#855)

* feat: add parse and getTables methods to LlamaParseReader

* feat: add tests

* fix: loop logic to fix test 🙈

* chore: implement suggestions

.changeset/README.md

@@ -1,8 +0,0 @@
-# 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

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

.github/workflows/build_package_ts.yml

@@ -0,0 +1,36 @@
+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

@@ -1,67 +0,0 @@
-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

@@ -0,0 +1,95 @@
+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_py.yml

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

.github/workflows/lint_ts.yml

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

.github/workflows/release_py.yml

@@ -24,20 +24,33 @@ jobs:
         with:
           version: ${{ env.UV_VERSION }}
 
-      - name: Install pnpm
-      - uses: pnpm/action-setup@v4
-        with:
-          version: 10
+      - name: Set up Python
+        run: uv python install
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version-file: "ts/llama_cloud_services/.nvmrc"
+      - name: Display Python version
+        run: python --version
 
-      - name: Publish llama-cloud-services and llama-parse
-        run: pnpm release-py
-        env:
-          LLAMA_PARSE_PYPI_TOKEN: ${{ secrets.LLAMA_PARSE_PYPI_TOKEN }}
+      - 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: Create GitHub Release
         id: create_release

.github/workflows/release_ts.yml

@@ -22,9 +22,12 @@ 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
@@ -36,10 +39,11 @@ 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 release-ts
+        run: pnpm publish --access public --no-git-checks
 
       - name: Create release
         uses: ncipollo/release-action@v1

.github/workflows/test_e2e_py.yml

@@ -0,0 +1,38 @@
+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,11 +4,14 @@ 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:
@@ -31,9 +34,9 @@ jobs:
         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
+        working-directory: py
+        run: uv run pytest unit_tests/ -v
 
       - name: Remove virtual environment
-        working-directory: py/llama-cloud-services-py
+        working-directory: py
         run: rm -rf .venv/

.github/workflows/test_ts.yml

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

.gitignore

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

.pre-commit-config.yaml

@@ -15,6 +15,7 @@ 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
 
@@ -33,7 +34,7 @@ repos:
     rev: v1.0.1
     hooks:
       - id: mypy
-        exclude: ^py/llama-cloud-services-py/tests/
+        exclude: ^py/tests|^py/unit_tests
         additional_dependencies:
           [
             "types-requests",
@@ -63,13 +64,13 @@ repos:
     rev: v3.0.3
     hooks:
       - id: prettier
-        exclude: uv.lock
+        exclude: ^(uv.lock|ts/llama_cloud_services/pnpm-lock.yaml|ts/e2e-tests)
   - repo: https://github.com/codespell-project/codespell
     rev: v2.2.6
     hooks:
       - id: codespell
         additional_dependencies: [tomli]
-        exclude: ^(uv.lock|docs|ts)
+        exclude: ^(uv.lock|docs|ts|examples|pnpm-lock.yaml)
         args:
           [
             "--ignore-words-list",
@@ -86,4 +87,4 @@ repos:
       - id: toml-sort-fix
         exclude: ".*uv.lock"
 
-exclude: .github/ISSUE_TEMPLATE
+exclude: ^(.github/ISSUE_TEMPLATE|ts/llama_cloud_services/src/client|pnpm-lock.yaml)

CONTRIBUTING.md

@@ -1,167 +1,33 @@
-# Contribute to `llama-cloud-services`
+# Python
 
-## Common Patterns
+## Installation
 
-### Issues
+This project uses uv. Create a virtual environment, and run `uv sync`
 
-One of the forms of contribution can be issues.
+## Versioning (Maintainers only)
 
-Issues should be used when there are bugs or feature request you would like to bring to the attention of the maintainers.
+Before merging your changes, make sure to bump the versions.
 
-When opening an issue:
+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`.
 
-- 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.
+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.
 
-### Pull requests
+**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).
 
-In order to open a valid pull request:
+You can also do this with `./scripts/version-bump.py set 0.x.x` if you have `uv` installed.
 
-- 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
+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`.
 
-## Python
+This tagging step can be done with `./scripts/version-bump tag`.
 
-### Set Up
+# Typescript
 
-The two python packages, which can be found under `py/llama-cloud-services-py/`, are:
+## Installation
 
-- `llama-cloud-services`
-- `llama-parse`
+...
 
-> [!NOTE]
->
-> `llama-parse` mostly re-exports from `llama-cloud-services`, so you should not modify that directly.
+## Versioning
 
-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

@@ -1,9 +0,0 @@
-# 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-ts/README.md

@@ -1,10 +0,0 @@
-# LlamaCloud Services Examples - TypeScript
-
-In this folder you will find two end-to-end examples on how to build applications with:
-
-- [LlamaParse](./parse/)
-- [LlamaCloud Index](./index)
-
-In TypeScript.
-
-Follow the instruction in each of the example sub-folders to get started!

docs/examples-ts/index/.example.env

@@ -1,3 +0,0 @@
-LLAMA_CLOUD_API_KEY="llx-***"
-OPENAI_API_KEY="sk-***"
-PIPELINE_NAME="my-pipeline"

examples-ts/README.md

@@ -0,0 +1,8 @@
+# LlamaCloud Services Examples - Python
+
+In this folder you will find several TypeScript end-to-end applications that contain examples regarding:
+
+- [LlamaParse](./parse/)
+- [LlamaCloud Index](./index/)
+
+Follow the instructions in each example folder to get started!

examples-ts/extract/README.md

@@ -0,0 +1,122 @@
+# LlamaExtract Demo
+
+A TypeScript demo application showcasing the power of **LlamaExract** - a structured data extraction agentic service from [LlamaCloud](https://cloud.llamaindex.ai). This demo allows you to extract structured information from scientific papers and get them into a nice markdown format.
+
+## Table of Contents
+
+- [Features](#features)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Start the Demo](#start-the-demo)
+  - [Development Mode](#development-mode)
+  - [Build the Project](#build-the-project)
+  - [Code Quality](#code-quality)
+  - [Quick Commands Reference](#quick-commands-reference)
+- [How It Works](#how-it-works)
+- [API Dependencies](#api-dependencies)
+- [Troubleshooting](#troubleshooting)
+  - [Common Issues](#common-issues)
+- [License](#license)
+- [Contributing](#contributing)
+
+## Features
+
+- 📄 **Structured Data Extraction**: Extract data from your files effortlessly, and structure them the way you want!
+- 🤖 **Markdown Rendering**: Generate markdown directly from your extracted data
+- 🎨 **Beautiful CLI**: Styled console interface with colors and ASCII art
+- ⚡ **Fast Development**: Hot reload support with watch mode
+- 🛠️ **TypeScript**: Full TypeScript support with strict type checking
+
+## Prerequisites
+
+- Node.js (version 18 or higher)
+- pnpm package manager
+- LlamaCloud API key
+
+## Installation
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/run-llama/llama_cloud_services
+cd lama_cloud_services/examples-ts/extract/
+```
+
+2. Install dependencies:
+
+```bash
+npm install
+```
+
+3. Set up your environment variables:
+
+```bash
+# Add your API key to your environment
+export LLAMA_CLOUD_API_KEY="your-llamacloud-api-key"
+```
+
+## Usage
+
+### Start the Demo
+
+```bash
+npm run start
+```
+
+The application will display a welcome screen and prompt you to enter the path to a document you'd like to process.
+
+### Development Mode
+
+For development with hot reload:
+
+```bash
+npm run dev
+```
+
+### Build the Project
+
+```bash
+npm run build
+```
+
+### Code Quality
+
+Format code:
+
+```bash
+npm run format
+```
+
+Lint code:
+
+```bash
+npm run lint
+```
+
+## How It Works
+
+1. **Document Input**: Enter the path to your document when prompted
+2. **Parsing**: LlamaExtract, based on the schema you can find [here](./src/schema.ts), processes the document and extracts structured data
+3. **Markdown Rendering**: The extracted content is rendered into beautiful markdown
+4. **Results**: View the results directly in your terminal
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Module Resolution Errors**: Ensure you're using Node.js 18+ and have all dependencies installed
+2. **API Key Issues**: Verify your LlamaCloud API key is correctly set
+3. **File Path Errors**: Use absolute paths or ensure relative paths are correct from the project root
+
+## License
+
+MIT License - see the [LICENSE](../../LICENSE) file for details.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run `npm run format` and `npm run lint`
+5. Submit a pull request

examples-ts/extract/eslint.config.mts

@@ -0,0 +1,14 @@
+import js from "@eslint/js";
+import globals from "globals";
+import tseslint from "typescript-eslint";
+import { defineConfig } from "eslint/config";
+
+export default defineConfig([
+  {
+    files: ["**/*.{js,mjs,cjs,ts,mts,cts}"],
+    plugins: { js },
+    extends: ["js/recommended"],
+    languageOptions: { globals: globals.browser },
+  },
+  tseslint.configs.recommended,
+]);

examples-ts/extract/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "llama-extract-demo",
+  "version": "0.1.0",
+  "description": "Demo for LlamaExtract in TypeScript",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"There are no tests\"",
+    "start": "npm exec tsx src/index.ts",
+    "lint": "eslint ./src/",
+    "format": "prettier --write ./src/",
+    "build": "tsc",
+    "dev": "npm exec tsx --watch src/index.ts"
+  },
+  "author": "LlamaIndex",
+  "license": "MIT",
+  "dependencies": {
+    "cli-markdown": "^3.5.1",
+    "consola": "^3.4.2",
+    "figlet": "^1.8.2",
+    "llama-cloud-services": "file:../../ts/llama_cloud_services",
+    "marked": "^15.0.12",
+    "marked-terminal": "^7.3.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.32.0",
+    "@types/figlet": "^1.7.0",
+    "@types/marked-terminal": "^6.1.1",
+    "@types/node": "^24.2.0",
+    "eslint": "^9.32.0",
+    "globals": "^16.3.0",
+    "jiti": "^2.5.1",
+    "prettier": "^3.6.2",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.39.0"
+  }
+}

examples-ts/extract/src/index.ts

@@ -0,0 +1,47 @@
+import { LlamaExtract, ExtractConfig } from "llama-cloud-services";
+import cliMarkdown from "cli-markdown";
+import { logger } from "./logger";
+import pc from "picocolors";
+import { consoleInput, renderLogo } from "./utils";
+import { dataSchema } from "./schema";
+import { renderMarkdown, ResearchData } from "./markdown";
+
+export async function main(): Promise<number> {
+  const extractClient = new LlamaExtract(
+    process.env.LLAMA_CLOUD_API_KEY!,
+    "https://api.cloud.llamaindex.ai",
+  );
+  await renderLogo();
+  logger.log(
+    `Welcome to ${pc.bold(
+      pc.magentaBright("LlamaExtract Demo✨"),
+    )}, our demo for ${pc.bold(pc.green("LlamaExtract"))}, a ${pc.bold(
+      pc.cyan("LlamaCloud☁️"),
+    )}  (https://cloud.llamaindex.ai) product!.\nIn this demo we are going to try extracting relevant information  ${pc.bold(
+      pc.yellowBright("from scientific papers"),
+    )}. Type the path to the paper you would like to process below👇\nIf you wish to exit, just type ${pc.bold(
+      pc.gray("quit"),
+    )}.\n`,
+  );
+  while (true) {
+    const userInput = await consoleInput();
+    if (userInput.toLowerCase() == "quit") {
+      break;
+    }
+    try {
+      const generatedData = await extractClient.extract(
+        dataSchema,
+        {} as ExtractConfig,
+        userInput,
+      );
+      const research = renderMarkdown(generatedData?.data as ResearchData); // Added await here
+      logger.log(`${pc.bold(pc.cyan("Extracted information:✨"))}:\n`);
+      logger.log(cliMarkdown(research));
+    } catch (error) {
+      logger.error(`Error processing file: ${error}`);
+    }
+  }
+  return 0;
+}
+
+main().catch(console.error);

examples-ts/extract/src/markdown.ts

@@ -0,0 +1,172 @@
+type Author = {
+  name: string;
+  affiliation?: string;
+  email?: string;
+};
+
+type Methodology = {
+  approach?: string;
+  participants?: string;
+  methods?: string[];
+};
+
+type Result = {
+  finding?: string;
+  significance?: string;
+  supportingData?: string;
+};
+
+type Reference = {
+  title: string;
+  authors: string;
+  year?: string;
+  relevance?: string;
+};
+
+type Discussion = {
+  implications?: string[];
+  limitations?: string[];
+  futureWork?: string[];
+};
+
+type Publication = {
+  journal?: string;
+  year: string;
+  doi?: string;
+  url?: string;
+};
+
+export type ResearchData = {
+  title: string;
+  authors: Author[];
+  abstract: string;
+  keywords?: string[];
+  mainFindings: string[];
+  methodology?: Methodology;
+  results?: Result[];
+  discussion?: Discussion;
+  references?: Reference[];
+  publication?: Publication;
+};
+
+export function renderMarkdown(data: ResearchData): string {
+  const {
+    title,
+    authors,
+    abstract,
+    keywords,
+    mainFindings,
+    methodology,
+    results,
+    discussion,
+    references,
+    publication,
+  } = data;
+
+  const md: string[] = [];
+
+  md.push(`# ${title}\n`);
+
+  // Authors
+  md.push(`## Authors`);
+  md.push(
+    authors
+      .map(
+        (author) =>
+          `- **${author.name}**${
+            author.affiliation ? `, *${author.affiliation}*` : ""
+          }${author.email ? ` (${author.email})` : ""}`,
+      )
+      .join("\n"),
+  );
+
+  // Abstract
+  md.push(`\n## Abstract\n${abstract}`);
+
+  // Keywords
+  if (keywords && keywords.length > 0) {
+    md.push(`\n## Keywords\n${keywords.map((k) => `- ${k}`).join("\n")}`);
+  }
+
+  // Main Findings
+  md.push(
+    `\n## Main Findings\n${mainFindings.map((f) => `- ${f}`).join("\n")}`,
+  );
+
+  // Methodology
+  if (methodology) {
+    md.push(`\n## Methodology`);
+    if (methodology.approach) md.push(`**Approach:** ${methodology.approach}`);
+    if (methodology.participants)
+      md.push(`**Participants:** ${methodology.participants}`);
+    if (methodology.methods?.length) {
+      md.push(
+        `**Methods:**\n${methodology.methods.map((m) => `- ${m}`).join("\n")}`,
+      );
+    }
+  }
+
+  // Results
+  if (results?.length) {
+    md.push(`\n## Results`);
+    results.forEach((result, i) => {
+      md.push(`\n### Result ${i + 1}`);
+      if (result.finding) md.push(`- **Finding:** ${result.finding}`);
+      if (result.significance)
+        md.push(`- **Significance:** ${result.significance}`);
+      if (result.supportingData)
+        md.push(`- **Supporting Data:** ${result.supportingData}`);
+    });
+  }
+
+  // Discussion
+  if (discussion) {
+    md.push(`\n## Discussion`);
+    if (discussion.implications?.length) {
+      md.push(
+        `### Implications\n${discussion.implications
+          .map((d) => `- ${d}`)
+          .join("\n")}`,
+      );
+    }
+    if (discussion.limitations?.length) {
+      md.push(
+        `### Limitations\n${discussion.limitations
+          .map((d) => `- ${d}`)
+          .join("\n")}`,
+      );
+    }
+    if (discussion.futureWork?.length) {
+      md.push(
+        `### Future Work\n${discussion.futureWork
+          .map((d) => `- ${d}`)
+          .join("\n")}`,
+      );
+    }
+  }
+
+  // References
+  if (references?.length) {
+    md.push(`\n## References`);
+    references.forEach((ref, i) => {
+      md.push(
+        `\n**[${i + 1}]** ${ref.title} — *${ref.authors}*${
+          ref.year ? ` (${ref.year})` : ""
+        }`,
+      );
+      if (ref.relevance) md.push(`> ${ref.relevance}`);
+    });
+  }
+
+  // Publication Info
+  if (publication) {
+    md.push(`\n## Publication`);
+    if (publication.journal) md.push(`- **Journal:** ${publication.journal}`);
+    if (publication.year) md.push(`- **Year:** ${publication.year}`);
+    if (publication.doi) md.push(`- **DOI:** ${publication.doi}`);
+    if (publication.url)
+      md.push(`- **URL:** [${publication.url}](${publication.url})`);
+  }
+
+  return md.join("\n");
+}

examples-ts/extract/src/schema.ts

@@ -0,0 +1,169 @@
+export const dataSchema = {
+  type: "object",
+  required: ["title", "authors", "abstract", "mainFindings"],
+  properties: {
+    title: {
+      type: "string",
+      description: "The full title of the research paper",
+    },
+    authors: {
+      type: "array",
+      description: "List of all authors of the paper",
+      items: {
+        type: "object",
+        properties: {
+          name: {
+            type: "string",
+            description: "Full name of the author",
+          },
+          affiliation: {
+            type: "string",
+            description:
+              "Institution or organization the author is affiliated with",
+          },
+          email: {
+            type: "string",
+            description: "Contact email of the author if provided",
+          },
+        },
+      },
+    },
+    abstract: {
+      type: "string",
+      description: "Complete abstract or summary of the paper",
+    },
+    keywords: {
+      type: "array",
+      description:
+        "Key terms and phrases that describe the paper's main topics",
+      items: {
+        type: "string",
+      },
+    },
+    mainFindings: {
+      type: "array",
+      description: "Key findings, conclusions, or contributions of the paper",
+      items: {
+        type: "string",
+      },
+    },
+    methodology: {
+      type: "object",
+      description: "Research methods and approaches used",
+      properties: {
+        approach: {
+          type: "string",
+          description: "Overall research approach or study design",
+        },
+        participants: {
+          type: "string",
+          description: "Description of study participants or data sources",
+        },
+        methods: {
+          type: "array",
+          description: "Specific methods, techniques, or tools used",
+          items: {
+            type: "string",
+          },
+        },
+      },
+    },
+    results: {
+      type: "array",
+      description: "Main results and outcomes of the research",
+      items: {
+        type: "object",
+        properties: {
+          finding: {
+            type: "string",
+            description: "Description of the specific result or finding",
+          },
+          significance: {
+            type: "string",
+            description:
+              "Statistical significance or importance of the finding",
+          },
+          supportingData: {
+            type: "string",
+            description: "Relevant statistics, measurements, or data points",
+          },
+        },
+      },
+    },
+    discussion: {
+      type: "object",
+      properties: {
+        implications: {
+          type: "array",
+          description: "Theoretical or practical implications of the findings",
+          items: {
+            type: "string",
+          },
+        },
+        limitations: {
+          type: "array",
+          description: "Study limitations or constraints",
+          items: {
+            type: "string",
+          },
+        },
+        futureWork: {
+          type: "array",
+          description: "Suggested future research directions",
+          items: {
+            type: "string",
+          },
+        },
+      },
+    },
+    references: {
+      type: "array",
+      description:
+        "Key papers cited that are crucial to understanding this work",
+      items: {
+        type: "object",
+        properties: {
+          title: {
+            type: "string",
+            description: "Title of the cited paper",
+          },
+          authors: {
+            type: "string",
+            description: "Authors of the cited paper",
+          },
+          year: {
+            type: "string",
+            description: "Publication year",
+          },
+          relevance: {
+            type: "string",
+            description: "Why this reference is important to the current paper",
+          },
+        },
+        required: ["title", "authors"],
+      },
+    },
+    publication: {
+      type: "object",
+      properties: {
+        journal: {
+          type: "string",
+          description: "Name of the journal or conference",
+        },
+        year: {
+          type: "string",
+          description: "Year of publication",
+        },
+        doi: {
+          type: "string",
+          description: "Digital Object Identifier (DOI) of the paper",
+        },
+        url: {
+          type: "string",
+          description: "URL where the paper can be accessed",
+        },
+      },
+      required: ["year"],
+    },
+  },
+};

examples-ts/extract/src/types/cli-markdown.d.ts

@@ -0,0 +1,4 @@
+declare module "cli-markdown" {
+  function cliMarkdown(input: string): string;
+  export default cliMarkdown;
+}

examples-ts/extract/src/utils.ts

@@ -0,0 +1,33 @@
+import * as readline from "readline/promises";
+import figlet from "figlet";
+import pc from "picocolors";
+
+export async function renderLogo(): Promise<void> {
+  const logoText = figlet.textSync("Extract Demo", {
+    font: "ANSI Shadow",
+    horizontalLayout: "default",
+    verticalLayout: "default",
+    width: 100,
+    whitespaceBreak: true,
+  });
+
+  // Add some styling with picocolors
+  const styledLogo = pc.bold(pc.redBright(logoText));
+
+  // Add some padding/margin
+  console.log("\n");
+  console.log(styledLogo);
+  console.log(pc.gray("─".repeat(60)));
+  console.log("\n");
+}
+
+export async function consoleInput(): Promise<string> {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  const answer = await rl.question("Path to your file: ");
+  rl.close();
+  return answer;
+}

examples-ts/index/README.md

@@ -22,7 +22,7 @@ A TypeScript demo application showcasing the power of **LlamaCloud Index** - a f
 
 ## Features
 
-- 🤖 **RAG**: Simple-yet-effective Retrieval Augmented Generation pipeline built on top of LlamaCloud Index adn OpenAI
+- 🤖 **RAG**: Simple-yet-effective Retrieval Augmented Generation pipeline built on top of LlamaCloud Index and OpenAI
 - 🎨 **Beautiful CLI**: Styled console interface with colors and ASCII art
 - ⚡ **Fast Development**: Hot reload support with watch mode
 - 🛠️ **TypeScript**: Full TypeScript support with strict type checking
@@ -40,8 +40,8 @@ A TypeScript demo application showcasing the power of **LlamaCloud Index** - a f
 1. Clone the repository:
 
 ```bash
-git clone <repository-url>
-cd llamaparse-demo
+git clone https://github.com/run-llama/llama_cloud_services
+cd lama_cloud_services/examples-ts/index/
 ```
 
 2. Install dependencies:
@@ -120,12 +120,12 @@ pnpm run lint
 
 ## License
 
-MIT License - see the [LICENSE](../../../LICENSE) file for details.
+MIT License - see the [LICENSE](../../LICENSE) file for details.
 
 ## Contributing
 
 1. Fork the repository
 2. Create a feature branch
 3. Make your changes
-4. Run `pnpm format` and `pnpm lint`
+4. Run `pnpm run format` and `pnpm run lint`
 5. Submit a pull request

examples-ts/index/package.json

@@ -42,7 +42,7 @@
     "consola": "^3.4.2",
     "dotenv": "^17.2.1",
     "figlet": "^1.8.2",
-    "llama-cloud-services": "link:../../../ts/llama_cloud_services",
+    "llama-cloud-services": "link:../../ts/llama_cloud_services",
     "picocolors": "^1.1.1"
   }
 }

examples-ts/parse/README.md

@@ -40,8 +40,8 @@ A TypeScript demo application showcasing the power of **LlamaParse** - an intell
 1. Clone the repository:
 
 ```bash
-git clone <repository-url>
-cd llamaparse-demo
+git clone https://github.com/run-llama/llama_cloud_services
+cd lama_cloud_services/examples-ts/parse/
 ```
 
 2. Install dependencies:
@@ -113,12 +113,12 @@ pnpm run lint
 
 ## License
 
-MIT License - see the [LICENSE](../../../LICENSE) file for details.
+MIT License - see the [LICENSE](../../LICENSE) file for details.
 
 ## Contributing
 
 1. Fork the repository
 2. Create a feature branch
 3. Make your changes
-4. Run `pnpm format` and `pnpm lint`
+4. Run `pnpm run format` and `pnpm run lint`
 5. Submit a pull request

examples-ts/parse/package.json

@@ -41,7 +41,7 @@
     "ai": "^4.3.19",
     "consola": "^3.4.2",
     "figlet": "^1.8.2",
-    "llama-cloud-services": "link:../../../ts/llama_cloud_services",
+    "llama-cloud-services": "link:../../ts/llama_cloud_services",
     "picocolors": "^1.1.1"
   }
 }

examples-ts/parse/src/logger.ts

@@ -0,0 +1,8 @@
+import { createConsola } from "consola";
+import type { ConsolaInstance } from "consola";
+
+export const logger: ConsolaInstance = createConsola({
+  formatOptions: {
+    date: false,
+  },
+});

examples/README.md

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