chore: post-cleanup — CHANGELOG 0.2.3, CI lint examples, PyPI tag check, docs/examples/ruff

- CHANGELOG: add [0.2.3] with run_with_sifreler, API.md, examples README gallery, ruff fixes
- CI: ruff check src/ tests/ examples/
- publish-pypi: verify release tag matches pyproject.toml version
- docs/API.md: latest API, run_with_sifreler, low-cost run, skip_gcs_upload, 404/MODEL_NOT_FOUND
- README: remove dead script refs, add run_with_sifreler
- CONTRIBUTING: lint scope + code style
- examples: run_with_sifreler.py, Tee E702 fix in all scripts, 12_veo F541 fix
- examples/README: sample results, provider counts, image gallery, low-cost run
- Remove obsolete examples: _common, capture_all_outputs, create_placeholder_video, fetch_sample_outputs, generate_istanbul_video_veo, make_video_and_gif

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

Author: uzunenes

.github/workflows/ci.yml

@@ -29,7 +29,7 @@ jobs:
         run: pip install -e ".[dev]"
 
       - name: Lint
-        run: ruff check src/ tests/
+        run: ruff check src/ tests/ examples/
 
       - name: Test
         run: pytest tests/ -v

.github/workflows/publish-pypi.yml

@@ -20,6 +20,15 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Verify version matches release tag
+        run: |
+          TAG="${{ github.event.release.tag_name }}"
+          VER=$(grep -m1 '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/')
+          if [ "v${VER}" != "${TAG}" ]; then
+            echo "::error::pyproject.toml version (${VER}) does not match release tag (${TAG}). Bump version to match before publishing."
+            exit 1
+          fi
+
       - name: Set up Python
         uses: actions/setup-python@v5
         with:

.gitignore

@@ -17,6 +17,8 @@ htmlcov/
 # OS
 .DS_Store
 
-# Env
+# Env / secrets
 .env
 .env.*
+sifreler
+*sa-key*.json

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.2.3] - 2026-02-13
+
+### Added
+
+- `examples/run_with_sifreler.py` — run examples with env loaded from `sifreler` or `VISGATE_ENV_FILE`.
+- docs/API.md: low-cost run, `skip_gcs_upload`, 404/MODEL_NOT_FOUND, run_with_sifreler.
+- examples/README.md: sample results (live API output), provider counts table, image gallery, low-cost run command.
+
+### Changed
+
+- README.md: removed references to deleted scripts (`capture_all_outputs`, `fetch_sample_outputs`, `make_video_and_gif`); added `run_with_sifreler`.
+- CONTRIBUTING.md: lint scope includes `examples/`; code style (no semicolons, no f-strings without placeholders).
+- All example scripts: `Tee` class write/flush split to multiple lines (ruff E702).
+- examples/12_veo_from_catalog.py: fixed f-string without placeholders (ruff F541).
+
 ## [0.2.2] - 2026-02-11
 
 ### Added

CONTRIBUTING.md

@@ -16,7 +16,7 @@ pip install -e ".[dev]"
 
 ```bash
 # Lint
-ruff check src/ tests/
+ruff check src/ tests/ examples/
 
 # Unit tests
 pytest tests/ -v
@@ -32,16 +32,18 @@ python examples/01_live_api_smoke.py
 
 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.
+3. Ensure `ruff check src/ tests/ examples/` 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.
+- Run `ruff check src/ tests/ examples/` before committing.
 - Keep the public API surface minimal.
 - Every public export must be in `__init__.py` `__all__`.
+- No multiple statements on one line (no semicolons); no f-strings without placeholders.
+- User-facing strings in English only.
 
 ## Releasing
 

README.md

@@ -1,12 +1,16 @@
 # visgate-sdk
 
-Python SDK for the [Visgate API](https://visgateai.com) -- one client for image and video generation across Fal, Replicate, and Runway.
+Python SDK for the [Visgate API](https://visgateai.com) — one client for image and video generation across **Fal**, **Replicate**, and **Runway**.
 
 [![CI](https://github.com/visgate-ai/visgate-python/actions/workflows/ci.yml/badge.svg)](https://github.com/visgate-ai/visgate-python/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/visgate-sdk)](https://pypi.org/project/visgate-sdk/)
 [![Python](https://img.shields.io/pypi/pyversions/visgate-sdk)](https://pypi.org/project/visgate-sdk/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
+## Overview
+
+Visgate is a visual AI gateway: one API, one SDK, three providers. Generate images and videos with Fal, Replicate, or Runway — managed keys or bring your own. Built-in cache, usage tracking, and typed exceptions.
+
 ## Install
 
 ```bash
