arcade-dropbox 0.1.4__tar.gz

arcade_dropbox-0.1.4/.gitignore

@@ -0,0 +1,175 @@
+.DS_Store
+credentials.yaml
+docker/credentials.yaml
+
+*.lock
+
+# example data
+examples/data
+scratch
+
+
+docs/source
+
+# From https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

arcade_dropbox-0.1.4/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+files: ^.*/dropbox/.*
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: "v4.4.0"
+    hooks:
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.7
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

arcade_dropbox-0.1.4/.ruff.toml

@@ -0,0 +1,46 @@
+target-version = "py39"
+line-length = 100
+fix = true
+
+[lint]
+select = [
+    # flake8-2020
+    "YTT",
+    # flake8-bandit
+    "S",
+    # flake8-bugbear
+    "B",
+    # flake8-builtins
+    "A",
+    # flake8-comprehensions
+    "C4",
+    # flake8-debugger
+    "T10",
+    # flake8-simplify
+    "SIM",
+    # isort
+    "I",
+    # mccabe
+    "C90",
+    # pycodestyle
+    "E", "W",
+    # pyflakes
+    "F",
+    # pygrep-hooks
+    "PGH",
+    # pyupgrade
+    "UP",
+    # ruff
+    "RUF",
+    # tryceratops
+    "TRY",
+]
+
+[lint.per-file-ignores]
+"*" = ["TRY003", "B904"]
+"**/tests/*" = ["S101", "E501"]
+"**/evals/*" = ["S101", "E501"]
+
+[format]
+preview = true
+skip-magic-trailing-comma = false

arcade_dropbox-0.1.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Arcade
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

arcade_dropbox-0.1.4/Makefile

@@ -0,0 +1,55 @@
+.PHONY: help
+
+help:
+	@echo "🛠️ github Commands:\n"
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
+
+.PHONY: install
+install: ## Install the uv environment and install all packages with dependencies
+	@echo "🚀 Creating virtual environment and installing all packages using uv"
+	@uv sync --active --all-extras --no-sources
+	@if [ -f .pre-commit-config.yaml ]; then uv run --no-sources pre-commit install; fi
+	@echo "✅ All packages and dependencies installed via uv"
+
+.PHONY: install-local
+install-local: ## Install the uv environment and install all packages with dependencies with local Arcade sources
+	@echo "🚀 Creating virtual environment and installing all packages using uv"
+	@uv sync --active --all-extras
+	@if [ -f .pre-commit-config.yaml ]; then uv run pre-commit install; fi
+	@echo "✅ All packages and dependencies installed via uv"
+
+.PHONY: build
+build: clean-build ## Build wheel file using poetry
+	@echo "🚀 Creating wheel file"
+	uv build
+
+.PHONY: clean-build
+clean-build: ## clean build artifacts
+	@echo "🗑️ Cleaning dist directory"
+	rm -rf dist
+
+.PHONY: test
+test: ## Test the code with pytest
+	@echo "🚀 Testing code: Running pytest"
+	@uv run --no-sources pytest -W ignore -v --cov --cov-config=pyproject.toml --cov-report=xml
+
+.PHONY: coverage
+coverage: ## Generate coverage report
+	@echo "coverage report"
+	@uv run --no-sources coverage report
+	@echo "Generating coverage report"
+	@uv run --no-sources coverage html
+
+.PHONY: bump-version
+bump-version: ## Bump the version in the pyproject.toml file by a patch version
+	@echo "🚀 Bumping version in pyproject.toml"
+	uv version --no-sources --bump patch
+
+.PHONY: check
+check: ## Run code quality tools.
+	@if [ -f .pre-commit-config.yaml ]; then\
+		echo "🚀 Linting code: Running pre-commit";\
+		uv run --no-sources pre-commit run -a;\
+	fi
+	@echo "🚀 Static type checking: Running mypy"
+	@uv run --no-sources mypy --config-file=pyproject.toml

arcade_dropbox-0.1.4/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: arcade_dropbox
+Version: 0.1.4
+Summary: Arcade tools designed for LLMs to interact with Dropbox
+Author-email: Arcade <dev@arcade.dev>
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: arcade-tdk<3.0.0,>=2.0.0
+Requires-Dist: httpx<1.0.0,>=0.27.2
+Provides-Extra: dev
+Requires-Dist: arcade-ai[evals]<3.0.0,>=2.0.0; extra == 'dev'
+Requires-Dist: arcade-serve<3.0.0,>=2.0.0; extra == 'dev'
+Requires-Dist: mypy<1.6.0,>=1.5.1; extra == 'dev'
+Requires-Dist: pre-commit<3.5.0,>=3.4.0; extra == 'dev'
+Requires-Dist: pytest-asyncio<0.25.0,>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov<4.1.0,>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-mock<3.12.0,>=3.11.1; extra == 'dev'
+Requires-Dist: pytest<8.4.0,>=8.3.0; extra == 'dev'
+Requires-Dist: ruff<0.8.0,>=0.7.4; extra == 'dev'
+Requires-Dist: tox<4.12.0,>=4.11.1; extra == 'dev'

