Metadata-Version: 2.4
Name: imagen-sdk
Version: 0.0.2
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.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: Topic :: Multimedia :: Graphics
Requires-Python: >=3.9
Requires-Dist: cryptography>=42.0.0
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.

## 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 --upgrade pip build twine pytest cryptography
pip install -e .
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

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.
