# Blocks SDK

Write custom AI-enabled codebase automations in Python. Leverage a full codebase-aware API. Automatically trigger automations from Github, Slack, and other providers.

> We're currently in private alpha, we recommend consistently updating your SDK to the latest version to get the latest features and fixes.

## Getting Started

### 1. Install SDK

```bash
pip install blocks-sdk
```

### 2. Create a new Blocks project

```bash
mkdir -p .blocks/myautomation
cd .blocks/myautomation
```

### 3. Create a new automation

```python
# automation.py
from blocks import task, on

@task(name="my_automation")
@on("github.pull_request", repos=["MyOrg/MyRepo"])
def my_automation(event):
    print(event)
```

### 5. Upload your automation

```bash
blocks init --api-key <your-api-key>
blocks push automation.py
```

## Repository Provider Configuration

Set `REPO_PROVIDER` when using `blocks.repo` APIs.

### GitHub

- `REPO_PROVIDER=github`
- `GITHUB_TOKEN=<token>`
- `REPO_URL=https://github.com/<owner>/<repo>.git` (or legacy `GITHUB_REPOSITORY_PATH=<owner>/<repo>`)

### GitLab

- `REPO_PROVIDER=gitlab`
- `GITLAB_TOKEN=<token>`
- `REPO_URL=https://gitlab.com/<owner>/<repo>.git`

### Bitbucket Cloud

- `REPO_PROVIDER=bitbucket`
- `BITBUCKET_TOKEN=<token>`
- `REPO_URL=https://bitbucket.org/<workspace>/<repo_slug>.git`
- Optional for git clone auth flows: `BITBUCKET_USERNAME=<username>`

Bitbucket pull request support includes creating/updating PRs, general and inline comments, replies, approvals, and request-changes reviews.