arcade_dropbox-0.1.4/arcade_dropbox/constants.py

@@ -0,0 +1,34 @@
+from enum import Enum
+
+
+class EndpointType(Enum):
+    API = "api"
+    CONTENT = "content"
+
+
+class Endpoint(Enum):
+    LIST_FOLDER = "/files/list_folder"
+    SEARCH_FILES = "/files/search"
+    DOWNLOAD_FILE = "/files/download"
+
+
+class ItemCategory(Enum):
+    IMAGE = "image"
+    DOCUMENT = "document"
+    PDF = "pdf"
+    SPREADSHEET = "spreadsheet"
+    PRESENTATION = "presentation"
+    AUDIO = "audio"
+    VIDEO = "video"
+    FOLDER = "folder"
+    PAPER = "paper"
+
+
+API_BASE_URL = "https://{endpoint_type}.dropboxapi.com"
+API_VERSION = "2"
+ENDPOINT_URL_MAP = {
+    Endpoint.LIST_FOLDER: (EndpointType.API, "files/list_folder"),
+    Endpoint.SEARCH_FILES: (EndpointType.API, "files/search_v2"),
+    Endpoint.DOWNLOAD_FILE: (EndpointType.CONTENT, "files/download"),
+}
+MAX_RESPONSE_BODY_SIZE = 10 * 1024 * 1024  # 10 MiB

arcade_dropbox-0.1.4/arcade_dropbox/critics.py

@@ -0,0 +1,34 @@
+from typing import Any
+
+from arcade_evals import BinaryCritic
+
+
+class DropboxPathCritic(BinaryCritic):
+    def evaluate(self, expected: Any, actual: Any) -> dict[str, float | bool]:
+        """
+        Ignores leading slash in the actual value when comparing to the expected value.
+
+        Note: sometimes the LLM won't start the path with a slash, so this critic ignores it when
+        comparing. Dropbox tools will add the slash, when needed, so no worries about API errors.
+
+        Args:
+            expected: The expected value.
+            actual: The actual value to compare, cast to the type of expected.
+
+        Returns:
+            dict: A dictionary containing the match status and score.
+        """
+        try:
+            actual_casted = self.cast_actual(expected, actual)
+        # TODO log or something better here
+        except TypeError:
+            actual_casted = actual
+
+        if isinstance(expected, str):
+            expected = expected.lstrip("/")
+
+        if isinstance(actual_casted, str):
+            actual_casted = actual_casted.lstrip("/")
+
+        match = expected == actual_casted
+        return {"match": match, "score": self.weight if match else 0.0}

arcade_dropbox-0.1.4/arcade_dropbox/exceptions.py

@@ -0,0 +1,18 @@
+from typing import Optional
+
+
+class DropboxApiError(Exception):
+    def __init__(
+        self,
+        status_code: int,
+        error_summary: str,
+        user_message: Optional[str],
+    ):
+        if "path/not_found" in error_summary:
+            self.message = "The specified path was not found by Dropbox"
+        elif "unsupported_file" in error_summary:
+            self.message = "The specified file is not supported for the requested operation"
+        else:
+            self.message = user_message or error_summary
+
+        self.status_code = status_code

arcade_dropbox-0.1.4/arcade_dropbox/tools/browse.py

