{"owner":"ace-step","repo":"ACE-Step-1.5","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md",".github/copilot-instructions.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\nGuidance for AI coding agents working in `ace-step/ACE-Step-1.5`.\n\nThis document is aligned with the intent from:\n- Discussion #408: functional decomposition to reduce risk from large mixed-responsibility files.\n- Discussion #365: low-risk contribution workflow, minimal scope, and review rigor.\n\n## Primary Objectives\n\n1. Keep changes safe and reviewable.\n2. Prefer small, maintainable, decomposed modules.\n3. Preserve behavior outside the target fix.\n4. Validate with focused Python unit tests.\n\n## Build, Lint, and Test Commands\n\n```bash\n# Install dependencies\nuv sync\n\n# Run all tests (unittest-based, discovery in */*_test.py and test_*.py)\nuv run python -m unittest discover -s . -p \"*_test.py\"\nuv run python -m unittest discover -s . -p \"test_*.py\"\n\n# Run a single test file\nuv run python -m unittest acestep.training.test_lora_utils\n\n# Run a specific test class\nuv run python -m unittest acestep.training.test_lora_utils.TestUnwrapDecoder\n\n# Run a single test method\nuv run python -m unittest acestep.training.test_lora_utils.TestUnwrapDecoder.test_returns_module_directly\n\n# Run all tests in a directory\nuv run python -m unittest discover -s acestep/training -p \"*_test.py\"\n```\n\n## Scope and Change Control (Required)\n\n- Solve one problem per task/PR.\n- Keep edits minimal: touch only files/functions required for the requested change.\n- Do not make drive-by refactors, formatting sweeps, or opportunistic cleanups.\n- Do not alter non-target hardware/runtime paths (CPU/CUDA/MPS/XPU) unless required by the task.\n- If any cross-path change is necessary, isolate it and justify it in the PR notes.\n- Preserve existing public interfaces unless the task explicitly requires an interface change.\n\n## Decomposition and Module Size Policy\n\n- Prefer single-responsibility modules with clear boundaries.\n- Target module size:\n  - Optimal: `<= 150` LOC\n  - Hard cap: `200` LOC\n- Function decomposition rules:\n  - Do one thing at a time; if a function description naturally contains \"and\", split it.\n  - Split by responsibility, not by convenience.\n  - Keep data flow explicit (`data in, data out`); side effects must be obvious and deliberate.\n  - Push decisions up and push work down (orchestration at higher layers, execution details in lower layers).\n  - The call graph should read clearly from top-level orchestration to leaf operations.\n- If a module would exceed `200` LOC:\n  - Split by responsibility before merging, or\n  - Add a short justification in PR notes and include a concrete follow-up split plan.\n- Keep orchestrator/facade modules thin. Move logic into focused helpers/services.\n- Preserve stable facade imports when splitting large files so external callers are not broken.\n\n## Python Unit Testing Expectations\n\n- Add or update tests for every behavior change and bug fix.\n- Match repository conventions:\n  - Use `unittest`-style tests.\n  - Name test files as `*_test.py` or `test_*.py`.\n- Keep tests deterministic, fast, and scoped to changed behavior.\n- Use `unittest.mock.MagicMock` and `unittest.mock.patch` for mocking.\n- Mock GPU, filesystem, network, and external services where possible.\n- If a change requires mocking a large portion of the system to test one unit, treat that as a decomposition smell and refactor boundaries.\n- Include at least:\n  - One success-path test.\n  - One regression/edge-case test for the bug being fixed.\n  - One non-target behavior check when relevant.\n- Run targeted tests locally before submitting.\n\n## Code Style Guidelines\n\n- **Python version**: 3.11-3.12\n- **Indentation**: 4 spaces (no tabs)\n- **Line length**: Maximum 100 characters (recommended). See `pyproject.toml` for configured formatter limits. Exceptions allowed for URLs and long strings where wrapping would hurt readability.\n- **Strings**: Double quotes `\"` preferred\n- **Imports**: Group by type (stdlib, third-party, local), sort alphabetically within groups\n\n```python\n# Example import ordering\nimport os\nimport tempfile\nfrom pathlib import Path\nfrom typing import Any\nfrom unittest.mock import MagicMock, patch\n\nimport torch\nimport torch.nn as nn\n\nfrom acestep.training.lora_injection import inject_lora_into_dit\n```\n\n**Naming conventions**:\n- `snake_case` for functions, variables, and module names\n- `PascalCase` for classes\n- `UPPER_SNAKE_CASE` for constants\n- Prefix private/internal names with underscore: `_internal_func`, `_private_var`\n\n**Type hints**: Add type annotations for new/modified functions when practical.\n\n**Docstrings**: Mandatory for all modules, classes, and public functions. Use concise format:\n\n```python\ndef inject_lora_into_dit(\n    dit: nn.Module,\n    config: dict[str, Any],\n    target_modules: list[str],\n) -> nn.Module:\n    \"\"\"Inject LoRA adapters into DiT model for parameter-efficient fine-tuning.\n\n    Args:\n        dit: The Diffusion Transformer model to modify.\n        config: LoRA configuration dictionary.\n        target_modules: List of module names to apply LoRA to.\n\n    Returns:\n        The modified DiT model with LoRA adapters injected.\n    \"\"\"\n```\n\n**Error handling**:\n- Avoid bare `except:` clauses; catch specific exceptions\n- Use custom exceptions for domain errors\n- Log errors with `loguru.logger` (not `print()`)\n- Let exceptions propagate for truly exceptional conditions\n\n**Logging**:\n- Use `from loguru import logger` and `logger.info()`, `logger.error()`, etc.\n- Keep logs actionable and debug-level for development\n- Avoid `print()` in committed code except CLI output\n\n**Multi-platform support** (CUDA, ROCm, Intel XPU, MPS, MLX, CPU):\n- Use `gpu_config.py` for hardware detection\n- Do not alter non-target platform paths unless explicitly required\n- Changes to CUDA code should not break MPS/XPU/CPU paths\n\n## Feature Gating and WIP Safety\n\n- Do not expose unfinished or non-functional user-facing flows by default.\n- Gate WIP or unstable UI/API paths behind explicit feature/release flags.\n- Keep default behavior stable; \"coming soon\" paths must not appear as usable functionality unless they are operational and tested.\n\n## Python Coding Best Practices\n\n- Use explicit, readable code over clever shortcuts.\n- Docstrings are mandatory for all new or modified Python modules, classes, and functions.\n- Docstrings must be concise and include purpose plus key inputs/outputs (and raised exceptions when relevant).\n- Add type hints for new/modified functions when practical.\n- Keep functions focused and short; extract helpers instead of nesting complexity.\n- Use clear names that describe behavior, not implementation trivia.\n- Prefer pure functions for logic-heavy paths where possible.\n- Avoid duplicated logic, but do not introduce broad abstractions too early; prefer simple local duplication over unstable premature abstraction.\n- Handle errors explicitly; avoid bare `except`.\n- Keep logging actionable; avoid noisy logs and `print` debugging in committed code.\n- Avoid hidden state and unintended side effects.\n- Write comments only where intent is non-obvious; keep comments concise and technical.\n\n## AI-Agent Workflow (Recommended)\n\n1. Understand the task and define explicit in-scope/out-of-scope boundaries.\n2. Propose a minimal patch plan before editing.\n3. Implement the smallest viable change.\n4. Add/update focused tests.\n5. Self-review only changed hunks for regressions and scope creep.\n6. Summarize risk, validation, and non-target impact in PR notes.\n\n## PR Readiness Checklist\n\n- [ ] Change is tightly scoped to one problem.\n- [ ] Non-target paths are unchanged, or changes are explicitly justified.\n- [ ] New/updated tests cover changed behavior and edge cases.\n- [ ] No unrelated refactor/formatting churn.\n- [ ] Required docstrings are present for all new/modified modules, classes, and functions.\n- [ ] WIP/unstable functionality is feature-flagged and not exposed as default-ready behavior.\n- [ ] Module LOC policy is met (`<=150` target, `<=200` hard cap or justified exception).\n",".github/copilot-instructions.md":"# ACE-Step 1.5 - GitHub Copilot Instructions\n\n## Project Overview\n\nACE-Step 1.5 is an open-source music foundation model combining a Language Model (LM) as a planner with a Diffusion Transformer (DiT) for audio synthesis. It generates commercial-grade music on consumer hardware (< 4GB VRAM).\n\n## Tech Stack\n\n- **Python 3.11-3.12** (ROCm on Windows requires 3.12; other platforms use 3.11)\n- **PyTorch 2.7+** with CUDA 12.8 (Windows/Linux), MPS (macOS ARM64)\n- **Transformers 4.51.0-4.57.x** for LLM inference\n- **Diffusers** for diffusion models\n- **Gradio 6.2.0** for web UI\n- **FastAPI + Uvicorn** for REST API server\n- **uv** for dependency management\n- **MLX** (Apple Silicon native acceleration, macOS ARM64)\n- **nano-vllm** (optimized LLM inference, non-macOS ARM64)\n\n## Multi-Platform Support\n\n**CRITICAL**: Supports CUDA, ROCm, Intel XPU, MPS, MLX, and CPU. When fixing bugs or adding features:\n- **DO NOT alter non-target platform paths** unless explicitly required\n- Changes to CUDA code should not affect MPS/XPU/CPU paths\n- Use `gpu_config.py` for hardware detection and configuration\n\n## Code Organization\n\n### Main Entry Points\n- `acestep/acestep_v15_pipeline.py` - Gradio UI pipeline\n- `acestep/api_server.py` - REST API server\n- `cli.py` - Command-line interface\n- `acestep/model_downloader.py` - Model downloader\n\n### Core Modules\n- `acestep/handler.py` - Audio generation handler (AceStepHandler)\n- `acestep/llm_inference.py` - LLM handler for text processing\n- `acestep/inference.py` - Generation logic and parameters\n- `acestep/gpu_config.py` - Hardware detection and GPU configuration\n- `acestep/audio_utils.py` - Audio processing utilities\n- `acestep/constants.py` - Global constants\n\n### UI & Internationalization\n- `acestep/gradio_ui/` - Gradio interface components\n- `acestep/gradio_ui/i18n.py` - i18n system (50+ languages)\n- All user-facing strings must use i18n translation keys\n\n### Training\n- `acestep/training/` - LoRA training pipeline\n- `acestep/dataset/` - Dataset handling\n\n## Key Conventions\n\n- **Python style**: PEP 8, 4 spaces, double quotes for strings\n- **Naming**: `snake_case` functions/variables, `PascalCase` classes, `UPPER_SNAKE_CASE` constants\n- **Logging**: Use `loguru` logger (not `print()` except CLI output)\n- **Dependencies**: Use `uv add <package>` to add to `pyproject.toml`\n\n## Performance\n\n- Target: 4GB VRAM - minimize memory allocations\n- Lazy load models when needed\n- Batch operations supported (up to 8 songs)\n\n## Additional Resources\n\n- **AGENTS.md**: Detailed guidance for AI coding agents\n- **CONTRIBUTING.md**: Contribution workflow and guidelines\n"},"files":{"AGENTS.md":"# AGENTS.md\n\nGuidance for AI coding agents working in `ace-step/ACE-Step-1.5`.\n\nThis document is aligned with the intent from:\n- Discussion #408: functional decomposition to reduce risk from large mixed-responsibility files.\n- Discussion #365: low-risk contribution workflow, minimal scope, and review rigor.\n\n## Primary Objectives\n\n1. Keep changes safe and reviewable.\n2. Prefer small, maintainable, decomposed modules.\n3. Preserve behavior outside the target fix.\n4. Validate with focused Python unit tests.\n\n## Build, Lint, and Test Commands\n\n```bash\n# Install dependencies\nuv sync\n\n# Run all tests (unittest-based, discovery in */*_test.py and test_*.py)\nuv run python -m unittest discover -s . -p \"*_test.py\"\nuv run python -m unittest discover -s . -p \"test_*.py\"\n\n# Run a single test file\nuv run python -m unittest acestep.training.test_lora_utils\n\n# Run a specific test class\nuv run python -m unittest acestep.training.test_lora_utils.TestUnwrapDecoder\n\n# Run a single test method\nuv run python -m unittest acestep.training.test_lora_utils.TestUnwrapDecoder.test_returns_module_directly\n\n# Run all tests in a directory\nuv run python -m unittest discover -s acestep/training -p \"*_test.py\"\n```\n\n## Scope and Change Control (Required)\n\n- Solve one problem per task/PR.\n- Keep edits minimal: touch only files/functions required for the requested change.\n- Do not make drive-by refactors, formatting sweeps, or opportunistic cleanups.\n- Do not alter non-target hardware/runtime paths (CPU/CUDA/MPS/XPU) unless required by the task.\n- If any cross-path change is necessary, isolate it and justify it in the PR notes.\n- Preserve existing public interfaces unless the task explicitly requires an interface change.\n\n## Decomposition and Module Size Policy\n\n- Prefer single-responsibility modules with clear boundaries.\n- Target module size:\n  - Optimal: `<= 150` LOC\n  - Hard cap: `200` LOC\n- Function decomposition rules:\n  - Do one thing at a time; if a function description naturally contains \"and\", split it.\n  - Split by responsibility, not by convenience.\n  - Keep data flow explicit (`data in, data out`); side effects must be obvious and deliberate.\n  - Push decisions up and push work down (orchestration at higher layers, execution details in lower layers).\n  - The call graph should read clearly from top-level orchestration to leaf operations.\n- If a module would exceed `200` LOC:\n  - Split by responsibility before merging, or\n  - Add a short justification in PR notes and include a concrete follow-up split plan.\n- Keep orchestrator/facade modules thin. Move logic into focused helpers/services.\n- Preserve stable facade imports when splitting large files so external callers are not broken.\n\n## Python Unit Testing Expectations\n\n- Add or update tests for every behavior change and bug fix.\n- Match repository conventions:\n  - Use `unittest`-style tests.\n  - Name test files as `*_test.py` or `test_*.py`.\n- Keep tests deterministic, fast, and scoped to changed behavior.\n- Use `unittest.mock.MagicMock` and `unittest.mock.patch` for mocking.\n- Mock GPU, filesystem, network, and external services where possible.\n- If a change requires mocking a large portion of the system to test one unit, treat that as a decomposition smell and refactor boundaries.\n- Include at least:\n  - One success-path test.\n  - One regression/edge-case test for the bug being fixed.\n  - One non-target behavior check when relevant.\n- Run targeted tests locally before submitting.\n\n## Code Style Guidelines\n\n- **Python version**: 3.11-3.12\n- **Indentation**: 4 spaces (no tabs)\n- **Line length**: Maximum 100 characters (recommended). See `pyproject.toml` for configured formatter limits. Exceptions allowed for URLs and long strings where wrapping would hurt readability.\n- **Strings**: Double quotes `\"` preferred\n- **Imports**: Group by type (stdlib, third-party, local), sort alphabetically within groups\n\n```python\n# Example import ordering\nimport os\nimport tempfile\nfrom pathlib import Path\nfrom typing import Any\nfrom unittest.mock import MagicMock, patch\n\nimport torch\nimport torch.nn as nn\n\nfrom acestep.training.lora_injection import inject_lora_into_dit\n```\n\n**Naming conventions**:\n- `snake_case` for functions, variables, and module names\n- `PascalCase` for classes\n- `UPPER_SNAKE_CASE` for constants\n- Prefix private/internal names with underscore: `_internal_func`, `_private_var`\n\n**Type hints**: Add type annotations for new/modified functions when practical.\n\n**Docstrings**: Mandatory for all modules, classes, and public functions. Use concise format:\n\n```python\ndef inject_lora_into_dit(\n    dit: nn.Module,\n    config: dict[str, Any],\n    target_modules: list[str],\n) -> nn.Module:\n    \"\"\"Inject LoRA adapters into DiT model for parameter-efficient fine-tuning.\n\n    Args:\n        dit: The Diffusion Transformer model to modify.\n        config: LoRA configuration dictionary.\n        target_modules: List of module names to apply LoRA to.\n\n    Returns:\n        The modified DiT model with LoRA adapters injected.\n    \"\"\"\n```\n\n**Error handling**:\n- Avoid bare `except:` clauses; catch specific exceptions\n- Use custom exceptions for domain errors\n- Log errors with `loguru.logger` (not `print()`)\n- Let exceptions propagate for truly exceptional conditions\n\n**Logging**:\n- Use `from loguru import logger` and `logger.info()`, `logger.error()`, etc.\n- Keep logs actionable and debug-level for development\n- Avoid `print()` in committed code except CLI output\n\n**Multi-platform support** (CUDA, ROCm, Intel XPU, MPS, MLX, CPU):\n- Use `gpu_config.py` for hardware detection\n- Do not alter non-target platform paths unless explicitly required\n- Changes to CUDA code should not break MPS/XPU/CPU paths\n\n## Feature Gating and WIP Safety\n\n- Do not expose unfinished or non-functional user-facing flows by default.\n- Gate WIP or unstable UI/API paths behind explicit feature/release flags.\n- Keep default behavior stable; \"coming soon\" paths must not appear as usable functionality unless they are operational and tested.\n\n## Python Coding Best Practices\n\n- Use explicit, readable code over clever shortcuts.\n- Docstrings are mandatory for all new or modified Python modules, classes, and functions.\n- Docstrings must be concise and include purpose plus key inputs/outputs (and raised exceptions when relevant).\n- Add type hints for new/modified functions when practical.\n- Keep functions focused and short; extract helpers instead of nesting complexity.\n- Use clear names that describe behavior, not implementation trivia.\n- Prefer pure functions for logic-heavy paths where possible.\n- Avoid duplicated logic, but do not introduce broad abstractions too early; prefer simple local duplication over unstable premature abstraction.\n- Handle errors explicitly; avoid bare `except`.\n- Keep logging actionable; avoid noisy logs and `print` debugging in committed code.\n- Avoid hidden state and unintended side effects.\n- Write comments only where intent is non-obvious; keep comments concise and technical.\n\n## AI-Agent Workflow (Recommended)\n\n1. Understand the task and define explicit in-scope/out-of-scope boundaries.\n2. Propose a minimal patch plan before editing.\n3. Implement the smallest viable change.\n4. Add/update focused tests.\n5. Self-review only changed hunks for regressions and scope creep.\n6. Summarize risk, validation, and non-target impact in PR notes.\n\n## PR Readiness Checklist\n\n- [ ] Change is tightly scoped to one problem.\n- [ ] Non-target paths are unchanged, or changes are explicitly justified.\n- [ ] New/updated tests cover changed behavior and edge cases.\n- [ ] No unrelated refactor/formatting churn.\n- [ ] Required docstrings are present for all new/modified modules, classes, and functions.\n- [ ] WIP/unstable functionality is feature-flagged and not exposed as default-ready behavior.\n- [ ] Module LOC policy is met (`<=150` target, `<=200` hard cap or justified exception).\n",".github/copilot-instructions.md":"# ACE-Step 1.5 - GitHub Copilot Instructions\n\n## Project Overview\n\nACE-Step 1.5 is an open-source music foundation model combining a Language Model (LM) as a planner with a Diffusion Transformer (DiT) for audio synthesis. It generates commercial-grade music on consumer hardware (< 4GB VRAM).\n\n## Tech Stack\n\n- **Python 3.11-3.12** (ROCm on Windows requires 3.12; other platforms use 3.11)\n- **PyTorch 2.7+** with CUDA 12.8 (Windows/Linux), MPS (macOS ARM64)\n- **Transformers 4.51.0-4.57.x** for LLM inference\n- **Diffusers** for diffusion models\n- **Gradio 6.2.0** for web UI\n- **FastAPI + Uvicorn** for REST API server\n- **uv** for dependency management\n- **MLX** (Apple Silicon native acceleration, macOS ARM64)\n- **nano-vllm** (optimized LLM inference, non-macOS ARM64)\n\n## Multi-Platform Support\n\n**CRITICAL**: Supports CUDA, ROCm, Intel XPU, MPS, MLX, and CPU. When fixing bugs or adding features:\n- **DO NOT alter non-target platform paths** unless explicitly required\n- Changes to CUDA code should not affect MPS/XPU/CPU paths\n- Use `gpu_config.py` for hardware detection and configuration\n\n## Code Organization\n\n### Main Entry Points\n- `acestep/acestep_v15_pipeline.py` - Gradio UI pipeline\n- `acestep/api_server.py` - REST API server\n- `cli.py` - Command-line interface\n- `acestep/model_downloader.py` - Model downloader\n\n### Core Modules\n- `acestep/handler.py` - Audio generation handler (AceStepHandler)\n- `acestep/llm_inference.py` - LLM handler for text processing\n- `acestep/inference.py` - Generation logic and parameters\n- `acestep/gpu_config.py` - Hardware detection and GPU configuration\n- `acestep/audio_utils.py` - Audio processing utilities\n- `acestep/constants.py` - Global constants\n\n### UI & Internationalization\n- `acestep/gradio_ui/` - Gradio interface components\n- `acestep/gradio_ui/i18n.py` - i18n system (50+ languages)\n- All user-facing strings must use i18n translation keys\n\n### Training\n- `acestep/training/` - LoRA training pipeline\n- `acestep/dataset/` - Dataset handling\n\n## Key Conventions\n\n- **Python style**: PEP 8, 4 spaces, double quotes for strings\n- **Naming**: `snake_case` functions/variables, `PascalCase` classes, `UPPER_SNAKE_CASE` constants\n- **Logging**: Use `loguru` logger (not `print()` except CLI output)\n- **Dependencies**: Use `uv add <package>` to add to `pyproject.toml`\n\n## Performance\n\n- Target: 4GB VRAM - minimize memory allocations\n- Lazy load models when needed\n- Batch operations supported (up to 8 songs)\n\n## Additional Resources\n\n- **AGENTS.md**: Detailed guidance for AI coding agents\n- **CONTRIBUTING.md**: Contribution workflow and guidelines\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\nGuidance for AI coding agents working in `ace-step/ACE-Step-1.5`.\n\nThis document is aligned with the intent from:\n- Discussion #408: functional decomposition to reduce risk from large mixed-responsibility files.\n- Discussion #365: low-risk contribution workflow, minimal scope, and review rigor.\n\n## Primary Objectives\n\n1. Keep changes safe and reviewable.\n2. Prefer small, maintainable, decomposed modules.\n3. Preserve behavior outside the target fix.\n4. Validate with focused Python unit tests.\n\n## Build, Lint, and Test Commands\n\n```bash\n# Install dependencies\nuv sync\n\n# Run all tests (unittest-based, discovery in */*_test.py and test_*.py)\nuv run python -m unittest discover -s . -p \"*_test.py\"\nuv run python -m unittest discover -s . -p \"test_*.py\"\n\n# Run a single test file\nuv run python -m unittest acestep.training.test_lora_utils\n\n# Run a specific test class\nuv run python -m unittest acestep.training.test_lora_utils.TestUnwrapDecoder\n\n# Run a single test method\nuv run python -m unittest acestep.training.test_lora_utils.TestUnwrapDecoder.test_returns_module_directly\n\n# Run all tests in a directory\nuv run python -m unittest discover -s acestep/training -p \"*_test.py\"\n```\n\n## Scope and Change Control (Required)\n\n- Solve one problem per task/PR.\n- Keep edits minimal: touch only files/functions required for the requested change.\n- Do not make drive-by refactors, formatting sweeps, or opportunistic cleanups.\n- Do not alter non-target hardware/runtime paths (CPU/CUDA/MPS/XPU) unless required by the task.\n- If any cross-path change is necessary, isolate it and justify it in the PR notes.\n- Preserve existing public interfaces unless the task explicitly requires an interface change.\n\n## Decomposition and Module Size Policy\n\n- Prefer single-responsibility modules with clear boundaries.\n- Target module size:\n  - Optimal: `<= 150` LOC\n  - Hard cap: `200` LOC\n- Function decomposition rules:\n  - Do one thing at a time; if a function description naturally contains \"and\", split it.\n  - Split by responsibility, not by convenience.\n  - Keep data flow explicit (`data in, data out`); side effects must be obvious and deliberate.\n  - Push decisions up and push work down (orchestration at higher layers, execution details in lower layers).\n  - The call graph should read clearly from top-level orchestration to leaf operations.\n- If a module would exceed `200` LOC:\n  - Split by responsibility before merging, or\n  - Add a short justification in PR notes and include a concrete follow-up split plan.\n- Keep orchestrator/facade modules thin. Move logic into focused helpers/services.\n- Preserve stable facade imports when splitting large files so external callers are not broken.\n\n## Python Unit Testing Expectations\n\n- Add or update tests for every behavior change and bug fix.\n- Match repository conventions:\n  - Use `unittest`-style tests.\n  - Name test files as `*_test.py` or `test_*.py`.\n- Keep tests deterministic, fast, and scoped to changed behavior.\n- Use `unittest.mock.MagicMock` and `unittest.mock.patch` for mocking.\n- Mock GPU, filesystem, network, and external services where possible.\n- If a change requires mocking a large portion of the system to test one unit, treat that as a decomposition smell and refactor boundaries.\n- Include at least:\n  - One success-path test.\n  - One regression/edge-case test for the bug being fixed.\n  - One non-target behavior check when relevant.\n- Run targeted tests locally before submitting.\n\n## Code Style Guidelines\n\n- **Python version**: 3.11-3.12\n- **Indentation**: 4 spaces (no tabs)\n- **Line length**: Maximum 100 characters (recommended). See `pyproject.toml` for configured formatter limits. Exceptions allowed for URLs and long strings where wrapping would hurt readability.\n- **Strings**: Double quotes `\"` preferred\n- **Imports**: Group by type (stdlib, third-party, local), sort alphabetically within groups\n\n```python\n# Example import ordering\nimport os\nimport tempfile\nfrom pathlib import Path\nfrom typing import Any\nfrom unittest.mock import MagicMock, patch\n\nimport torch\nimport torch.nn as nn\n\nfrom acestep.training.lora_injection import inject_lora_into_dit\n```\n\n**Naming conventions**:\n- `snake_case` for functions, variables, and module names\n- `PascalCase` for classes\n- `UPPER_SNAKE_CASE` for constants\n- Prefix private/internal names with underscore: `_internal_func`, `_private_var`\n\n**Type hints**: Add type annotations for new/modified functions when practical.\n\n**Docstrings**: Mandatory for all modules, classes, and public functions. Use concise format:\n\n```python\ndef inject_lora_into_dit(\n    dit: nn.Module,\n    config: dict[str, Any],\n    target_modules: list[str],\n) -> nn.Module:\n    \"\"\"Inject LoRA adapters into DiT model for parameter-efficient fine-tuning.\n\n    Args:\n        dit: The Diffusion Transformer model to modify.\n        config: LoRA configuration dictionary.\n        target_modules: List of module names to apply LoRA to.\n\n    Returns:\n        The modified DiT model with LoRA adapters injected.\n    \"\"\"\n```\n\n**Error handling**:\n- Avoid bare `except:` clauses; catch specific exceptions\n- Use custom exceptions for domain errors\n- Log errors with `loguru.logger` (not `print()`)\n- Let exceptions propagate for truly exceptional conditions\n\n**Logging**:\n- Use `from loguru import logger` and `logger.info()`, `logger.error()`, etc.\n- Keep logs actionable and debug-level for development\n- Avoid `print()` in committed code except CLI output\n\n**Multi-platform support** (CUDA, ROCm, Intel XPU, MPS, MLX, CPU):\n- Use `gpu_config.py` for hardware detection\n- Do not alter non-target platform paths unless explicitly required\n- Changes to CUDA code should not break MPS/XPU/CPU paths\n\n## Feature Gating and WIP Safety\n\n- Do not expose unfinished or non-functional user-facing flows by default.\n- Gate WIP or unstable UI/API paths behind explicit feature/release flags.\n- Keep default behavior stable; \"coming soon\" paths must not appear as usable functionality unless they are operational and tested.\n\n## Python Coding Best Practices\n\n- Use explicit, readable code over clever shortcuts.\n- Docstrings are mandatory for all new or modified Python modules, classes, and functions.\n- Docstrings must be concise and include purpose plus key inputs/outputs (and raised exceptions when relevant).\n- Add type hints for new/modified functions when practical.\n- Keep functions focused and short; extract helpers instead of nesting complexity.\n- Use clear names that describe behavior, not implementation trivia.\n- Prefer pure functions for logic-heavy paths where possible.\n- Avoid duplicated logic, but do not introduce broad abstractions too early; prefer simple local duplication over unstable premature abstraction.\n- Handle errors explicitly; avoid bare `except`.\n- Keep logging actionable; avoid noisy logs and `print` debugging in committed code.\n- Avoid hidden state and unintended side effects.\n- Write comments only where intent is non-obvious; keep comments concise and technical.\n\n## AI-Agent Workflow (Recommended)\n\n1. Understand the task and define explicit in-scope/out-of-scope boundaries.\n2. Propose a minimal patch plan before editing.\n3. Implement the smallest viable change.\n4. Add/update focused tests.\n5. Self-review only changed hunks for regressions and scope creep.\n6. Summarize risk, validation, and non-target impact in PR notes.\n\n## PR Readiness Checklist\n\n- [ ] Change is tightly scoped to one problem.\n- [ ] Non-target paths are unchanged, or changes are explicitly justified.\n- [ ] New/updated tests cover changed behavior and edge cases.\n- [ ] No unrelated refactor/formatting churn.\n- [ ] Required docstrings are present for all new/modified modules, classes, and functions.\n- [ ] WIP/unstable functionality is feature-flagged and not exposed as default-ready behavior.\n- [ ] Module LOC policy is met (`<=150` target, `<=200` hard cap or justified exception).\n","category":"root","tokens":1977},{"name":"copilot-instructions.md","path":".github/copilot-instructions.md","title":"copilot-instructions.md","content":"# ACE-Step 1.5 - GitHub Copilot Instructions\n\n## Project Overview\n\nACE-Step 1.5 is an open-source music foundation model combining a Language Model (LM) as a planner with a Diffusion Transformer (DiT) for audio synthesis. It generates commercial-grade music on consumer hardware (< 4GB VRAM).\n\n## Tech Stack\n\n- **Python 3.11-3.12** (ROCm on Windows requires 3.12; other platforms use 3.11)\n- **PyTorch 2.7+** with CUDA 12.8 (Windows/Linux), MPS (macOS ARM64)\n- **Transformers 4.51.0-4.57.x** for LLM inference\n- **Diffusers** for diffusion models\n- **Gradio 6.2.0** for web UI\n- **FastAPI + Uvicorn** for REST API server\n- **uv** for dependency management\n- **MLX** (Apple Silicon native acceleration, macOS ARM64)\n- **nano-vllm** (optimized LLM inference, non-macOS ARM64)\n\n## Multi-Platform Support\n\n**CRITICAL**: Supports CUDA, ROCm, Intel XPU, MPS, MLX, and CPU. When fixing bugs or adding features:\n- **DO NOT alter non-target platform paths** unless explicitly required\n- Changes to CUDA code should not affect MPS/XPU/CPU paths\n- Use `gpu_config.py` for hardware detection and configuration\n\n## Code Organization\n\n### Main Entry Points\n- `acestep/acestep_v15_pipeline.py` - Gradio UI pipeline\n- `acestep/api_server.py` - REST API server\n- `cli.py` - Command-line interface\n- `acestep/model_downloader.py` - Model downloader\n\n### Core Modules\n- `acestep/handler.py` - Audio generation handler (AceStepHandler)\n- `acestep/llm_inference.py` - LLM handler for text processing\n- `acestep/inference.py` - Generation logic and parameters\n- `acestep/gpu_config.py` - Hardware detection and GPU configuration\n- `acestep/audio_utils.py` - Audio processing utilities\n- `acestep/constants.py` - Global constants\n\n### UI & Internationalization\n- `acestep/gradio_ui/` - Gradio interface components\n- `acestep/gradio_ui/i18n.py` - i18n system (50+ languages)\n- All user-facing strings must use i18n translation keys\n\n### Training\n- `acestep/training/` - LoRA training pipeline\n- `acestep/dataset/` - Dataset handling\n\n## Key Conventions\n\n- **Python style**: PEP 8, 4 spaces, double quotes for strings\n- **Naming**: `snake_case` functions/variables, `PascalCase` classes, `UPPER_SNAKE_CASE` constants\n- **Logging**: Use `loguru` logger (not `print()` except CLI output)\n- **Dependencies**: Use `uv add <package>` to add to `pyproject.toml`\n\n## Performance\n\n- Target: 4GB VRAM - minimize memory allocations\n- Lazy load models when needed\n- Batch operations supported (up to 8 songs)\n\n## Additional Resources\n\n- **AGENTS.md**: Detailed guidance for AI coding agents\n- **CONTRIBUTING.md**: Contribution workflow and guidelines\n","category":".github","tokens":654}]}