@@ -26,7 +30,7 @@ print(result.image_url)
 client.close()
 ```
 
-Or with a context manager:
+With a context manager:
 
 ```python
 with Client() as client:
@@ -38,28 +42,29 @@ with Client() as client:
 
 - **One client, three providers.** Fal, Replicate, and Runway behind a single API.
 - **Managed and BYOK modes.** Use Visgate-managed keys or bring your own.
-- **Sync and async.** `Client` for synchronous code, `AsyncClient` for async.
-- **Automatic retries.** Transient errors (429, 5xx) are retried with exponential backoff.
-- **Typed exceptions.** Catch `AuthenticationError`, `RateLimitError`, `ProviderError`, etc.
-- **Full type hints.** PEP 561 compliant with `py.typed` marker.
+- **Sync and async.** `Client` for sync, `AsyncClient` for async.
+- **Async 202 + poll.** `videos.generate(wait=False)` / `images.generate(wait=False)` for long-running jobs; poll with `client.requests.get()`.
+- **Automatic retries.** Transient errors (429, 5xx) with exponential backoff.
+- **Typed exceptions.** `AuthenticationError`, `RateLimitError`, `ProviderError`, etc.
+- **Full type hints.** PEP 561 compliant.
 
 ## Authentication
 
-Set your API key as an environment variable (recommended):
+Set your API key (required for most endpoints):
 
 ```bash
 export VISGATE_API_KEY="vg-..."
 ```
 
-Or pass it directly:
+Or pass directly:
 
 ```python
 client = Client(api_key="vg-...")
 ```
 
 ## BYOK (Bring Your Own Key)
 
-Use your own provider keys while still routing through Visgate:
+Use your own provider keys while routing through Visgate:
 
 ```python
 client = Client(
@@ -95,7 +100,7 @@ result = client.videos.generate(
     prompt="Cinematic drone over Istanbul at golden hour, Bosphorus and minarets",
     duration_seconds=5.0,
 )
-print(result.video_url)  # Convert to GIF for previews: examples/make_video_and_gif.py --mp4 path
+print(result.video_url)
 ```
 
 ### Model Discovery
@@ -196,38 +201,35 @@ All API traffic uses HTTPS. Provider API keys (BYOK) are encrypted at rest; othe
 
 ## Examples
 
-A **step-by-step guide** with purpose, command, and proof output for each example is in [examples/README.md](examples/README.md) (textbook-style with all results).
+A step-by-step guide for each example is in [examples/README.md](examples/README.md).
 
 | Script | Description | Auth |
 |--------|-------------|:---:|
-| `00_smoke_sdk.py` | Version and client (no network) | No |
-| `01_live_api_smoke.py` | Health check and model listing | No |
+| `00_smoke_sdk.py` | SDK version and client (no network) | No |
+| `01_live_api_smoke.py` | Health and model listing | No |
 | `00_auth_identity.py` | Auth identity verification | Yes |
 | `01_models_catalog.py` | Model discovery and search | Yes |
 | `02_generate_unified.py` | Unified generation (managed + BYOK) | Yes |
-| `03_images_all_providers.py` | Image generation across providers | Yes |
+| `03_images_all_providers.py` | Image generation (Fal, Replicate, Runway) | Yes |
 | `04_videos_all_providers.py` | Video generation | Yes |
-| `05_usage_history_verify.py` | Usage, logs, and dashboard | Yes |
+| `05_usage_history_verify.py` | Usage, logs, dashboard | Yes |
 | `06_provider_balances.py` | Provider status and balances | Yes |
-| `07_cache_demo.py` | Cache: two identical image requests | Yes |
+| `07_cache_demo.py` | Exact cache (identical requests) | Yes |
 | `08_semantic_cache_demo.py` | Semantic cache (similar prompts) | Yes |
 | `09_provider_keys.py` | Provider keys list and validate | Yes |
-| `10_api_keys.py` | List API keys (GET /api-keys) | Yes |
+| `10_api_keys.py` | List API keys | Yes |
 | `11_billing_readonly.py` | Billing stats, info, pricing | Yes |
