Bucket Helper

🇫🇷 · 🇬🇧

Bucket Helper는 인공지능 구축을 위해 개발된 AI Helpers라는 라이브러리 모음에 속하며, 각각은 자체적인 녹색 CI 게이트(pytest와 ruff, 둘 다 차단 방식)와 시맨틱 버전 관리 릴리스를 통해 PyPI에 게시됩니다.

AWS S3 및 모든 S3 호환 객체 스토리지(MinIO, Backblaze B2 S3 API, DigitalOcean Spaces, Cloudflare R2, Wasabi 등)를 위한 유틸리티 함수입니다. boto3 기반으로 구축되었습니다. sftp-helper와 동일한 구조를 가집니다: credentials() 로더, 일반적인 CRUD(upload / download / delete / exists / list_prefix), 그리고 스테이지-앤-공유(stage-and-share) 워크플로우를 위한 remote_tempfile 컨텍스트 매니저.

객체 스토리지는 파일을 하드 드라이브의 중첩된 폴더 트리 대신 평평하고 주소 지정 가능한 블롭(blob)으로 유지하며, 버킷과 키(예: my-bucket/folder/file.txt)로 구성됩니다. 미리 생성할 것이 없고, 한 곳에 쌓을 수 있는 파일 수에 제한이 없으며, 모든 객체는 URL에서 직접 접근할 수 있습니다. Amazon Web Services가 이 개념의 첫 번째 대중적인 버전인 S3(Simple Storage Service)를 구축했고, 그 와이어 프로토콜은 사실상의 표준이 되었습니다: MinIO, Backblaze B2, DigitalOcean Spaces, Cloudflare R2, Wasabi 모두 동일한 S3 API를 사용하므로 bucket-helper는 엔드포인트 URL만 변경하면 이들 모두에서 수정 없이 실행됩니다.

🌍 AI Helpers

약속(The Promise)

원격 우선 설계(Remote by design). bucket-helper는 선택한 객체 스토리지(AWS 또는 가리키는 모든 S3 호환 엔드포인트, 자체 네트워크의 MinIO 인스턴스 포함)로 데이터를 이동하기 위해 존재합니다. 의도적으로 로컬 우선(local-first)이 아니며 GUI도 제공하지 않습니다. S3 대신 SFTP로 접근하는 원격 저장소가 필요하면 sftp-helper를 사용하고, URL에서 미디어를 다운로드하려면 youtube-helper를 사용하세요.

그 원격 접근성은 "전투 테스트를 거친(battle-tested)"이라는 말이 슬로건이 아니라 검증 가능한 의미를 가져야 하는 부분이기도 합니다. 모든 푸시는 차단형 CI 게이트를 실행합니다: 테스트 스위트는 moto로 모킹된 백엔드에 대해 S3 클라이언트를 실행한 후 ruff가 스타일을 검사합니다. 빨간 실행에서는 main으로 병합되지 않습니다. 이 패키지는 PyPI에서 v0.2.2부터 현재 v1.1.2까지 9개의 시맨틱 버전 관리 릴리스를 통해 배포되었습니다(태그 기록은 git tag로 확인 가능). AI Helpers 스위트 전체가 로깅과 파일 처리를 위해 공유하는 작은 기반 패키지인 os-helper에 의존합니다. 여기서 그 계층을 재발명하지 않습니다.

Related MCP server: MinIO MCP Server

문서(Documentation)

💻 문서

🗺️ 랜드스케이프

📋 예제

🎯 트리거

기능(Features)

• CRUD: AWS S3 또는 모든 S3 호환 엔드포인트에 대한 upload, download, delete, exists, list_prefix.

• 모든 S3 호환 제공업체에서 작동: MinIO, Backblaze B2 S3 API, DigitalOcean Spaces, Cloudflare R2, Wasabi 등. endpoint_url 자격 증명을 해당 제공업체로 지정하기만 하면 되며, 제공업체별 코드 변경이 필요 없습니다.

