Metadata-Version: 2.4
Name: imagen-sdk
Version: 0.0.3
Summary: A client library for generating images through the flix-imagen API
Project-URL: Homepage, https://bitbucket.org/flixstock-dev/imagen-sdk
Project-URL: Repository, https://bitbucket.org/flixstock-dev/imagen-sdk
Project-URL: Issues, https://bitbucket.org/flixstock-dev/imagen-sdk/issues
Author-email: Flixstock <dev@flixstock.com>
License-Expression: LicenseRef-Flixstock-Proprietary
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.9
Requires-Dist: cryptography>=42.0.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: tox>=4.0; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# Imagen SDK

A proprietary client library for generating images through the [flix-imagen](https://bitbucket.org/flixstock-dev/flix-imagen) API.

**Authorized Flixstock users only.** A signed runtime license file is required before the SDK can be used.

## Python compatibility

- **Supported:** Python 3.9 through 3.14 (CPython and PyPy)
- **Wheel:** one universal `py3-none-any` wheel works across all supported versions
- **Floor:** Python 3.9 (required by the `cryptography` dependency)

Test locally across versions (requires [tox](https://tox.wiki/) and multiple Python installs):

```bash
pip install -e ".[dev]"
tox
```

CI runs the test suite on Python 3.9–3.13 via `bitbucket-pipelines.yml`.

## Installation

```bash
pip install imagen-sdk
```

## Runtime license file

Before creating a client, obtain an RSA-signed license file from Flixstock. The SDK verifies signatures using a **public key bundled in the package**; the private key never ships with the SDK.

The SDK checks for a license in this order:

1. `license_path` argument to `ImagenClient`
2. `IMAGEN_SDK_LICENSE` environment variable
3. `./imagen-sdk.license` or `./license.json` in the working directory
4. `~/.config/imagen-sdk/license.json`

Example license format: see `license.example.json`.

Allowed email domains: `@flixstock.com`, `@imageedit.ai`.

### Key setup (Flixstock admins, one-time)

Generate an RSA key pair. The public key is committed to the repo; the private key stays local.

```bash
pip install cryptography
python scripts/generate_keys.py
```

- Public key: `src/imagen_sdk/keys/license_public.pem` (bundled in the wheel)
- Private key: `keys/license_private.pem` (gitignored — store securely)

### Issue a license (Flixstock admins)

```bash
python scripts/issue_license.py \
  --licensee "Jane Doe" \
  --email "jane.doe@flixstock.com" \
  --output imagen-sdk.license
```

Optional: `--private-key /path/to/license_private.pem` or set `IMAGEN_SDK_PRIVATE_KEY`.

## Usage

```python
from imagen_sdk import ImagenClient, LicenseError

try:
    client = ImagenClient(
        base_url="https://imagen-api.flixstock.com",
        api_key="your-api-key",
        license_path="/path/to/imagen-sdk.license",
    )
except LicenseError as exc:
    print(exc)
```

Or set the environment variable:

```bash
export IMAGEN_SDK_LICENSE=/path/to/imagen-sdk.license
```

```python
from imagen_sdk import ImagenClient

client = ImagenClient(
    base_url="https://imagen-api.flixstock.com",
    api_key="your-api-key",
)
```

## Development

```bash
python -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate     # macOS/Linux

pip install -e ".[dev]"
python scripts/generate_keys.py   # if keys do not exist yet
python scripts/issue_license.py --licensee "Dev User" --email "dev@flixstock.com"
pytest
```

## Publishing to PyPI

### CI/CD (Bitbucket Pipelines)

Releases are published automatically when you push a version tag.

1. Bump `version` in `pyproject.toml` and `__version__` in `src/imagen_sdk/__init__.py`.
2. Commit and push.
3. Create and push a matching tag:

```bash
git tag v0.0.2
git push origin v0.0.2
```

The `v*` tag pipeline runs tests, verifies the tag matches the package version, builds, and uploads to PyPI.

**Manual TestPyPI publish:** Pipelines → Run pipeline → `publish-testpypi`.

#### Bitbucket repository variables

Add these under **Repository settings → Pipelines → Repository variables**:

| Variable | Secured | Value |
|---|---|---|
| `TWINE_USERNAME` | No | `__token__` |
| `TWINE_PASSWORD` | **Yes** | Production PyPI API token (full value, including `pypi-` prefix) |
| `TESTPYPI_TWINE_PASSWORD` | **Yes** | TestPyPI API token (only needed for the `publish-testpypi` custom pipeline) |

Create tokens at:

- Production: [pypi.org/manage/account/#api-tokens](https://pypi.org/manage/account/#api-tokens)
- Test: [test.pypi.org/manage/account/#api-tokens](https://test.pypi.org/manage/account/#api-tokens)

Scope tokens to the `imagen-sdk` project when possible.

### Manual publish

Follow the [Python Packaging User Guide](https://packaging.python.org/en/latest/tutorials/packaging-projects/).

### 1. Install build tools

```bash
pip install --upgrade pip build twine
```

### 2. Bump the version

Update `version` in `pyproject.toml` and `__version__` in `src/imagen_sdk/__init__.py`. PyPI does not allow re-uploading the same version.

### 3. Build distribution archives

```bash
# Windows PowerShell
Remove-Item -Recurse -Force dist, build -ErrorAction SilentlyContinue
python -m build
```

This produces in `dist/`:

- `imagen_sdk-<version>.tar.gz` — source distribution
- `imagen_sdk-<version>-py3-none-any.whl` — wheel

### 4. Test on TestPyPI (recommended)

1. Register at [test.pypi.org](https://test.pypi.org/account/register/) and verify your email.
2. Create an API token at [test.pypi.org/manage/account/#api-tokens](https://test.pypi.org/manage/account/#api-tokens).
3. Upload:

```bash
python -m twine upload --repository testpypi dist/*
```

When prompted:

- **Username**: `__token__`
- **Password**: your API token (including the `pypi-` prefix)

4. Verify install:

```bash
pip install --index-url https://test.pypi.org/simple/ --no-deps imagen-sdk
```

5. Check: `https://test.pypi.org/project/imagen-sdk/`

### 5. Publish to PyPI

1. Register at [pypi.org](https://pypi.org/account/register/) (separate from TestPyPI).
2. Confirm `imagen-sdk` is available on [pypi.org](https://pypi.org/).
3. Create a production API token at [pypi.org/manage/account/#api-tokens](https://pypi.org/manage/account/#api-tokens).
4. Upload:

```bash
python -m twine upload dist/*
```

5. Install from PyPI:

```bash
pip install imagen-sdk
```

### Optional: store credentials in `.pypirc`

```ini
[distutils]
index-servers =
    pypi
    testpypi

[pypi]
username = __token__
password = pypi-...

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi-...
```

Never commit `.pypirc` or API tokens to version control.

## License

Proprietary — see [LICENSE](LICENSE). Unauthorized use, copying, or distribution is prohibited.