+| `12_veo_from_catalog.py` | Veo from catalog → generate → save | Yes |
+| `13_async_generation.py` | Async 202 + poll (video/image) | Yes |
 
 ```bash
-# Run all examples in order
+# Run all examples (requires VISGATE_API_KEY; generation steps incur cost)
 VISGATE_API_KEY=vg-... python examples/run_all_capabilities.py
 
-# Capture all text outputs to sample_outputs/out_*.txt
-cd examples && python capture_all_outputs.py
-```
+# Run with a credentials file (e.g. sifreler in repo root)
+python examples/run_with_sifreler.py
 
-Sample outputs use an **Istanbul theme** (Bosphorus, minarets, golden hour). They are under [`examples/sample_outputs/`](examples/sample_outputs/) (images, `istanbul.mp4`, `istanbul.gif`, and text proofs). Regenerate:
-
-```bash
-cd examples && python fetch_sample_outputs.py   # images + video
-cd examples && python make_video_and_gif.py    # video + GIF
+# Low-cost run (no generation): see examples/README.md
 ```
 
 ## Contributing

docs/API.md

@@ -1,37 +1,34 @@
 # API reference
 
-Short reference. Full OpenAPI spec: your API base URL + `/docs`.
+Short reference for the **visgate-python** SDK. Full OpenAPI spec: **https://visgateai.com/api/v1/docs** (or your base URL + `/docs`).
 
 ## Testing against the live API
 
-Use the **visgate-python** SDK and examples to hit the live API. Sample outputs (images and video) use an **Istanbul theme** for a consistent look.
+Use the SDK and the numbered examples to hit the live API. Sample outputs use an **Istanbul theme** (Bosphorus, Galata Tower, golden hour).
 
 ```bash
 pip install visgate-sdk
 export VISGATE_API_KEY=vg-...
 
-# Health and models (minimal check)
+# Health and models (no auth)
 python examples/01_live_api_smoke.py
 
-# Exact cache: identical requests; second = cache hit
-python examples/07_cache_demo.py
+# Auth and identity
+python examples/00_auth_identity.py
 
-# Semantic cache: similar prompts; second may = cache hit (Vertex AI + Firestore)
-python examples/08_semantic_cache_demo.py
-
-# Run all capability examples (images, video, usage, providers, etc.)
+# Run all examples (requires API key; generation steps incur cost)
 python examples/run_all_capabilities.py
 ```
 
-**Regenerate sample outputs (Istanbul-themed images + video + GIF):**
+**Run with a credentials file (e.g. `sifreler` in repo root):**
 
 ```bash
-cd examples
-python fetch_sample_outputs.py              # images + video (waits for video when async)
-python make_video_and_gif.py                # video + GIF (or use --mp4 path to convert only)
-python create_placeholder_video.py          # placeholder istanbul.mp4 + .gif without API
+python examples/run_with_sifreler.py
+python examples/run_with_sifreler.py 04_videos_all_providers.py   # single example
 ```
 
+**Low-cost run (no image/video generation):** `00_smoke_sdk`, `01_live_api_smoke`, `00_auth_identity`, `01_models_catalog`, `05_usage_history_verify`, `06_provider_balances`, `09_provider_keys`, `10_api_keys`, `11_billing_readonly`. See [examples/README.md](examples/README.md) for the full table and sample outputs.
+
 Base URL defaults to `https://visgateai.com/api/v1`. Override with `VISGATE_BASE_URL` for staging or local.
 
 ## Installation