• 자격 증명 로더(credentials): JSON / YAML / 환경 변수 / .env를 해당 폴백 순서로 해석합니다.

• remote_tempfile 컨텍스트 매니저: 스테이지-앤-공유 워크플로우용. 업로드 후 객체를 반환하고, 블록 종료 시 자동 삭제되며 수동 정리가 필요 없습니다.

• 세 가지 표면, 하나의 동작: Python 라이브러리, argparse CLI, click CLI 트윈([cli] 엑스트라), FastAPI HTTP 표면([api] 엑스트라). 다중 표면 섹션 참조.

• Docker 이미지: HTTP 서버를 실행 가능한 상태로 제공합니다.

설치(Installation)

사전 요구 사항: Python 3.10–3.13 및 git, 크로스 플랫폼:

• 🍎 macOS (Homebrew): brew install python git

• 🐧 Ubuntu/Debian: sudo apt update && sudo apt install -y python3 python3-pip git

• 🪟 Windows (PowerShell): winget install Python.Python.3.12 Git.Git

Python 환경 사용을 권장합니다. 환경 설정에 익숙하지 않다면 이 링크를 확인하세요: 🥸 기술 팁.

PyPI에서 설치(권장)

# Core library (credentials loader + CRUD + remote_tempfile)
pip install bucket-helper

# Optional surfaces
pip install "bucket-helper[cli]"       # click-based CLI twin
pip install "bucket-helper[api]"       # FastAPI HTTP surface

소스에서 설치(PyPI 없음)

git clone https://github.com/warith-harchaoui/bucket-helper.git
cd bucket-helper
pip install -e .

# Optional surfaces
pip install -e ".[cli]"
pip install -e ".[api]"

argparse CLI는 항상 사용할 수 있습니다. [cli] 엑스트라는 click 트윈을 추가합니다.

구성(Configuration)

바로 작성할 수 있는 템플릿이 settings.yaml.example에 커밋되어 있습니다. 이를 settings.yaml로 복사하고 그 자리에서 편집하세요: settings.yaml은 gitignore 처리되어 있으므로 실수로 비밀을 커밋할 수 없습니다.

cp settings.yaml.example settings.yaml
# then edit settings.yaml with your AWS / MinIO / R2 / B2 credentials

YAML 대신 JSON을 작성하거나 .env를 사용하거나 환경 변수를 설정할 수도 있습니다. bucket-helper는 os_helper.get_config를 통해 해당 순서로 폴백합니다. 필수 키:

{
  "s3_access_key": "AKIA...",
  "s3_secret_key": "...",
  "s3_bucket":     "my-bucket",
  "s3_https":      "https://my-bucket.s3.eu-west-3.amazonaws.com"
}

선택적 키:

일반적인 S3 호환 스토리지의 엔드포인트 URL

s3_endpoint_url을 다음으로 설정하세요:

사용법(Usage)

전체 레시피 카탈로그(업로드 / 다운로드 / 목록 조회, MinIO / R2 / B2 / Spaces / Wasabi와 같은 S3 호환 엔드포인트, 자동 정리 기능이 있는 임시 원격 키, sftp-helper와의 미러링)는 📋 EXAMPLES.md를 참조하세요.

import bucket_helper as bh

# Load creds: JSON / YAML / env / .env (auto-fallback in that order)
cred = bh.credentials("path/to/settings.yaml")

# Upload a local file
uri = bh.upload("local.txt", cred, "folder/uploaded.txt")
# uri == "s3://my-bucket/folder/uploaded.txt"

assert bh.exists(uri, cred)

# Download
bh.download(uri, "downloaded.txt", cred)

# List
for key in bh.list_prefix("folder/", cred):
    print(key)

# Delete
bh.delete(uri, cred)

MinIO 예제

cred = {
    "s3_access_key":      "minioadmin",
    "s3_secret_key":      "minioadmin",
    "s3_bucket":          "uploads",
    "s3_https":           "http://minio.example.com:9000/uploads",
    "s3_endpoint_url":    "http://minio.example.com:9000",
    "s3_use_path_style":  "true",
    "s3_region":          "us-east-1",  # MinIO accepts any region string
}