@@ -0,0 +1,138 @@
+from typing import Annotated, Optional
+
+from arcade_tdk import ToolContext, tool
+from arcade_tdk.auth import Dropbox
+from arcade_tdk.errors import ToolExecutionError
+
+from arcade_dropbox.constants import Endpoint, ItemCategory
+from arcade_dropbox.exceptions import DropboxApiError
+from arcade_dropbox.utils import (
+    build_dropbox_json,
+    clean_dropbox_entries,
+    parse_dropbox_path,
+    send_dropbox_request,
+)
+
+
+@tool(
+    requires_auth=Dropbox(
+        scopes=["files.metadata.read"],
+    )
+)
+async def list_items_in_folder(
+    context: ToolContext,
+    folder_path: Annotated[
+        str,
+        "The path to the folder to list the contents of. E.g. '/AcmeInc/Reports'. "
+        "Defaults to an empty string (list items in the Dropbox root folder).",
+    ] = "",
+    limit: Annotated[
+        int,
+        "The maximum number of items to return. Defaults to 100. Maximum allowed is 2000.",
+    ] = 100,
+    cursor: Annotated[
+        Optional[str],
+        "The cursor token for the next page of results. "
+        "Defaults to None (returns the first page of results).",
+    ] = None,
+) -> Annotated[
+    dict, "Dictionary containing the list of files and folders in the specified folder path"
+]:
+    """Provides a dictionary containing the list of items in the specified folder path.
+
+    Note 1: when paginating, it is not necessary to provide any other argument besides the cursor.
+    Note 2: when paginating, any given item (file or folder) may be returned in multiple pages.
+    """
+    limit = min(limit, 2000)
+
+    try:
+        result = await send_dropbox_request(
+            context.get_auth_token_or_empty(),
+            endpoint=Endpoint.LIST_FOLDER,
+            path=parse_dropbox_path(folder_path),
+            limit=limit,
+            cursor=cursor,
+        )
+    except DropboxApiError as api_error:
+        return {"error": api_error.message}
+
+    return {
+        "items": clean_dropbox_entries(result["entries"]),
+        "cursor": result.get("cursor"),
+        "has_more": result.get("has_more", False),
+    }
+
+
+@tool(
+    requires_auth=Dropbox(
+        scopes=["files.metadata.read"],
+    )
+)
+async def search_files_and_folders(
+    context: ToolContext,
+    keywords: Annotated[
+        str,
+        "The keywords to search for. E.g. 'quarterly report'. "
+        "Maximum length allowed by the Dropbox API is 1000 characters. ",
+    ],
+    search_in_folder_path: Annotated[
+        Optional[str],
+        "Restricts the search to the specified folder path. E.g. '/AcmeInc/Reports'. "
+        "Defaults to None (search in the entire Dropbox).",
+    ] = None,
+    filter_by_category: Annotated[
+        Optional[list[ItemCategory]],
+        "Restricts the search to the specified category(ies) of items. "
+        "Provide None, one or multiple, if needed. Defaults to None (returns all categories).",
+    ] = None,
+    limit: Annotated[
+        int,
+        "The maximum number of items to return. Defaults to 100. Maximum allowed is 1000.",
+    ] = 100,
+    cursor: Annotated[
+        Optional[str],
+        "The cursor token for the next page of results. Defaults to None (first page of results).",
+    ] = None,
+) -> Annotated[dict, "List of items in the specified folder path matching the search criteria"]:
+    """Returns a list of items in the specified folder path matching the search criteria.
+
+    Note 1: the Dropbox API will return up to 10,000 (ten thousand) items cumulatively across
+    multiple pagination requests using the cursor token.
+    Note 2: when paginating, it is not necessary to provide any other argument besides the cursor.
+    Note 3: when paginating, any given item (file or folder) may be returned in multiple pages.
+    """
+    if len(keywords) > 1000:
+        raise ToolExecutionError(
+            "The keywords argument must be a string with up to 1000 characters."
+        )
+
+    limit = min(limit, 1000)
+
+    filter_by_category = filter_by_category or []
+
+    options = build_dropbox_json(
+        file_status="active",
+        filename_only=False,
+        path=parse_dropbox_path(search_in_folder_path),
+        max_results=limit,
+        file_categories=[category.value for category in filter_by_category],
+    )
+
+    try:
+        result = await send_dropbox_request(
+            context.get_auth_token_or_empty(),
+            endpoint=Endpoint.SEARCH_FILES,
+            query=keywords,
+            options=options,
+            cursor=cursor,
+        )
+    except DropboxApiError as api_error:
+        return {"error": api_error.message}
+
+    return {
+        "items": clean_dropbox_entries([
+            match["metadata"]["metadata"] for match in result["matches"]
+        ]),
+        "cursor": result.get("cursor"),
+        "has_more": result.get("has_more", False),
+    }

arcade_dropbox-0.1.4/arcade_dropbox/tools/files.py

@@ -0,0 +1,47 @@
+from typing import Annotated, Optional
+
+from arcade_tdk import ToolContext, tool
+from arcade_tdk.auth import Dropbox
+from arcade_tdk.errors import ToolExecutionError
+
+from arcade_dropbox.constants import Endpoint
+from arcade_dropbox.exceptions import DropboxApiError
+from arcade_dropbox.utils import parse_dropbox_path, send_dropbox_request
+
+
+@tool(
+    requires_auth=Dropbox(
+        scopes=["files.content.read"],
+    )
+)
+async def download_file(
+    context: ToolContext,
+    file_path: Annotated[
+        Optional[str],
+        "The path of the file to download. E.g. '/AcmeInc/Reports/Q1_2025.txt'. Defaults to None.",
+    ] = None,
+    file_id: Annotated[
+        Optional[str],
+        "The ID of the file to download. E.g. 'id:a4ayc_80_OEAAAAAAAAAYa'. Defaults to None.",
+    ] = None,
+) -> Annotated[dict, "Contents of the specified file"]:
+    """Downloads the specified file.
+
+    Note: either one of `file_path` or `file_id` must be provided.
+    """
+    if not file_path and not file_id:
+        raise ToolExecutionError("Either `file_path` or `file_id` must be provided.")
+
+    if file_path and file_id:
+        raise ToolExecutionError("Only one of `file_path` or `file_id` can be provided.")
+
+    try:
+        result = await send_dropbox_request(
+            context.get_auth_token_or_empty(),
+            endpoint=Endpoint.DOWNLOAD_FILE,
+            path=parse_dropbox_path(file_path) or file_id,
+        )
+    except DropboxApiError as api_error:
+        return {"error": api_error.message}
+
+    return {"file": result}