@@ -207,6 +204,7 @@ result = client.videos.generate(
     prompt="a cat walking",
     image_url=None,  # Optional, image URL to animate
     duration_seconds=5.0,  # Optional, default 5.0
+    skip_gcs_upload=False,  # Set True to return provider URL directly (faster, avoids proxy timeouts)
     params=None,  # Optional, additional model-specific parameters
 )
 ```
@@ -224,16 +222,64 @@ result = await client.videos.generate(
 ### VideoResult Properties
 
 - `id` (str): Request ID
-- `video_url` (str | None): Generated video URL
+- `video_url` (str | None): Generated video URL (may be ``None`` if generation failed or still processing)
 - `model` (str): Model identifier used
-- `provider` (str): Provider name
+- `provider` (str): Provider name (e.g. ``"fal"``, ``"replicate"``, ``"runway"``)
 - `cost` (float): Cost in USD
 - `cache_hit` (bool): Whether the result was served from cache
-- `provider_cost_avoided_micro` (int | None): When `cache_hit` is true, provider cost avoided in micro-USD (1e-6 USD). Omitted on cache miss.
+- `provider_cost_avoided_micro` (int | None): When `cache_hit` is true, provider cost avoided in micro-USD. Omitted on cache miss.
 - `latency_ms` (int | None): Request latency in milliseconds
 - `created_at` (datetime): Creation timestamp
 
-**Note:** Video generation may be asynchronous. Check `video_url` to see if the video is ready. You can convert the downloaded MP4 to a GIF for previews (e.g. `examples/make_video_and_gif.py` or `--mp4 path/to/video.mp4`).
+**Note:** Video generation can take a minute or more. Use `skip_gcs_upload=True` to get the provider URL directly and avoid proxy timeouts. For non-blocking flow, use `wait=False` and poll via the Requests resource (see below).
+
+### Async 202 + poll (wait=False)
+
+For long-running video or image generation, use `wait=False` to get a 202 response and a `GenerationRequest`; then poll until complete:
+
+```python
+req = client.videos.generate(
+    model="fal-ai/veo3",
+    prompt="Cinematic drone over Istanbul",
+    duration_seconds=5.0,
+    wait=False,
+)
+# req has .request_id and .status ("accepted", "processing", "completed", "failed")
+result = req.wait()  # blocks until completed, returns VideoResult
+print(result.video_url)
+
+# Or poll manually
+status = client.requests.get(req.request_id, wait=True)
+# status.result is VideoResult when status.status == "completed"
+```
+
+## Requests Resource
+
+Poll async generation status (202 flow for videos/images).
+
+### Sync
+
+```python
+req = client.requests.get(request_id)           # current status
+req = client.requests.get(request_id, wait=True)  # block until completed
+# req: RequestStatusResult with .request_id, .status, .result (VideoResult/ImageResult when completed)
+```
+
+### Async
+
+```python
+req = await client.requests.get(request_id)
+req = await client.requests.get(request_id, wait=True)
+```
+
+### RequestStatusResult
+
+- `request_id` (str): Request ID
+- `status` (str): `"accepted"` | `"processing"` | `"completed"` | `"failed"`
+- `result` (VideoResult | ImageResult | None): Output when status is `"completed"`
+- `error` (dict | None): Error details when status is `"failed"`
+
+Example: `examples/13_async_generation.py`.
 
 ## Usage Resource
 
@@ -311,10 +357,10 @@ except VisgateError as e:
 | Exception | HTTP Status | When |
 |-----------|-------------|------|
 | `AuthenticationError` | 401 | Invalid or missing API key |
-| `RateLimitError` | 429 | Too many requests (includes `retry_after` attribute) |
-| `ProviderError` | 502+ | Upstream provider (e.g., fal.ai) failed |
 | `ValidationError` | 422 | Bad request parameters |
-| `VisgateError` | Other | Other API errors |
+| `RateLimitError` | 429 | Too many requests (includes `retry_after` attribute) |
+| `ProviderError` | 502 | Upstream provider (Fal, Replicate, Runway) failed |
+| `VisgateError` | 404, 500, etc. | e.g. 404 + ``MODEL_NOT_FOUND`` for unsupported model; other API errors |
 
 ### Exception Properties
 
@@ -431,10 +477,10 @@ API traffic is over HTTPS. Provider keys (BYOK) are encrypted at rest; account a
 
 ## Sample outputs (Istanbul theme)
 
-All example scripts use Istanbul-themed prompts (Bosphorus, minarets, golden hour, Galata Tower, etc.). Generated assets are under `examples/sample_outputs/`: images (e.g. `generate_unified.jpg`, `sunset_istanbul.jpg`, `galata_tower.jpg`, `bosphorus_night.jpg`), cache demos, and video `istanbul.mp4` plus `istanbul.gif` (video converted to GIF for previews).
+Example scripts use Istanbul-themed prompts (Bosphorus, Galata Tower, golden hour). Generated assets are in `examples/sample_outputs/`: images (`generate_unified.jpg`, `sunset_istanbul.jpg`, `galata_tower.jpg`, `bosphorus_night.jpg`), cache demos (`cache_demo.jpg`, `semantic_exact.jpg`, `semantic_similar.jpg`), and video `istanbul.mp4` with preview `istanbul.gif`. See [examples/README.md](examples/README.md) for the output gallery and provider counts.
 
-## Additional Resources
+## Additional resources
 
 - SDK README: [README.md](../README.md)
-- Examples (step-by-step): [examples/README.md](../examples/README.md)
-- API OpenAPI Spec: https://visgateai.com/api/v1/docs
+- Examples (step-by-step and sample results): [examples/README.md](../examples/README.md)
+- OpenAPI spec: **https://visgateai.com/api/v1/docs**