bh.make_bucket("uploads", cred)
bh.upload("file.bin", cred, "file.bin")

remote_tempfile을 사용한 스테이지-앤-공유

생성된 파일을 고유한 임의 키에 넣고 공개 URL을 다운스트림 워커 / 웹훅에 전달하면, 객체는 블록 종료 시 삭제됩니다(본문에서 예외가 발생해도):

import bucket_helper as bh
import requests

cred = bh.credentials("path/to/settings.yaml")

with bh.remote_tempfile(cred, ext="json", prefix="runs") as (s3_addr, public_url):
    bh.upload("payload.json", cred, s3_addr, content_type="application/json")
    # Hand the URL to something that fetches it once.
    requests.post("https://hook.example.com/process", json={"input_url": public_url}).raise_for_status()
# Object is gone here, no manual cleanup.

다중 표면 노출(Multi-surface exposure)

라이브러리의 모든 공개 함수는 다음으로도 노출됩니다:

• argparse CLI: bucket-helper <subcommand> (기본 설치).

• click CLI: bucket-helper-click <subcommand> ([cli] 엑스트라 설치).

• FastAPI HTTP: uvicorn bucket_helper.api:app --host 0.0.0.0 --port 8000 ([api] 엑스트라 설치).

• MCP: bucket-helper-mcp는 동일한 HTTP 표면을 MCP 도구로 노출하여 MCP 인식 에이전트 호스트에서 사용할 수 있게 합니다([mcp] 엑스트라 설치).

두 CLI 모두 동일한 하위 명령 이름과 플래그를 공유하므로 원하는 것을 선택하세요.

도구 키트를 트리거하는 것에 대한 전체 카탈로그(자연어 표현, 명령, 함수, 주소 신호, 명시적 SKIP 규칙)는 TRIGGERS.md에 있습니다.

CLI 예제

# argparse CLI (always available)
bucket-helper upload      --config settings.yaml --input local.txt --key folder/uploaded.txt
bucket-helper exists      --config settings.yaml --key folder/uploaded.txt
bucket-helper download    --config settings.yaml --key folder/uploaded.txt --output back.txt
bucket-helper list        --config settings.yaml --prefix folder/
bucket-helper delete      --config settings.yaml --key folder/uploaded.txt
bucket-helper make-bucket --config settings.yaml --bucket new-bucket
bucket-helper tempfile    --config settings.yaml --ext json --prefix runs
bucket-helper strip-path  --config settings.yaml --address s3://my-bucket/path/to/obj

# click CLI: same verbs, same flags
bucket-helper-click upload --config settings.yaml --input local.txt --key folder/uploaded.txt

HTTP 서버

# Serve HTTP (default credentials picked up from BUCKET_HELPER_CONFIG)
BUCKET_HELPER_CONFIG=$PWD/settings.yaml uvicorn bucket_helper.api:app --host 0.0.0.0 --port 8000
# → Swagger UI at http://localhost:8000/docs

요청별 자격 증명은 멀티파트 폼 필드(s3_access_key / s3_secret_key / s3_bucket / s3_https / …)로도 보낼 수 있습니다.

Docker

docker build -t bucket-helper .
docker run --rm -p 8000:8000 \
  -e BUCKET_HELPER_CONFIG=/config/settings.yaml \
  -v $PWD/settings.yaml:/config/settings.yaml:ro \
  bucket-helper

참조: TRIGGERS.md(도구 키트를 호출하는 것) 및 GUI.md(시각적 제품 설계 계획; GUI는 제공되지 않으며, bucket-helper는 원격 객체 스토리지 파이프라인입니다).

작성자(Author)

• Warith HARCHAOUI

감사의 말(Acknowledgements)

유익한 논의를 해주신 Mohamed Chelali와 Bachir Zerroug에게 특별히 감사드립니다.

라이선스(License)

이 프로젝트는 BSD-3-Clause 라이선스로 배포됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.