visgate-sdk v0.2.2 — production-ready Python client for Visgate API

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: uzunenes

.cursorrules

@@ -0,0 +1,28 @@
+You are working on visgate-python, the open-source Python SDK for the Visgate API.
+
+Stack: Python 3.9+, httpx, pytest, ruff. Build: setuptools via pyproject.toml.
+
+Architecture:
+- src/visgate_sdk/client.py — Client (sync) and AsyncClient (async), httpx-based with retry logic
+- src/visgate_sdk/resources/ — one module per API resource (generate, images, videos, models, usage, providers)
+- src/visgate_sdk/exceptions.py — typed exception hierarchy (VisgateError base)
+- src/visgate_sdk/_utils.py — internal helpers (datetime parsing)
+- tests/test_client.py — unit tests (pytest + pytest-asyncio)
+- examples/ — numbered scripts tested against the live API
+
+Key design decisions:
+- api_key auto-discovers from VISGATE_API_KEY env var (like openai/stripe SDKs)
+- Version is single-sourced from pyproject.toml via importlib.metadata with fallback
+- _handle_response is a shared module-level function (not duplicated per client)
+- generate() is a proper method on Client, not a callable resource
+- max_retries with exponential backoff for transient errors (429, 5xx)
+- All BYOK keys (fal, replicate, runway) are constructor parameters
+- All result types have __repr__ for readable debugging
+- py.typed marker for PEP 561 compliance
+
+Rules:
+- All modules use `from __future__ import annotations` for Python 3.9 compat
+- All user-facing text must be English only
+- Every public export must be in __init__.py __all__
+- Run `ruff check src/ tests/` and `pytest tests/ -v` before any commit
+- No unnecessary dependencies; httpx is the only runtime dep

.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src/ tests/
+
+      - name: Test
+        run: pytest tests/ -v
+
+      - name: Smoke (offline)
+        run: python examples/00_smoke_sdk.py

.github/workflows/publish-pypi.yml

@@ -0,0 +1,37 @@
+# Publish visgate-sdk to PyPI on GitHub Release.
+#
+# Authentication (in order of preference):
+#   1. PyPI trusted publisher (recommended, no secrets needed)
+#      Setup: https://docs.pypi.org/trusted-publishers/adding-a-publisher/
+#   2. PYPI_API_TOKEN secret (fallback)
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+
+# Test / tools
+.pytest_cache/
+.coverage
+htmlcov/
+.ruff_cache/
+
+# OS
+.DS_Store
+
+# Env
+.env
+.env.*

CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+## [0.2.2] - 2026-02-11
+
+### Added
+
+- Automatic API key discovery from `VISGATE_API_KEY` environment variable.
+- `max_retries` parameter with exponential backoff for transient errors (429, 5xx).
+- `replicate_key` and `runway_key` constructor parameters for BYOK mode.
+- `client.health()` method for API health checks.
+- `client.usage.logs()` and `client.usage.dashboard()` methods.
+- `ValidationError` for 422 responses with `.field` attribute.
+- `TimeoutError` and `ConnectionError` for network failures.
+- `py.typed` marker (PEP 561) for downstream type checking.
+- `CONTRIBUTING.md` for contributor guidelines.
+- CI workflow testing Python 3.9, 3.11, and 3.12.
+- 54 unit tests covering client, errors, data classes, and async.
+
+### Changed
+
+- `api_key` is now optional -- reads from environment if not provided.
+- `generate()` is a proper method on the client, not a callable resource.
+- Response handling is shared between sync and async clients (fixes async `ProviderError` bug).
+- All datetime fields use consistent parsing via `_utils.parse_datetime`.
+- All result types have `__repr__` for readable debugging output.
+- User-Agent changed to `visgate-sdk-python/{version}`.
+- `__version__` falls back gracefully when package is not installed.
+- Usage resource uses proper `params=` instead of manual query string.
+- PyPI publish uses trusted publisher (no token required).
+
+### Removed
+
+- `VisGate` alias (use `Client` directly).
+- Redundant `sdk-test-project/` and `istanbul_prompt_to_image.py` examples.
+- Stale `RELEASE.md`, `RELEASE_CHECKLIST.md`, `docs/SDK-WORKFLOW.md`.
+
+## [0.2.1] - 2026-02-10
+
+### Changed
+
+- Initial standalone release on PyPI.
+
+## [0.2.0] - 2026-02-07
+
+### Added
+
+- BYOK proxy layer, unified `/v1/generate` endpoint, megapixel pricing.

CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing to visgate-sdk
+
+Thanks for your interest in contributing.
+
+## Setup
+
+```bash
+git clone https://github.com/visgate-ai/visgate-python.git
+cd visgate-python
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Development
+
+```bash
+# Lint
+ruff check src/ tests/
+
+# Unit tests
+pytest tests/ -v
+
+# Smoke test (no network)
+python examples/00_smoke_sdk.py
+
+# Live API smoke test (no auth needed)
+python examples/01_live_api_smoke.py
+```
+
+## Pull Requests
+
+1. Fork the repo and create a feature branch.
+2. Make your changes. Add tests for new functionality.
+3. Ensure `ruff check src/ tests/` and `pytest tests/ -v` pass.
+4. Open a PR with a clear description of what changed and why.
+
+## Code Style
+
+- Python 3.9+ compatible.
+- Use `from __future__ import annotations` in all modules.
+- Run `ruff check` before committing.
+- Keep the public API surface minimal.
+- Every public export must be in `__init__.py` `__all__`.
+
+## Releasing
+
+Version is single-sourced from `pyproject.toml`. To release:
+
+1. Bump version in `pyproject.toml`.
+2. Update `CHANGELOG.md`.
+3. Commit and push to `main`.
+4. Create a GitHub Release with the tag (e.g. `v0.3.0`).
+5. The PyPI publish workflow runs automatically.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Visgate AI
+
+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.