Update to Flyte

{
  "description": "Generates flyte.Image specs, Dockerfiles, dependency management, image tagging strategy, and reproducible build instructions for Flyte tasks. Use when the user needs to build container images for Flyte tasks, configure custom images, manage dependencies, or set up reproducible builds. Trigger words: \"image\", \"Docker\", \"build\", \"dependency\", \"pip package\", \"debian base\", \"image builder\", \"push image\", \"container\", \"Dockerfile\", \"uv\", \"requirements\".",
  "included_files": [],
  "name": "flyte-sdk-ship",
  "skill_md_contents": "---\nname: flyte-sdk-ship\ndescription: 'Generates flyte.Image specs, Dockerfiles, dependency management, image tagging strategy, and reproducible build instructions for Flyte tasks. Use when the user needs to build container images for Flyte tasks, configure custom images, manage dependencies, or set up reproducible builds. Trigger words: \"image\", \"Docker\", \"build\", \"dependency\", \"pip package\", \"debian base\", \"image builder\", \"push image\", \"container\", \"Dockerfile\", \"uv\", \"requirements\".'\n---\n\n# Flyte 2 SDK Ship Skill\n\nGenerate images, Dockerfiles, and dependency configurations for Flyte 2 tasks.\n\n## Grounding References\n\n| Resource | URL |\n|---|---|\n| Official docs | https://www.union.ai/docs/v2/flyte |\n| Docs index (LLMs) | https://www.union.ai/docs/v2/flyte/llms.txt |\n| SDK API reference | https://www.union.ai/docs/v2/union/api-reference/flyte-sdk/ |\n| CLI API reference | https://www.union.ai/docs/v2/union/api-reference/flyte-cli/ |\n| flyte-sdk source | https://github.com/flyteorg/flyte-sdk |\n| Example code | https://github.com/unionai/unionai-examples |\n| Flyte MCP tools | Available via the `flyte-cluster` and `flyte-docs` MCP servers |\n\n**Ground unfamiliar APIs in real examples.** When unsure of a current Flyte 2 API, or for a pattern not shown below, and the `flyte-docs` search tools are available, search them first — by exact symbol (`TaskEnvironment`, `flyte.io.File`, `map_task`), since matching is literal substring, not semantic — then adapt a real example rather than inventing one, and cite the file or section you pulled it from. (Flyte 2 is not `flytekit`; priors are often wrong.)\n\n## flyte.Image — Programmatic Image Definition\n\nUse `flyte.Image` to define task container images in Python. Flyte builds and pushes them automatically.\n\n### From Debian Base\n\n```python\nimport flyte\n\nenv = flyte.TaskEnvironment(\n    name=\"etl-pipeline\",\n    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(\n        \"pandas\", \"polars\", \"pyarrow\", \"boto3\",\n    ).with_system_packages(\n        \"git\", \"curl\", \"wget\",\n    ),\n)\n```\n\n### From Existing Image\n\n```python\nenv = flyte.TaskEnvironment(\n    name=\"ml-training\",\n    image=flyte.Image.from_base(\n        \"ghcr.io/flyteorg/flyte:py3.12-v2\",  # base image\n    ).with_pip_packages(\n        \"torch\", \"transformers\", \"datasets\",\n    ),\n)\n```\n\n### Image from uv Script Metadata\n\nWhen using a `# /// script` header, Flyte can derive the image from the script's dependencies:\n\n```python\n# /// script\n# requires-python = \">=3.12\"\n# dependencies = [\n#   \"pandas\",\n#   \"polars\",\n# ]\n# ///\n\n# Flyte reads the script metadata and builds the image automatically\n```\n\n## Image Configuration Methods\n\n### with_pip_packages\n\n```python\nimage = flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(\n    \"pandas\",           # latest version\n    \"torch>=2.0\",       # version constraint\n    \"transformers==4.40\",  # pinned version\n)\n```\n\n### with_system_packages\n\n```python\nimage = image.with_system_packages(\n    \"git\", \"curl\", \"wget\", \"jq\", \"ffmpeg\",\n)\n```\n\n### with_commands (apt-get run)\n\n```python\nimage = image.with_commands(\n    \"apt-get update && apt-get install -y libgl1-mesa-glx\",  # for OpenCV\n    \"pip install --upgrade pip\",\n)\n```\n\n### with_env_vars\n\n```python\nimage = image.with_env_vars({\n    \"HF_HUB_DISABLE_TELEMETRY\": \"1\",\n    \"PYTHONDONTWRITEBYTECODE\": \"1\",\n})\n```\n\n### with_local_rs_controller\n\n```python\n# For development: bake the Rust controller wheel into the image\nimage = image.with_local_rs_controller()\n```\n\n## Custom Dockerfile\n\nFor complex builds, use a custom `Dockerfile`:\n\n```dockerfile\n# Dockerfile\nFROM python:3.12-slim\n\nRUN apt-get update && apt-get install -y \\\n    git \\\n    libgl1-mesa-glx \\\n    && rm -rf /var/lib/apt/lists/*\n\nRUN pip install --no-cache-dir \\\n    torch \\\n    transformers \\\n    datasets\n\nWORKDIR /app\nCOPY . /app\n\nENV HF_HUB_DISABLE_TELEMETRY=1\n```\n\n```python\nenv = flyte.TaskEnvironment(\n    name=\"ml-training\",\n    image=flyte.Image.from_dockerfile(\"Dockerfile\"),\n)\n```\n\n## Image Builder Configuration\n\n### Local builder (default for development)\n\n```yaml\n# .flyte/config.yaml\nimage:\n  builder: local\n```\n\nBuilds images locally using Docker. Fast iteration, requires Docker installed.\n\n### Remote builder (CI/production)\n\n```yaml\n# .flyte/config.yaml\nimage:\n  builder: remote\n  registry: \"ghcr.io/myorg\"\n  repository: \"flyte-tasks\"\n```\n\nBuilds images in a remote Docker build service. No local Docker needed.\n\n### Push to registry\n\n```python\n# Programmatically configure the builder\nenv = flyte.TaskEnvironment(\n    name=\"training\",\n    image=flyte.Image.from_debian_base(python_version=(3, 12)),\n)\n# Set registry via config or CLI\n```\n\n## Image Tagging Strategy\n\n### Version tags (recommended for production)\n\n```bash\n# Tag with git sha for reproducibility\nVERSION=$(git rev-parse --short HEAD)\nflyte deploy --version $VERSION\n```\n\n### Semantic versioning\n\n```bash\n# Tag with semver\nflyte deploy --version 1.2.3\n```\n\n### Auto versioning (development)\n\n```bash\n# Flyte auto-generates a version based on code hash\nflyte deploy --version auto\n```\n\n## Dependency Management Patterns\n\n### Using pyproject.toml\n\n```toml\n[project]\nname = \"my-flyte-pipeline\"\nversion = \"0.1.0\"\nrequires-python = \">=3.12\"\ndependencies = [\n    \"pandas\",\n    \"polars\",\n    \"flyte\",\n]\n\n[project.optional-dependencies]\nml = [\"torch\", \"transformers\", \"datasets\"]\ndev = [\"pytest\", \"ruff\"]\n```\n\n### Using requirements.txt\n\n```\npandas>=2.0\npolars>=0.20\npyarrow>=14.0\nboto3>=1.34\nflyte\n```\n\n### uv pyproject.toml (monorepo)\n\n```toml\n[project]\nname = \"flyte-monorepo\"\nversion = \"0.1.0\"\nrequires-python = \">=3.12\"\ndependencies = [\"flyte\"]\n\n[tool.uv.sources]\n# Pin flyte to local path during development\nflyte = { workspace = true }\n```\n\n## BYOI (Bring Your Own Image) Pattern\n\nFor multi-team setups where each team manages their own images:\n\n```python\n# team-a/pipeline.py\nimport flyte\n\n# Reference an externally-built image\nenv = flyte.TaskEnvironment(\n    name=\"team-a-task\",\n    image=flyte.Image.from_base(\"ghcr.io/team-a/base:v1.2.3\"),\n)\n\n@env.task\nasync def process(data: str) -> str:\n    ...\n```\n\n```python\n# team-b/pipeline.py\nimport flyte\nimport flyte.io\n\nenv = flyte.TaskEnvironment(\n    name=\"team-b-task\",\n    image=flyte.Image.from_base(\"ghcr.io/team-b/base:v2.0.0\"),\n)\n\n@env.task\nasync def train(model_path: flyte.io.File) -> dict:\n    ...\n```\n\n## Common Image Recipes\n\n### Data Engineering\n\n```python\nenv = flyte.TaskEnvironment(\n    name=\"etl\",\n    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(\n        \"pandas\", \"polars\", \"pyarrow\", \"boto3\", \"sqlalchemy\",\n        \"db-dtypes\",  # for BigQuery\n        \"google-cloud-bigquery\",\n    ).with_system_packages(\"git\", \"curl\"),\n)\n```\n\n### ML Training (GPU)\n\n```python\nenv = flyte.TaskEnvironment(\n    name=\"training\",\n    image=flyte.Image.from_base(\"nvidia/cuda:12.1-py3\").with_pip_packages(\n        \"torch\", \"torchvision\", \"transformers\", \"datasets\",\n        \"accelerate\", \"peft\",\n    ),\n)\n```\n\n### LLM Inference\n\n```python\nenv = flyte.TaskEnvironment(\n    name=\"inference\",\n    image=flyte.Image.from_base(\"python:3.12-slim\").with_pip_packages(\n        \"fastapi\", \"uvicorn\", \"torch\", \"transformers\",\n        \"bitsandbytes\", \"vllm\",\n    ),\n)\n```\n\n### Data Quality\n\n```python\nenv = flyte.TaskEnvironment(\n    name=\"data-quality\",\n    image=flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(\n        \"pandas\", \"polars\", \"pyarrow\",\n        \"great-expectations\",  # or \"pandera\"\n        \"soda-core\",\n        \"boto3\",\n    ),\n)\n```\n\n## Build and Deploy Workflow\n\n### Build locally\n\n```bash\n# Deploy will auto-build the image\nflyte deploy pipeline.py\n\n# Dry-run to see what would be built\nflyte deploy --dry-run pipeline.py\n```\n\n### Build with remote builder\n\n```bash\n# Use remote builder (no Docker needed locally)\nflyte deploy --image-builder remote pipeline.py\n```\n\n### Push image manually\n\n```bash\n# If using a custom registry\ndocker build -t ghcr.io/myorg/my-task:v1 .\ndocker push ghcr.io/myorg/my-task:v1\n```\n\n### Image caching\n\nFlyte caches built images by content hash. If the image source hasn't changed, it reuses the cached image.\n\n## Troubleshooting\n\n| Issue | Fix |\n|---|---|\n| `Docker not found` | Install Docker, or use `builder: remote` in config |\n| `Permission denied` on Docker socket | Add user to `docker` group: `sudo usermod -aG docker $USER` |\n| `Image build failed` | Check Dockerfile syntax, apt package names, pip requirements |\n| `Registry push failed` | Verify registry credentials, network connectivity |\n| `CUDA not found in container` | Use `nvidia/cuda` base image or install CUDA toolkit in Dockerfile |\n| `pip install fails for torch` | Use the correct CUDA index: `--extra-index-url https://download.pytorch.org/whl/cu121` |\n| `Image too large` | Use slim base images, multi-stage builds, `.dockerignore` |\n\n## Anti-Patterns\n\n1. **Don't bake secrets into images** — use Flyte secrets instead (`flyte.Secret`).\n2. **Don't use `latest` tags in production** — pin to specific versions or git SHAs.\n3. **Don't install unnecessary system packages** — they increase image size and build time.\n4. **Don't forget `.dockerignore`** — exclude `.git`, `__pycache__`, `.venv`, etc.\n5. **Don't use Union-only features** — avoid `ReusePolicy` and other Union-specific APIs.\n"
}