docs: document model attribution and test environments

Author: ALexFIlik

README.md

@@ -50,6 +50,15 @@ Acceleration options:
 - NVIDIA GPU: CUDA-compatible PyTorch build.
 - CPU: useful for tests and lightweight smoke checks, but slow for production video inference.
 
+## Tested Environments
+
+Current validation has been done in two practical environments:
+
+- Local development: Intel macOS on an older i7 Mac, running the app and regression suite in CPU mode.
+- Cloud/server worker: NVIDIA CUDA GPU worker, used for end-to-end model workflow checks.
+
+The Intel macOS path uses compatibility pins and small integration patches where newer upstream packages no longer support older architecture constraints cleanly. In particular, the project pins older PyTorch/torchvision on `darwin x86_64`, keeps `numpy<2` there, constrains GVM-related `diffusers`, and includes helper patches/workarounds for model packages that assume newer Linux/CUDA-oriented stacks. See [docs/installation.md](docs/installation.md) and [docs/models.md](docs/models.md) before treating this as a universal production support matrix.
+
 ## Quick Start
 
 ```bash
@@ -78,6 +87,12 @@ KeyFlow Studio checks the configured model cache at runtime and downloads suppor
 
 Typical local model locations are managed by the application settings or by `KEYFLOW_MODELS_DIR`. See [docs/models.md](docs/models.md) for details.
 
+## Third-Party Models
+
+KeyFlow Studio is an orchestration UI/runtime around several third-party model projects. Those projects and their authors retain their own copyrights, licenses, model terms, checkpoints, and trademarks. This repository does not claim ownership of the upstream models or weights.
+
+Integrated or supported workflows include CorridorKey by `nikopueringer`, BiRefNet by `ZhengPeng7`, GVM by `geyongtao`, MatAnyone2 by `pq-yang`, and Meta/Facebook Research SAM-family models where installed by the user. See [docs/models.md](docs/models.md) for links and attribution details.
+
 ## Cloud GPU Worker
 
 The repository includes an optional EC2 worker under [ec2_worker/](ec2_worker/) for headless GPU inference. This is useful when local hardware is not strong enough for final production-sized tests.

docs/installation.md

@@ -25,6 +25,13 @@ pip install -r requirements.txt
 
 The pinned defaults in `requirements.txt` are chosen for development compatibility, including Intel macOS constraints. For CUDA systems, install a PyTorch build that matches your NVIDIA driver and CUDA runtime before installing model-specific packages.
 
+Current compatibility baseline:
+
+- Local development and regression checks have been run on an older Intel i7 Mac in CPU mode.
+- The EC2/server worker path has been tested with NVIDIA CUDA for end-to-end model workflows.
+- Intel macOS `x86_64` intentionally uses older PyTorch/torchvision pins, `numpy<2`, and selected dependency ceilings so the project can still run on that older architecture.
+- Some model packages require local workarounds or patch files. See `scripts/install_sam2_intel_workaround.sh`, `ec2_worker/_patch/`, and [models.md](models.md).
+
 Some model workflows may require extra upstream packages, private tokens, or license acceptance. See [models.md](models.md) for model cache and weight behavior.
 
 ## 4. Install FFmpeg

docs/models.md

@@ -2,6 +2,25 @@
 
 KeyFlow Studio integrates several third-party model workflows. Model weights are not committed to this repository.
 
+## Attribution And Ownership
+
+KeyFlow Studio provides integration code, graph orchestration, UI controls, and worker/runtime glue. The model architectures, upstream packages, checkpoints, papers, names, and licenses belong to their respective authors and projects.
+
+Before redistributing this repository, binaries, screenshots, demos, or generated assets, review each upstream license and model card. Some projects may restrict commercial use, redistribution of weights, or use of generated assets.
+
+Known upstream projects currently referenced by the integration:
+
+| Workflow | Upstream project / source | Notes |
+| --- | --- | --- |
+| CorridorKey | [nikopueringer/CorridorKey](https://github.com/nikopueringer/CorridorKey), [CorridorKey_v1.0](https://huggingface.co/nikopueringer/CorridorKey_v1.0), [CorridorKeyBlue_1.0](https://huggingface.co/nikopueringer/CorridorKeyBlue_1.0) | Green/blue screen keying checkpoints are resolved outside Git history. Check upstream terms before redistribution. |
+| BiRefNet | [ZhengPeng7/BiRefNet](https://huggingface.co/ZhengPeng7/BiRefNet) and related `ZhengPeng7/BiRefNet_*` Hugging Face repos | Used as a mask/alpha source. Presets may map to different upstream repos. |
+| GVM | [geyongtao/gvm](https://huggingface.co/geyongtao/gvm) | Used for generative video matting / alpha generation. KeyFlow includes compatibility patch files for the worker/runtime path. |
+| MatAnyone2 | [pq-yang/MatAnyone2](https://github.com/pq-yang/MatAnyone2) | Optional matting workflow. The checkpoint is downloaded or placed outside Git history. |
+| SAM2 | [facebookresearch/sam2](https://github.com/facebookresearch/sam2) | Optional segmentation workflow when installed in the active environment. |
+| SAM3 | [facebookresearch/sam3](https://github.com/facebookresearch/sam3), [facebook/sam3](https://huggingface.co/facebook/sam3) | Optional SAM3 workflow. Weight download may require manual setup or upstream access rules. |
+
+This table is attribution documentation, not a license grant. Always follow the upstream project instructions for installation, citation, and allowed use.
+
 At runtime, the application checks the configured model cache and downloads supported weights automatically when they are available from the configured upstream source. Some upstream models may still require manual license acceptance, private tokens, or external setup, so automatic download should be treated as a supported path rather than a universal guarantee for every model.
 
 ## Storage Policy
@@ -31,10 +50,32 @@ export KEYFLOW_MODELS_DIR="$HOME/.local/share/com.keyflow.studio/models"
 
 CorridorKey weights can be resolved through the app-managed download path when available. Keep the checkpoint outside Git history.
 
+Supported checkpoint sources currently include the green-screen `nikopueringer/CorridorKey_v1.0` and blue-screen `nikopueringer/CorridorKeyBlue_1.0` repositories. The local integration defaults to `screen_color=green` for backward compatibility.
+
 ## BiRefNet, SAM, GVM, MatAnyone2
 
 Each model may have separate licensing, hardware, and storage requirements. Check the upstream project before redistributing weights or derived assets.
 
+## Tested Runtime Notes
+
+The current development/test baseline is intentionally conservative:
+
+- Local app and regression tests have been run on an older Intel i7 Mac in CPU mode.
+- Cloud/server worker workflows have also been tested on a CUDA GPU worker.
+- CPU mode is useful for validation and small samples, but production-sized video model inference is expected to be slow on old Intel hardware.
+
+## Legacy Intel macOS Compatibility
+
+Some modern ML packages no longer fit older Intel macOS constraints cleanly. For that reason the repository uses compatibility pins and local integration workarounds, including:
+
+- `torch==2.2.2` and `torchvision==0.17.2` on `darwin x86_64`, because newer upstream combinations may not provide usable wheels for this architecture.
+- `numpy<2` on `darwin x86_64` to avoid binary compatibility problems with older PyTorch wheels.
+- `diffusers>=0.30,<0.32` for GVM compatibility, because newer versions changed behavior/dependencies in ways that require newer Torch stacks.
+- `scripts/install_sam2_intel_workaround.sh` for Intel macOS SAM2 package constraints.
+- `ec2_worker/_patch/` patch files for cloud/runtime compatibility around GVM components.
+
+These patches and pins are pragmatic compatibility work, not forks of the upstream projects. When running on modern Linux/CUDA machines, prefer the CUDA-compatible PyTorch build that matches the driver/runtime and validate the model-specific stack separately.
+
 ## Public Repository Rule
 
 Before making the repository public, verify that model weights and generated media are absent from both the working tree and Git history.