genblaze-core 0.1.0__tar.gz

genblaze_core-0.1.0/.gitignore

@@ -0,0 +1,76 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+wheels/
+/MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# IDE / editors
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.project
+.settings/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+
+# Type checking
+.mypy_cache/
+.pytype/
+.pyre/
+
+# Linting
+.ruff_cache/
+
+# OS files
+.DS_Store
+Thumbs.db
+ehthumbs.db
+
+# Environment / secrets
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+credentials.json
+
+# Jupyter
+.ipynb_checkpoints/
+
+# MkDocs build output
+site/
+
+# Claude Code — local/ephemeral
+.claude/settings.local.json
+.claude/worktrees/
+CLAUDE.local.md
+
+# Hypothesis test cache
+.hypothesis/
+
+# Temp files
+*.tmp
+*.bak
+*.log

genblaze_core-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: genblaze-core
+Version: 0.1.0
+Summary: Core SDK for genblaze media generation orchestration
+Project-URL: Documentation, https://github.com/backblaze-labs/genblaze
+Project-URL: Repository, https://github.com/backblaze-labs/genblaze
+Project-URL: Changelog, https://github.com/backblaze-labs/genblaze/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/backblaze-labs/genblaze/issues
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pillow>=10.0
+Requires-Dist: pydantic<3,>=2.0
+Provides-Extra: audio
+Requires-Dist: mutagen>=1.47; extra == 'audio'
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.0; extra == 'dev'
+Requires-Dist: jsonschema>=4.0; extra == 'dev'
+Requires-Dist: mutagen>=1.47; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pyarrow>=14.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: parquet
+Requires-Dist: pyarrow>=14.0; extra == 'parquet'
+Description-Content-Type: text/markdown
+
+<!-- last_verified: 2026-04-22 -->
+# genblaze-core
+
+**Python SDK for building generative AI pipelines across video, image, and audio — with built-in SHA-256 provenance.**
+
+`genblaze-core` is the core of [genblaze](https://github.com/backblaze-labs/genblaze), an open-source orchestration framework by [Backblaze](https://www.backblaze.com/cloud-storage?utm_source=github&utm_medium=referral&utm_campaign=ai_artifacts&utm_content=genblaze) for composing multi-step AI media generation workflows. It gives you a single, provider-agnostic `Pipeline` API for text-to-video, text-to-image, text-to-speech, image-to-video, and audio generation — so you can swap models (Sora, Veo, Runway, Luma, Flux, DALL·E, ElevenLabs, Stable Audio, LMNT, GMICloud) without rewriting pipeline logic.
+
+Every pipeline run emits a canonical, hash-verified **provenance manifest** — a tamper-evident JSON document capturing the provider, model, prompt, parameters, timestamps, and SHA-256 hash of every generated asset. Manifests can be embedded directly into PNG, JPEG, WebP, MP4, MP3, and WAV files, uploaded alongside assets to S3-compatible storage, or exported to Parquet for analytics.
+
+## Why genblaze-core
+
+- **One API for every generative AI provider** — Pipelines, not per-vendor SDK glue. Fluent, composable, chainable.
+- **Built-in provenance** — Every asset gets a SHA-256–verified manifest. Prove how media was made; detect tampering.
+- **Production-ready** — Retries, timeouts, progress streaming, moderation hooks, OpenTelemetry tracing, step caching.
+- **Storage-agnostic sinks** — Drop into Backblaze B2, AWS S3, Cloudflare R2, MinIO, Parquet, or local disk.
+- **Policy + privacy controls** — Redact prompts, strip params, pointer-mode for sensitive content.
+- **Agent loops + templates** — Evaluator-driven iteration, reusable pipeline and step templates.
+- **Zero lock-in** — MIT licensed, typed, lazy imports, provider adapters are separate packages.
+
+## Features
+
+| Capability | What you get |
+|---|---|
+| `Pipeline` API | Fluent multi-step generation, fan-in (`input_from`), AV compositing via FFmpeg |
+| Provider discovery | Entry-point–based registry — `pip install genblaze-<provider>` and it's available |
+| Manifest (Pydantic) | `Run`, `Step`, `Asset` models with canonical JSON hashing and `.verify()` |
+| Media embedding | `PngHandler`, `Mp4Handler`, `Mp3Handler`, etc. — embed + extract manifests in-file |
+| Storage sink | `ObjectStorageSink` with hierarchical or content-addressable key layout |
+| Parquet sink | Partitioned run/step/asset tables for downstream analytics |
+| Observability | `OTelTracer`, `LoggingTracer`, `CompositeTracer`, structured events |
+| Agents | `AgentLoop` with pluggable `Evaluator` for iterative refinement |
+| Moderation | Pre/post moderation hooks, configurable embed policies |
+| Testing | `MockProvider`, `MockVideoProvider`, `MockAudioProvider` for offline tests |
+
+## Install
+
+```bash
+pip install genblaze-core
+```
+
+Optional extras:
+
+```bash
+pip install "genblaze-core[parquet]"   # ParquetSink for analytics
+pip install "genblaze-core[audio]"     # Audio metadata embedding (mutagen)
+```
+
+Add provider adapters separately:
+
+```bash
+pip install genblaze-openai genblaze-google genblaze-runway genblaze-luma \
+            genblaze-decart genblaze-replicate genblaze-elevenlabs \
+            genblaze-stability-audio genblaze-lmnt genblaze-gmicloud
+
+pip install genblaze-s3    # Storage backend for Backblaze B2 / AWS S3 / R2 / MinIO
+pip install genblaze-cli   # Extract / verify / replay / index manifests
+```
+
+## Quickstart — local, zero API keys
+
+```python
+from genblaze_core import Modality, Pipeline
+from genblaze_core.testing import MockVideoProvider
+
+run, manifest = (
+    Pipeline("hello-genblaze")
+    .step(MockVideoProvider(), model="mock-v1",
+          prompt="A drone shot over a coastal city at golden hour",
+          modality=Modality.VIDEO)
+    .run()
+)
+
+print(manifest.canonical_hash)   # deterministic SHA-256 of the run
+print(manifest.verify())         # True
+```
+
+## Quickstart — Sora + Backblaze B2 storage
+
+Generate a video, upload it + its manifest to [Backblaze B2](https://www.backblaze.com/cloud-storage?utm_source=github&utm_medium=referral&utm_campaign=ai_artifacts&utm_content=genblaze), verify the hash:
+
+```bash
+pip install genblaze-core genblaze-openai genblaze-s3
+export OPENAI_API_KEY="sk-..."
+export B2_KEY_ID="..."
+export B2_APP_KEY="..."
+```
+
+```python
+from genblaze_core import KeyStrategy, Modality, ObjectStorageSink, Pipeline
+from genblaze_openai import SoraProvider
+from genblaze_s3 import S3StorageBackend
+
+storage = ObjectStorageSink(
+    S3StorageBackend.for_backblaze("my-bucket"),
+    key_strategy=KeyStrategy.HIERARCHICAL,
+)
+
+result = (
+    Pipeline("hero-reel")
+    .step(SoraProvider(), model="sora-2",
+          prompt="Aerial flyover of a mountain lake at sunrise",
+          modality=Modality.VIDEO, seconds=4, size="1280x720")
+    .run(sink=storage, timeout=300)
+)
+
+print(result.run.steps[0].assets[0].url)   # durable B2 URL
+print(result.manifest.canonical_hash)      # SHA-256 of the full run
+assert result.manifest.verify()
+```
+
+## Storage — Backblaze B2 recommended
+
+[Backblaze B2](https://www.backblaze.com/cloud-storage?utm_source=github&utm_medium=referral&utm_campaign=ai_artifacts&utm_content=genblaze) is the recommended default sink for genblaze — purpose-built for large AI-generated media with S3-compatible APIs, resilient multipart uploads, Object Lock for immutable manifests, and strong cost economics at scale. One-liner credentials from `B2_KEY_ID` / `B2_APP_KEY`. See the [`genblaze-s3`](https://pypi.org/project/genblaze-s3/) backend for the full recipe plus AWS S3, Cloudflare R2, and MinIO variants.
+
+## Documentation
+
+- **Main repo**: https://github.com/backblaze-labs/genblaze
+- **Architecture**: https://github.com/backblaze-labs/genblaze/blob/main/ARCHITECTURE.md
+- **Feature docs**: https://github.com/backblaze-labs/genblaze/tree/main/docs/features
+- **Runnable examples**: https://github.com/backblaze-labs/genblaze/tree/main/examples
+
+## Related packages
+
+Provider adapters: [`genblaze-openai`](https://pypi.org/project/genblaze-openai/) · [`genblaze-google`](https://pypi.org/project/genblaze-google/) · [`genblaze-runway`](https://pypi.org/project/genblaze-runway/) · [`genblaze-luma`](https://pypi.org/project/genblaze-luma/) · [`genblaze-decart`](https://pypi.org/project/genblaze-decart/) · [`genblaze-replicate`](https://pypi.org/project/genblaze-replicate/) · [`genblaze-elevenlabs`](https://pypi.org/project/genblaze-elevenlabs/) · [`genblaze-stability-audio`](https://pypi.org/project/genblaze-stability-audio/) · [`genblaze-lmnt`](https://pypi.org/project/genblaze-lmnt/) · [`genblaze-gmicloud`](https://pypi.org/project/genblaze-gmicloud/)
+
+Storage + tooling: [`genblaze-s3`](https://pypi.org/project/genblaze-s3/) · [`genblaze-cli`](https://pypi.org/project/genblaze-cli/) · [`genblaze-langsmith`](https://pypi.org/project/genblaze-langsmith/)
+
+## License
+
+MIT

genblaze_core-0.1.0/README.md

@@ -0,0 +1,130 @@
+<!-- last_verified: 2026-04-22 -->
+# genblaze-core
+
+**Python SDK for building generative AI pipelines across video, image, and audio — with built-in SHA-256 provenance.**
+
+`genblaze-core` is the core of [genblaze](https://github.com/backblaze-labs/genblaze), an open-source orchestration framework by [Backblaze](https://www.backblaze.com/cloud-storage?utm_source=github&utm_medium=referral&utm_campaign=ai_artifacts&utm_content=genblaze) for composing multi-step AI media generation workflows. It gives you a single, provider-agnostic `Pipeline` API for text-to-video, text-to-image, text-to-speech, image-to-video, and audio generation — so you can swap models (Sora, Veo, Runway, Luma, Flux, DALL·E, ElevenLabs, Stable Audio, LMNT, GMICloud) without rewriting pipeline logic.
+
+Every pipeline run emits a canonical, hash-verified **provenance manifest** — a tamper-evident JSON document capturing the provider, model, prompt, parameters, timestamps, and SHA-256 hash of every generated asset. Manifests can be embedded directly into PNG, JPEG, WebP, MP4, MP3, and WAV files, uploaded alongside assets to S3-compatible storage, or exported to Parquet for analytics.
+
+## Why genblaze-core
+
+- **One API for every generative AI provider** — Pipelines, not per-vendor SDK glue. Fluent, composable, chainable.
+- **Built-in provenance** — Every asset gets a SHA-256–verified manifest. Prove how media was made; detect tampering.
+- **Production-ready** — Retries, timeouts, progress streaming, moderation hooks, OpenTelemetry tracing, step caching.
+- **Storage-agnostic sinks** — Drop into Backblaze B2, AWS S3, Cloudflare R2, MinIO, Parquet, or local disk.
+- **Policy + privacy controls** — Redact prompts, strip params, pointer-mode for sensitive content.
+- **Agent loops + templates** — Evaluator-driven iteration, reusable pipeline and step templates.
+- **Zero lock-in** — MIT licensed, typed, lazy imports, provider adapters are separate packages.
+
+## Features
+
+| Capability | What you get |
+|---|---|
+| `Pipeline` API | Fluent multi-step generation, fan-in (`input_from`), AV compositing via FFmpeg |
+| Provider discovery | Entry-point–based registry — `pip install genblaze-<provider>` and it's available |
+| Manifest (Pydantic) | `Run`, `Step`, `Asset` models with canonical JSON hashing and `.verify()` |
+| Media embedding | `PngHandler`, `Mp4Handler`, `Mp3Handler`, etc. — embed + extract manifests in-file |
+| Storage sink | `ObjectStorageSink` with hierarchical or content-addressable key layout |
+| Parquet sink | Partitioned run/step/asset tables for downstream analytics |
+| Observability | `OTelTracer`, `LoggingTracer`, `CompositeTracer`, structured events |
+| Agents | `AgentLoop` with pluggable `Evaluator` for iterative refinement |
+| Moderation | Pre/post moderation hooks, configurable embed policies |
+| Testing | `MockProvider`, `MockVideoProvider`, `MockAudioProvider` for offline tests |
+
+## Install
+
+```bash
+pip install genblaze-core
+```
+
+Optional extras:
+
+```bash
+pip install "genblaze-core[parquet]"   # ParquetSink for analytics
+pip install "genblaze-core[audio]"     # Audio metadata embedding (mutagen)
+```
+
+Add provider adapters separately:
+
+```bash
+pip install genblaze-openai genblaze-google genblaze-runway genblaze-luma \
+            genblaze-decart genblaze-replicate genblaze-elevenlabs \
+            genblaze-stability-audio genblaze-lmnt genblaze-gmicloud
+
+pip install genblaze-s3    # Storage backend for Backblaze B2 / AWS S3 / R2 / MinIO
+pip install genblaze-cli   # Extract / verify / replay / index manifests
+```
+
+## Quickstart — local, zero API keys
+
+```python
+from genblaze_core import Modality, Pipeline
+from genblaze_core.testing import MockVideoProvider
+
+run, manifest = (
+    Pipeline("hello-genblaze")
+    .step(MockVideoProvider(), model="mock-v1",
+          prompt="A drone shot over a coastal city at golden hour",
+          modality=Modality.VIDEO)
+    .run()
+)
+
+print(manifest.canonical_hash)   # deterministic SHA-256 of the run
+print(manifest.verify())         # True
+```
+
+## Quickstart — Sora + Backblaze B2 storage
+
+Generate a video, upload it + its manifest to [Backblaze B2](https://www.backblaze.com/cloud-storage?utm_source=github&utm_medium=referral&utm_campaign=ai_artifacts&utm_content=genblaze), verify the hash:
+
+```bash
+pip install genblaze-core genblaze-openai genblaze-s3
+export OPENAI_API_KEY="sk-..."
+export B2_KEY_ID="..."
+export B2_APP_KEY="..."
+```
+
+```python
+from genblaze_core import KeyStrategy, Modality, ObjectStorageSink, Pipeline
+from genblaze_openai import SoraProvider
+from genblaze_s3 import S3StorageBackend
+
+storage = ObjectStorageSink(
+    S3StorageBackend.for_backblaze("my-bucket"),
+    key_strategy=KeyStrategy.HIERARCHICAL,
+)
+
+result = (
+    Pipeline("hero-reel")
+    .step(SoraProvider(), model="sora-2",
+          prompt="Aerial flyover of a mountain lake at sunrise",
+          modality=Modality.VIDEO, seconds=4, size="1280x720")
+    .run(sink=storage, timeout=300)
+)
+
+print(result.run.steps[0].assets[0].url)   # durable B2 URL
+print(result.manifest.canonical_hash)      # SHA-256 of the full run
+assert result.manifest.verify()
+```
+
+## Storage — Backblaze B2 recommended
+
+[Backblaze B2](https://www.backblaze.com/cloud-storage?utm_source=github&utm_medium=referral&utm_campaign=ai_artifacts&utm_content=genblaze) is the recommended default sink for genblaze — purpose-built for large AI-generated media with S3-compatible APIs, resilient multipart uploads, Object Lock for immutable manifests, and strong cost economics at scale. One-liner credentials from `B2_KEY_ID` / `B2_APP_KEY`. See the [`genblaze-s3`](https://pypi.org/project/genblaze-s3/) backend for the full recipe plus AWS S3, Cloudflare R2, and MinIO variants.
+
+## Documentation
+
+- **Main repo**: https://github.com/backblaze-labs/genblaze
+- **Architecture**: https://github.com/backblaze-labs/genblaze/blob/main/ARCHITECTURE.md
+- **Feature docs**: https://github.com/backblaze-labs/genblaze/tree/main/docs/features
+- **Runnable examples**: https://github.com/backblaze-labs/genblaze/tree/main/examples
+
+## Related packages
+
+Provider adapters: [`genblaze-openai`](https://pypi.org/project/genblaze-openai/) · [`genblaze-google`](https://pypi.org/project/genblaze-google/) · [`genblaze-runway`](https://pypi.org/project/genblaze-runway/) · [`genblaze-luma`](https://pypi.org/project/genblaze-luma/) · [`genblaze-decart`](https://pypi.org/project/genblaze-decart/) · [`genblaze-replicate`](https://pypi.org/project/genblaze-replicate/) · [`genblaze-elevenlabs`](https://pypi.org/project/genblaze-elevenlabs/) · [`genblaze-stability-audio`](https://pypi.org/project/genblaze-stability-audio/) · [`genblaze-lmnt`](https://pypi.org/project/genblaze-lmnt/) · [`genblaze-gmicloud`](https://pypi.org/project/genblaze-gmicloud/)
+
+Storage + tooling: [`genblaze-s3`](https://pypi.org/project/genblaze-s3/) · [`genblaze-cli`](https://pypi.org/project/genblaze-cli/) · [`genblaze-langsmith`](https://pypi.org/project/genblaze-langsmith/)
+
+## License
+
+MIT

genblaze_core-0.1.0/genblaze_core/__init__.py

@@ -0,0 +1,110 @@
+"""genblaze-core — orchestration framework for media generation."""
+
+from genblaze_core._version import __version__
+
+_LAZY_IMPORTS: dict[str, tuple[str, str]] = {
+    # pipeline (primary entry point)
+    "Pipeline": ("genblaze_core.pipeline.pipeline", "Pipeline"),
+    "PipelineResult": ("genblaze_core.pipeline.result", "PipelineResult"),
+    "StepCompleteEvent": ("genblaze_core.pipeline.result", "StepCompleteEvent"),
+    # pipeline cache
+    "StepCache": ("genblaze_core.pipeline.cache", "StepCache"),
+    # pipeline templates
+    "PipelineTemplate": ("genblaze_core.pipeline.template", "PipelineTemplate"),
+    "StepTemplate": ("genblaze_core.pipeline.template", "StepTemplate"),
+    # moderation
+    "ModerationHook": ("genblaze_core.pipeline.moderation", "ModerationHook"),
+    "ModerationResult": ("genblaze_core.pipeline.moderation", "ModerationResult"),
+    # builders
+    "RunBuilder": ("genblaze_core.builders.run_builder", "RunBuilder"),
+    "StepBuilder": ("genblaze_core.builders.step_builder", "StepBuilder"),
+    # providers
+    "BaseProvider": ("genblaze_core.providers.base", "BaseProvider"),
+    "ProviderCapabilities": ("genblaze_core.providers.base", "ProviderCapabilities"),
+    "SubmitResult": ("genblaze_core.providers.base", "SubmitResult"),
+    "SyncProvider": ("genblaze_core.providers.base", "SyncProvider"),
+    "validate_asset_url": ("genblaze_core.providers.base", "validate_asset_url"),
+    "validate_chain_input_url": ("genblaze_core.providers.base", "validate_chain_input_url"),
+    "FFmpegCompositor": ("genblaze_core.providers.compositor", "FFmpegCompositor"),
+    "FFmpegTransform": ("genblaze_core.providers.transform", "FFmpegTransform"),
+    "ProgressEvent": ("genblaze_core.providers.progress", "ProgressEvent"),
+    # observability
+    "StreamEvent": ("genblaze_core.observability.events", "StreamEvent"),
+    "Tracer": ("genblaze_core.observability.tracer", "Tracer"),
+    "NoOpTracer": ("genblaze_core.observability.tracer", "NoOpTracer"),
+    "LoggingTracer": ("genblaze_core.observability.tracer", "LoggingTracer"),
+    "OTelTracer": ("genblaze_core.observability.tracer", "OTelTracer"),
+    "CompositeTracer": ("genblaze_core.observability.tracer", "CompositeTracer"),
+    "StructuredLogger": ("genblaze_core.observability.logger", "StructuredLogger"),
+    # agents
+    "AgentLoop": ("genblaze_core.agents.loop", "AgentLoop"),
+    "AgentContext": ("genblaze_core.agents.loop", "AgentContext"),
+    "AgentIteration": ("genblaze_core.agents.loop", "AgentIteration"),
+    "AgentResult": ("genblaze_core.agents.loop", "AgentResult"),
+    "Evaluator": ("genblaze_core.agents.evaluator", "Evaluator"),
+    "EvaluationResult": ("genblaze_core.agents.evaluator", "EvaluationResult"),
+    "CallableEvaluator": ("genblaze_core.agents.evaluator", "CallableEvaluator"),
+    "ThresholdEvaluator": ("genblaze_core.agents.evaluator", "ThresholdEvaluator"),
+    # models
+    "Manifest": ("genblaze_core.models.manifest", "Manifest"),
+    "Run": ("genblaze_core.models.run", "Run"),
+    "Step": ("genblaze_core.models.step", "Step"),
+    "Asset": ("genblaze_core.models.asset", "Asset"),
+    "AudioMetadata": ("genblaze_core.models.asset", "AudioMetadata"),
+    "Track": ("genblaze_core.models.asset", "Track"),
+    "VideoMetadata": ("genblaze_core.models.asset", "VideoMetadata"),
+    "WordTiming": ("genblaze_core.models.asset", "WordTiming"),
+    # enums
+    "Modality": ("genblaze_core.models.enums", "Modality"),
+    "StepType": ("genblaze_core.models.enums", "StepType"),
+    "RunStatus": ("genblaze_core.models.enums", "RunStatus"),
+    "StepStatus": ("genblaze_core.models.enums", "StepStatus"),
+    "PromptVisibility": ("genblaze_core.models.enums", "PromptVisibility"),
+    "ProviderErrorCode": ("genblaze_core.models.enums", "ProviderErrorCode"),
+    "EmbedPolicy": ("genblaze_core.models.policy", "EmbedPolicy"),
+    "PromptTemplate": ("genblaze_core.models.prompt_template", "PromptTemplate"),
+    # provider discovery
+    "discover_providers": ("genblaze_core.providers.registry", "discover_providers"),
+    # sinks
+    "BaseSink": ("genblaze_core.sinks.base", "BaseSink"),
+    "ParquetSink": ("genblaze_core.sinks.parquet", "ParquetSink"),
+    # storage
+    "StorageBackend": ("genblaze_core.storage.base", "StorageBackend"),
+    "ObjectStorageSink": ("genblaze_core.storage.sink", "ObjectStorageSink"),
+    "AssetTransfer": ("genblaze_core.storage.transfer", "AssetTransfer"),
+    "KeyStrategy": ("genblaze_core.storage.base", "KeyStrategy"),
+    "ObjectLockConfig": ("genblaze_core.storage.base", "ObjectLockConfig"),
+    # testing
+    "MockProvider": ("genblaze_core.testing", "MockProvider"),
+    "MockVideoProvider": ("genblaze_core.testing", "MockVideoProvider"),
+    "MockAudioProvider": ("genblaze_core.testing", "MockAudioProvider"),
+    "ProviderComplianceTests": ("genblaze_core.testing", "ProviderComplianceTests"),
+    # exceptions
+    "GenblazeError": ("genblaze_core.exceptions", "GenblazeError"),
+    "PipelineTimeoutError": ("genblaze_core.exceptions", "PipelineTimeoutError"),
+    "EmbeddingError": ("genblaze_core.exceptions", "EmbeddingError"),
+    "StorageError": ("genblaze_core.exceptions", "StorageError"),
+    "ProviderError": ("genblaze_core.exceptions", "ProviderError"),
+    "ManifestError": ("genblaze_core.exceptions", "ManifestError"),
+    "SinkError": ("genblaze_core.exceptions", "SinkError"),
+    "WebhookError": ("genblaze_core.exceptions", "WebhookError"),
+    # webhooks
+    "WebhookNotifier": ("genblaze_core.webhooks.notifier", "WebhookNotifier"),
+    "WebhookConfig": ("genblaze_core.webhooks.notifier", "WebhookConfig"),
+    "WebhookEvent": ("genblaze_core.webhooks.notifier", "WebhookEvent"),
+    "WebhookSink": ("genblaze_core.webhooks.sink", "WebhookSink"),
+}
+
+__all__ = [*_LAZY_IMPORTS.keys(), "__version__"]
+
+
+def __getattr__(name: str):
+    if name in _LAZY_IMPORTS:
+        module_path, attr = _LAZY_IMPORTS[name]
+        import importlib
+
+        mod = importlib.import_module(module_path)
+        val = getattr(mod, attr)
+        globals()[name] = val
+        return val
+    raise AttributeError(f"module 'genblaze_core' has no attribute {name!r}")

genblaze_core-0.1.0/genblaze_core/_utils.py

@@ -0,0 +1,158 @@
+"""Internal utilities."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import ipaddress
+import random
+import re
+import socket
+import tempfile
+import uuid
+from collections.abc import Coroutine
+from concurrent.futures import ThreadPoolExecutor
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse as _urlparse
+
+
+def new_id() -> str:
+    """Generate a new UUID4 string."""
+    return str(uuid.uuid4())
+
+
+def utc_now() -> datetime:
+    """Return current UTC datetime."""
+    return datetime.now(UTC)
+
+
+def compute_sha256(data: bytes) -> str:
+    """Compute SHA-256 hex digest of raw bytes."""
+    return hashlib.sha256(data).hexdigest()
+
+
+def _run_async(coro: Coroutine) -> Any:
+    """Run an async coroutine from sync code safely.
+
+    If there's already a running event loop (e.g. inside Jupyter or an async provider
+    called from BaseProvider.invoke), runs in a new thread to avoid RuntimeError.
+    Otherwise uses asyncio.run().
+    """
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        loop = None
+
+    if loop is not None and loop.is_running():
+        # Already inside an event loop — run in a separate thread
+        with ThreadPoolExecutor(max_workers=1) as pool:
+            return pool.submit(asyncio.run, coro).result()
+    return asyncio.run(coro)
+
+
+# ---------------------------------------------------------------------------
+# SSRF protection — shared by storage/transfer.py and webhooks/notifier.py
+# ---------------------------------------------------------------------------
+
+# Private/reserved IP ranges blocked to prevent SSRF
+BLOCKED_NETWORKS = [
+    ipaddress.ip_network("0.0.0.0/8"),  # "This host" — resolves to loopback on Linux
+    ipaddress.ip_network("10.0.0.0/8"),
+    ipaddress.ip_network("172.16.0.0/12"),
+    ipaddress.ip_network("192.168.0.0/16"),
+    ipaddress.ip_network("127.0.0.0/8"),
+    ipaddress.ip_network("169.254.0.0/16"),  # Link-local / IMDS
+    ipaddress.ip_network("100.64.0.0/10"),  # Carrier-grade NAT
+    ipaddress.ip_network("::1/128"),  # IPv6 loopback
+    ipaddress.ip_network("fc00::/7"),  # IPv6 unique local
+    ipaddress.ip_network("fe80::/10"),  # IPv6 link-local
+]
+
+
+# Allowed parent directories for file:// inputs (shared by storage + ffmpeg providers)
+# Deduplicate: /tmp and gettempdir() may resolve to the same or different paths
+ALLOWED_FILE_ROOTS: tuple[Path, ...] = tuple(
+    {Path(tempfile.gettempdir()).resolve(), Path("/tmp").resolve()}  # noqa: S108
+)
+
+
+def check_ssrf(url: str, *, exc_type: type[Exception] = ValueError) -> None:
+    """Reject non-HTTPS URLs and hostnames resolving to private IP ranges.
+
+    Shared SSRF guard used by storage transfers and webhook dispatch.
+    Callers pass their domain-specific exception type via ``exc_type``.
+    """
+    parsed = _urlparse(url)
+    if parsed.scheme not in ("https",):
+        raise exc_type(f"Only HTTPS URLs are allowed, got: {parsed.scheme}://")
+
+    host = parsed.hostname or ""
+    if host.lower() == "localhost":
+        raise exc_type(f"Private/loopback URLs are not allowed: {host}")
+
+    try:
+        addrinfos = socket.getaddrinfo(host, None, proto=socket.IPPROTO_TCP)
+    except socket.gaierror as exc:
+        raise exc_type(f"Cannot resolve hostname: {host}") from exc
+
+    for _, _, _, _, sockaddr in addrinfos:
+        try:
+            ip = ipaddress.ip_address(str(sockaddr[0]))
+        except ValueError:
+            continue
+        if any(ip in net for net in BLOCKED_NETWORKS):
+            raise exc_type(f"Private/loopback URLs are not allowed: {host}")
+
+
+# ---------------------------------------------------------------------------
+# Manifest size cap — bounds the JSON payload accepted from disk/media
+# ---------------------------------------------------------------------------
+# Real manifests are O(KB). 16 MiB is generous and bounds OOM blast from
+# malicious media or sidecars that declare absurd payload sizes.
+MAX_MANIFEST_BYTES = 16 * 1024 * 1024
+
+
+# ---------------------------------------------------------------------------
+# Credential pattern detection — used by error sanitization (providers/base.py)
+# AND by Pipeline.step build-time rejection of secret-shaped params values.
+# Centralized here so both call sites share one regex of record.
+# ---------------------------------------------------------------------------
+_SECRET_PATTERNS = re.compile(
+    r"(r8_[A-Za-z0-9]{20,})"  # Replicate tokens
+    r"|(sk-ant-[A-Za-z0-9\-]{20,})"  # Anthropic API keys (before generic sk-)
+    r"|(sk-[A-Za-z0-9]{20,})"  # OpenAI-style keys
+    r"|(AIza[A-Za-z0-9_\-]{30,})"  # Google API keys
+    r"|(AKIA[A-Z0-9]{16})"  # AWS access key IDs
+    r"|(Bearer\s+[A-Za-z0-9._\-]{20,})"  # Bearer tokens
+    r"|(Token\s+[A-Za-z0-9._\-]{20,})"  # Token auth headers
+    r"|(\bapi[_-]key[=:]\s*[A-Za-z0-9._\-]{20,})",  # api_key=... / api-key:...
+    re.IGNORECASE,
+)
+
+
+def jittered_backoff(attempt: int) -> float:
+    """Compute exponential backoff with jitter to avoid thundering herd.
+
+    Starts at 1s, doubles per attempt, capped at 30s base with up to 25% jitter.
+    """
+    base = min(2**attempt, 30)
+    return base * (1 + random.uniform(0, 0.25))  # noqa: S311 — jitter, not crypto
+
+
+def probe_audio_duration(path: str | Any) -> float | None:
+    """Try to read audio duration from a file using mutagen (optional dep).
+
+    Returns duration in seconds, or None if mutagen is not installed or
+    the file format is not recognized.
+    """
+    try:
+        from mutagen import File as MutagenFile
+
+        audio = MutagenFile(str(path))
+        if audio is not None and audio.info is not None:
+            return audio.info.length
+    except Exception:  # noqa: S110 — mutagen is optional, fail gracefully
+        pass
+    return None

genblaze_core-0.1.0/genblaze_core/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

genblaze_core-0.1.0/genblaze_core/agents/__init__.py

@@ -0,0 +1,20 @@
+"""Agent / reasoning layer — evaluate outputs, refine prompts, retry."""
+
+from genblaze_core.agents.evaluator import (
+    CallableEvaluator,
+    EvaluationResult,
+    Evaluator,
+    ThresholdEvaluator,
+)
+from genblaze_core.agents.loop import AgentContext, AgentIteration, AgentLoop, AgentResult
+
+__all__ = [
+    "AgentContext",
+    "AgentIteration",
+    "AgentLoop",
+    "AgentResult",
+    "CallableEvaluator",
+    "EvaluationResult",
+    "Evaluator",
+    "ThresholdEvaluator",
+]