# =============================================================================
# GCA environment variables — external provider setup
# =============================================================================
#
# Quick start
# -----------
# 1. From the repository root:
#      cp .env.example .env
# 2. Replace every uncommented <placeholder>. Never commit `.env`.
# 3. Keep the pinned Doubao 2.0 model identity and choose one RMBG strategy.
# 4. Run the preflight commands at the end of this file.
# 5. Restart the MCP process after changing `.env`.
#
# Already-exported process variables take precedence over values in `.env`.
# Use one KEY=value assignment per line; `${OTHER_VAR}` interpolation is not
# supported. Outer single/double quotes are removed.
# =============================================================================


# =============================================================================
# 1. OpenAI Images API — `generate_image` and `edit_image`
# =============================================================================
#
# The key must be allowed to use the selected image model. Do not include
# `Bearer `; the client adds the Authorization scheme. GAME_ASSET_BASE_URL is
# the API root; GCA appends `/images/generations` or `/images/edits`.
OPENAI_API_KEY=<your_openai_api_key>
GAME_ASSET_BASE_URL=https://api.openai.com/v1
GAME_ASSET_MODEL=gpt-image-2


# =============================================================================
# 2. Volcengine ARK — Seedance video generation
# =============================================================================
#
# ARK_API_KEY is used for both Seedance and Doubao VLM requests. Do not include
# `Bearer `. SEEDANCE_URL is the async task-collection endpoint; GCA POSTs here
# and polls `<SEEDANCE_URL>/<task_id>`.
ARK_API_KEY=<your_ark_api_key>
SEEDANCE_URL=https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks
SEEDANCE_MODEL_STANDARD=doubao-seedance-2-0-260128
SEEDANCE_MODEL_FAST=doubao-seedance-2-0-fast-260128

# Optional transport tuning. Defaults are shown.
# SEEDANCE_VERIFY_SSL=true
# SEEDANCE_POLL_INTERVAL=10.0


# =============================================================================
# 3. VLM validation — pinned Doubao 2.0 through ARK
# =============================================================================
#
# The model identity is pinned in code. DOUBAO_MODEL is listed for operational
# clarity, but changing it does not override the runtime policy.
DOUBAO_API_ENDPOINT=https://ark.cn-beijing.volces.com/api/v3/chat/completions
DOUBAO_MODEL=doubao-seed-2-0-pro-260215
VLM_ATTEMPTS_PER_MODEL=1

# Backoff values remain for configuration compatibility but are unused by the
# single-attempt policy.
# VLM_BACKOFF_SECONDS=2.0
# VLM_RATE_LIMIT_BACKOFF_SECONDS=10.0


# =============================================================================
# 4. Background removal — model-free color-key by default
# =============================================================================
#
# Nothing in this section is required. Matting defaults to the model-free
# `color_key` backend, which needs no credentials, no service, and no model.
#
# Backend selection is configured in `gca.config.yaml`:
#
#   assets:
#     matting:
#       backend: color_key
#
# Supported policies:
#   color_key DEFAULT. Remove the generated safe background color locally.
#             Pure computation — no model, no API, nothing downloaded.
#   auto      Prefer RMBG; use deterministic color-key matting after eligible
#             network, missing-route HTTP 404, or HTTP 5xx failures.
#   rmbg2     Require RMBG and fail if it is unavailable.
#
# `auto` and `rmbg2` load RMBG-2.0, which is licensed under CC BY-NC 4.0 and
# prohibits commercial use. GCA neither ships nor enables it by default;
# selecting either value is an explicit opt-in, and obtaining the model and
# complying with its license is your responsibility.
#
# The variables below are only read once you opt in. RMBG_BASE_URL is a full
# endpoint for a separately deployed service; leave it empty to matte in-process
# (requires the `local-rmbg` extra).
RMBG_BASE_URL=
# HF_TOKEN=<your_huggingface_token>


# =============================================================================
# 5. Install and preflight
# =============================================================================
#
# From the repository root:
#
#   cd gca-mcp
#   uv sync --extra dev
#   cd ..
#   gca-mcp/.venv/bin/python scripts/preflight_env.py
#
# If using local in-process RMBG:
#
#   cd gca-mcp
#   uv sync --extra dev --extra local-rmbg
#   cd ..
#
# Verify that the MCP executable starts and publishes its tools:
#
#   cd gca-mcp
#   uv run gca-mcp <<< '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
#
# Common failures
# ---------------
#   MISSING_CREDENTIALS / HTTP 401 / HTTP 403
#     Check OPENAI_API_KEY, ARK_API_KEY, model access, and quota.
#
#   IMAGE_GEN_FAILED
#     Check GAME_ASSET_BASE_URL, GAME_ASSET_MODEL, quota, and model access.
#
#   SEEDANCE_FAILED / SEEDANCE_TIMEOUT
#     Check ARK model IDs, the task endpoint, quota, and request timeout.
#
#   VLM_CALL_FAILED
#     Check DOUBAO_API_ENDPOINT, ARK credentials, model access, and response.
#
#   RMBG2_FAILED with HTTP 404 / 5xx
#     Under `backend: auto`, color-key may be used; under `rmbg2`, restore the
#     service or change the configured policy.
# =============================================================================