crewai-suno 0.1.0__tar.gz

crewai_suno-0.1.0/.env.example

@@ -0,0 +1 @@
+ACEDATACLOUD_API_KEY=your_api_consumer_token

crewai_suno-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,24 @@
+name: Test and build
+on:
+  push:
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ['3.10', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --group dev
+      - run: uv run pytest
+      - run: uv run ruff check .
+      - run: uv build
+      - name: Install built wheel in a clean environment
+        run: |
+          uv venv /tmp/suno-wheel --python ${{ matrix.python }}
+          uv pip install --python /tmp/suno-wheel/bin/python dist/crewai_suno-0.1.0-py3-none-any.whl
+          /tmp/suno-wheel/bin/python -c 'from suno_crewai import SunoGenerateMusicTool, SunoRetrieveTaskTool; t = SunoRetrieveTaskTool(api_key="fixture"); assert "fixture" not in str(t.model_dump()); assert "task_id" in t.args_schema.model_fields; print("clean wheel import and schema passed")'

crewai_suno-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.env
+.env.*
+!/.env.example

crewai_suno-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ace Data Cloud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

crewai_suno-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.5
+Name: crewai-suno
+Version: 0.1.0
+Summary: Suno by Ace Data Cloud: native CrewAI music generation and same-task retrieval tools
+Project-URL: Homepage, https://github.com/AceDataCloud/SunoCrewAI
+Project-URL: Repository, https://github.com/AceDataCloud/SunoCrewAI
+Project-URL: Documentation, https://github.com/AceDataCloud/SunoCrewAI#readme
+Project-URL: Issues, https://github.com/AceDataCloud/SunoCrewAI/issues
+Author-email: Ace Data Cloud Dev <dev@acedata.cloud>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: acedatacloud,agents,audio,crewai,music,suno
+Requires-Python: <3.14,>=3.10
+Requires-Dist: crewai<2,>=1.15.28
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: pydantic<3,>=2.11
+Description-Content-Type: text/markdown
+
+# Suno by Ace Data Cloud for CrewAI
+
+Generate Suno music and retrieve the same asynchronous task from native CrewAI tools. **Ace Data Cloud provides this integration; it is not an official Suno or CrewAI product.**
+
+[简体中文](https://github.com/AceDataCloud/SunoCrewAI/blob/v0.1.0-preview.1/readme/README_zh_Hans.md) · [Current models and pricing](https://platform.acedata.cloud/models?utm_source=pypi&utm_medium=referral&utm_campaign=evergreen&utm_content=sunocrewai_package_pricing)
+
+## 1. Install the integration
+
+This is the standalone **Suno** package, not an all-services bundle. A [GitHub review preview with wheel and source archive](https://github.com/AceDataCloud/SunoCrewAI/releases/tag/v0.1.0-preview.1) is available; implementation remains under review. **No PyPI release or official CrewAI catalog listing is claimed.** Use the exact source commit below, or the hash-pinned wheel command after it. Do not install an attachment merely by tag name:
+
+```bash
+uv add 'crewai-suno @ git+https://github.com/AceDataCloud/SunoCrewAI.git@e5eeb04661ed7b9a86e1f2f970a9e7943b027ca2'
+```
+
+```bash
+uv add 'crewai-suno @ https://github.com/AceDataCloud/SunoCrewAI/releases/download/v0.1.0-preview.1/crewai_suno-0.1.0-py3-none-any.whl#sha256=d31998ca7f33f54c9603a0acb0d906f25933e858be6c83babc5a6d0e5a478e51'
+```
+
+The wheel was built from the exact source SHA above. Its SHA256 is pinned in the URL; if an asset is replaced, installation must fail the digest check. The release page is informational, not the trust anchor.
+
+The source SHA identifies the reviewed preview; inspect the [implementation PR](https://github.com/AceDataCloud/SunoCrewAI/pull/1) before adoption. After a verified PyPI release, the standard entry will be `uv add crewai-suno`. Do not interpret a repository or built wheel as an official listing. CrewAI currently requires Python 3.10–3.13; on Intel macOS its mandatory `lancedb` dependency may lack a wheel. Use a supported Linux environment rather than skipping dependencies for production.
+
+## 2. Register, sign in and obtain your own Token
+
+1. Open [Ace Data Cloud → Applications](https://platform.acedata.cloud/console/applications?utm_source=pypi&utm_medium=referral&utm_campaign=evergreen&utm_content=sunocrewai_package_api_key). Register or sign in. If needed, choose **Initialize General Application**.
+2. Open **General application**. Check **Suno** access, current price and balance before generating. A service-specific application can only use its allowed service.
+3. Copy the selected API key with the copy icon **1**, or choose **Manage Keys** **2** to create a separate key.
+
+![Copy API Key or open Manage Keys; credentials redacted](https://raw.githubusercontent.com/AceDataCloud/SunoCrewAI/v0.1.0-preview.1/assets/tutorial/get-api-key-en.png)
+
+4. Choose **Create**, name the key `CrewAI Suno`, and configure expiration/restrictions as needed. If **Allowed APIs** is enabled, allow both `/suno/audios` and `/suno/tasks`.
+
+![Create optional dedicated API Key; historical screenshot](https://raw.githubusercontent.com/AceDataCloud/SunoCrewAI/v0.1.0-preview.1/assets/tutorial/create-api-key-en.png)
+
+These redacted screenshots are reused unchanged from the Ace SunoDify tutorial, revision `8d3d03570e73324220f111f7fe343da0792a8071`, retrieved 2026-10-18. The historical name `Dify tutorial` in the second screenshot is only an example; use `CrewAI Suno`. No visible real credential is included. See [image sources](https://raw.githubusercontent.com/AceDataCloud/SunoCrewAI/v0.1.0-preview.1/assets/tutorial/source.json).
+
+Set the raw API-consumer Token in the environment variable `ACEDATACLOUD_API_KEY` using your secret manager or terminal's secure input. Do not prepend `Bearer`, use a platform management Token, put the key in prompts, or commit `.env` files. Tools also accept `api_key=...` when a secure credential store supplies it; it is excluded from serialization.
+
+## 3. Add the named Suno tools to your CrewAI agent
+
+```python
+from crewai import Agent
+from suno_crewai import SunoGenerateMusicTool, SunoRetrieveTaskTool
+
+agent = Agent(
+    role="Music producer",
+    goal="Create the requested music and check its task result",
+    backstory="Use Suno through Ace Data Cloud within the user's approved budget.",
+    llm=your_configured_llm,
+    tools=[SunoGenerateMusicTool(), SunoRetrieveTaskTool()],
+    allow_delegation=False,
+    max_retry_limit=0,
+)
+```
+
+These are actual CrewAI `BaseTool` implementations with input schemas and discoverable names **Suno by Ace Data Cloud - Generate Music** and **Suno by Ace Data Cloud - Retrieve Task**. They need no MCP server configuration. Adding a generation tool does not itself submit a request. The caller is responsible for approving the workflow's paid actions. The generation tool defaults to one use per instance to reduce duplicate submissions; this is not a funds cap or permission system.
+
+## 4. First use: submit once, then query the same ID
+
+First inspect the current [model and price catalog](https://platform.acedata.cloud/models?utm_source=pypi&utm_medium=referral&utm_campaign=evergreen&utm_content=sunocrewai_package_first_use). Select a currently supported Suno model; `chirp-v6` is an example from the current Suno API contract, not a permanent default.
+
+A generation invocation is **billable**. Run it only after agreeing the model and budget:
+
+```python
+import json
+from suno_crewai import SunoGenerateMusicTool, SunoRetrieveTaskTool
+
+# BILLABLE when run; this README does not execute it.
+submitted = json.loads(SunoGenerateMusicTool().run(
+    prompt="A gentle instrumental piano melody for a sunrise, no vocals.",
+    model="chirp-v6",
+    instrumental=True,
+))
+print(submitted["task_id"])
+
+# accepted/pending is not completion. Preserve this same ID.
+result = SunoRetrieveTaskTool().run(task_id=submitted["task_id"], wait_seconds=240)
+print(result)
+```
+
+A pending result looks like `{"status":"pending","success":false,"task_id":"...","media_urls":[]}`. Do not rerun the generation if pending, timeout or an unknown submission outcome occurs. Query the same ID again. A terminal successful result includes `status=succeeded`, `success=true`, audio URLs and the original `cost`, when returned by the service. Costs are Credits; they are not USD. A link's presence does not verify that it remains playable.
+
+For an existing task, run only this **read-only** example:
+
+```bash
+uv run python examples/query_existing.py YOUR_EXISTING_TASK_ID
+```
+
+The ID must belong to your Key. The published payloads are `/suno/audios` with `async=true` and `/suno/tasks` with `action=retrieve,id=...`; model IDs pass through unchanged. No substitute model or automatic paid HTTP retry is added. Bounded polling only queries the same task.
+
+## 5. Inspect execution and output
+
+![Official historical CrewAI execution trace, not Ace runtime evidence](https://raw.githubusercontent.com/AceDataCloud/SunoCrewAI/v0.1.0-preview.1/assets/tutorial/official-crewai-tracing.png)
+
+Official CrewAI reference, downloaded 2026-10-18 from its tracing documentation. The screenshot's historical date marker is `10/1/2025`; its capture version is unspecified. It shows a task timeline and Response output, **not this Suno tool running**, not an Ace result, and not a new GUI promised by this package. Inputs are not expanded in this image. For your own run, inspect the named Suno tool event and its returned task status. See [official tracing guide](https://docs.crewai.com/en/observability/tracing) for optional account/authentication requirements; tracing is not enabled by this package.
+
+## Troubleshooting and cost boundaries
+
+| Result | Action |
+|---|---|
+| 401 / 403 | Check raw consumer Token, expiry, Suno entitlement, Allowed APIs and balance; inspect the actual business error. A 403 is not always moderation. |
+| 400 | Use current public model ID and schema; this first tool only exposes basic text-to-music. Duration/custom actions are not silently guessed. |
+| pending / empty media list | Query the same task ID; never regenerate to poll. |
+| 429 | Reduce concurrency and wait; the tool makes one HTTP attempt. Your agent/LLM may have separate retry behavior. |
+| Timeout / 5xx | Submission may have reached the service; inspect request history before creating a new job. |
+| ToolFailure | The terminal task failed; failure is structured and non-retryable by default. Preserve task/trace ID for support, never the key. |
+| Media won't open | Verify terminal success and network access to the returned HTTPS audio URL. |
+
+The integration code is free; API generation and any configured LLM follow their current prices. `cost` is the original task's Credits cost, not a new charge for querying it. Do not use a test count, install count or trace screenshot as revenue evidence. The tool sends the provided music prompt and consumer Token to `api.acedata.cloud`; only filtered result fields are returned to the agent. Do not submit private content without authorization.
+
+[Source](https://github.com/AceDataCloud/SunoCrewAI) · [Issues](https://github.com/AceDataCloud/SunoCrewAI/issues) · dev@acedata.cloud
+
+Development: `uv sync --group dev`, `uv run pytest`, `uv run ruff check .`, `uv build`. Tests mock paid HTTP calls. No paid generation is performed by CI.
+
+Release safety: HTTP errors retain status without raw bodies/headers; nested explicit failure is terminal before finished_at, and terminal missing audio is not success. Cost output is filtered.

crewai_suno-0.1.0/PRIVACY.md

@@ -0,0 +1,7 @@
+# Privacy
+
+The tools send user-selected music prompts and the API-consumer Token to `api.acedata.cloud` over HTTPS. The Token is read from an environment variable or explicit secure input and excluded from tool serialization. The package adds no analytics or telemetry and does not enable CrewAI tracing. CrewAI, the configured LLM, and the caller may have separate telemetry or trace settings. Do not place secrets or personal data in music prompts without authorization.
+
+Returned fields are limited to task status, the task ID, HTTPS audio result URLs and original cost. Raw request payloads and account/application identities are excluded. Optional task polling queries only the same ID. The caller controls retention, LLM context sharing and logging. Do not publish private media links or keys in bug reports.
+
+The API and any configured LLM follow current prices and data handling terms; this package does not accept terms or create an account for the user.

crewai_suno-0.1.0/README.md

@@ -0,0 +1,115 @@
+# Suno by Ace Data Cloud for CrewAI
+
+Generate Suno music and retrieve the same asynchronous task from native CrewAI tools. **Ace Data Cloud provides this integration; it is not an official Suno or CrewAI product.**
+
+[简体中文](readme/README_zh_Hans.md) · [Current models and pricing](https://platform.acedata.cloud/models?utm_source=github&utm_medium=referral&utm_campaign=evergreen&utm_content=sunocrewai_readme_pricing)
+
+## 1. Install the integration
+
+This is the standalone **Suno** package, not an all-services bundle. A [GitHub review preview with wheel and source archive](https://github.com/AceDataCloud/SunoCrewAI/releases/tag/v0.1.0-preview.1) is available; implementation remains under review. **No PyPI release or official CrewAI catalog listing is claimed.** Use the exact source commit below, or the hash-pinned wheel command after it. Do not install an attachment merely by tag name:
+
+```bash
+uv add 'crewai-suno @ git+https://github.com/AceDataCloud/SunoCrewAI.git@e5eeb04661ed7b9a86e1f2f970a9e7943b027ca2'
+```
+
+```bash
+uv add 'crewai-suno @ https://github.com/AceDataCloud/SunoCrewAI/releases/download/v0.1.0-preview.1/crewai_suno-0.1.0-py3-none-any.whl#sha256=d31998ca7f33f54c9603a0acb0d906f25933e858be6c83babc5a6d0e5a478e51'
+```
+
+The wheel was built from the exact source SHA above. Its SHA256 is pinned in the URL; if an asset is replaced, installation must fail the digest check. The release page is informational, not the trust anchor.
+
+The source SHA identifies the reviewed preview; inspect the [implementation PR](https://github.com/AceDataCloud/SunoCrewAI/pull/1) before adoption. After a verified PyPI release, the standard entry will be `uv add crewai-suno`. Do not interpret a repository or built wheel as an official listing. CrewAI currently requires Python 3.10–3.13; on Intel macOS its mandatory `lancedb` dependency may lack a wheel. Use a supported Linux environment rather than skipping dependencies for production.
+
+## 2. Register, sign in and obtain your own Token
+
+1. Open [Ace Data Cloud → Applications](https://platform.acedata.cloud/console/applications?utm_source=github&utm_medium=referral&utm_campaign=evergreen&utm_content=sunocrewai_readme_api_key). Register or sign in. If needed, choose **Initialize General Application**.
+2. Open **General application**. Check **Suno** access, current price and balance before generating. A service-specific application can only use its allowed service.
+3. Copy the selected API key with the copy icon **1**, or choose **Manage Keys** **2** to create a separate key.
+
+![Copy API Key or open Manage Keys; credentials redacted](assets/tutorial/get-api-key-en.png)
+
+4. Choose **Create**, name the key `CrewAI Suno`, and configure expiration/restrictions as needed. If **Allowed APIs** is enabled, allow both `/suno/audios` and `/suno/tasks`.
+
+![Create optional dedicated API Key; historical screenshot](assets/tutorial/create-api-key-en.png)
+
+These redacted screenshots are reused unchanged from the Ace SunoDify tutorial, revision `8d3d03570e73324220f111f7fe343da0792a8071`, retrieved 2026-10-18. The historical name `Dify tutorial` in the second screenshot is only an example; use `CrewAI Suno`. No visible real credential is included. See [image sources](assets/tutorial/source.json).
+
+Set the raw API-consumer Token in the environment variable `ACEDATACLOUD_API_KEY` using your secret manager or terminal's secure input. Do not prepend `Bearer`, use a platform management Token, put the key in prompts, or commit `.env` files. Tools also accept `api_key=...` when a secure credential store supplies it; it is excluded from serialization.
+
+## 3. Add the named Suno tools to your CrewAI agent
+
+```python
+from crewai import Agent
+from suno_crewai import SunoGenerateMusicTool, SunoRetrieveTaskTool
+
+agent = Agent(
+    role="Music producer",
+    goal="Create the requested music and check its task result",
+    backstory="Use Suno through Ace Data Cloud within the user's approved budget.",
+    llm=your_configured_llm,
+    tools=[SunoGenerateMusicTool(), SunoRetrieveTaskTool()],
+    allow_delegation=False,
+    max_retry_limit=0,
+)
+```
+
+These are actual CrewAI `BaseTool` implementations with input schemas and discoverable names **Suno by Ace Data Cloud - Generate Music** and **Suno by Ace Data Cloud - Retrieve Task**. They need no MCP server configuration. Adding a generation tool does not itself submit a request. The caller is responsible for approving the workflow's paid actions. The generation tool defaults to one use per instance to reduce duplicate submissions; this is not a funds cap or permission system.
+
+## 4. First use: submit once, then query the same ID
+
+First inspect the current [model and price catalog](https://platform.acedata.cloud/models?utm_source=github&utm_medium=referral&utm_campaign=evergreen&utm_content=sunocrewai_readme_first_use). Select a currently supported Suno model; `chirp-v6` is an example from the current Suno API contract, not a permanent default.
+
+A generation invocation is **billable**. Run it only after agreeing the model and budget:
+
+```python
+import json
+from suno_crewai import SunoGenerateMusicTool, SunoRetrieveTaskTool
+
+# BILLABLE when run; this README does not execute it.
+submitted = json.loads(SunoGenerateMusicTool().run(
+    prompt="A gentle instrumental piano melody for a sunrise, no vocals.",
+    model="chirp-v6",
+    instrumental=True,
+))
+print(submitted["task_id"])
+
+# accepted/pending is not completion. Preserve this same ID.
+result = SunoRetrieveTaskTool().run(task_id=submitted["task_id"], wait_seconds=240)
+print(result)
+```
+
+A pending result looks like `{"status":"pending","success":false,"task_id":"...","media_urls":[]}`. Do not rerun the generation if pending, timeout or an unknown submission outcome occurs. Query the same ID again. A terminal successful result includes `status=succeeded`, `success=true`, audio URLs and the original `cost`, when returned by the service. Costs are Credits; they are not USD. A link's presence does not verify that it remains playable.
+
+For an existing task, run only this **read-only** example:
+
+```bash
+uv run python examples/query_existing.py YOUR_EXISTING_TASK_ID
+```
+
+The ID must belong to your Key. The published payloads are `/suno/audios` with `async=true` and `/suno/tasks` with `action=retrieve,id=...`; model IDs pass through unchanged. No substitute model or automatic paid HTTP retry is added. Bounded polling only queries the same task.
+
+## 5. Inspect execution and output
+
+![Official historical CrewAI execution trace, not Ace runtime evidence](assets/tutorial/official-crewai-tracing.png)
+
+Official CrewAI reference, downloaded 2026-10-18 from its tracing documentation. The screenshot's historical date marker is `10/1/2025`; its capture version is unspecified. It shows a task timeline and Response output, **not this Suno tool running**, not an Ace result, and not a new GUI promised by this package. Inputs are not expanded in this image. For your own run, inspect the named Suno tool event and its returned task status. See [official tracing guide](https://docs.crewai.com/en/observability/tracing) for optional account/authentication requirements; tracing is not enabled by this package.
+
+## Troubleshooting and cost boundaries
+
+| Result | Action |
+|---|---|
+| 401 / 403 | Check raw consumer Token, expiry, Suno entitlement, Allowed APIs and balance; inspect the actual business error. A 403 is not always moderation. |
+| 400 | Use current public model ID and schema; this first tool only exposes basic text-to-music. Duration/custom actions are not silently guessed. |
+| pending / empty media list | Query the same task ID; never regenerate to poll. |
+| 429 | Reduce concurrency and wait; the tool makes one HTTP attempt. Your agent/LLM may have separate retry behavior. |
+| Timeout / 5xx | Submission may have reached the service; inspect request history before creating a new job. |
+| ToolFailure | The terminal task failed; failure is structured and non-retryable by default. Preserve task/trace ID for support, never the key. |
+| Media won't open | Verify terminal success and network access to the returned HTTPS audio URL. |
+
+The integration code is free; API generation and any configured LLM follow their current prices. `cost` is the original task's Credits cost, not a new charge for querying it. Do not use a test count, install count or trace screenshot as revenue evidence. The tool sends the provided music prompt and consumer Token to `api.acedata.cloud`; only filtered result fields are returned to the agent. Do not submit private content without authorization.
+
+[Source](https://github.com/AceDataCloud/SunoCrewAI) · [Issues](https://github.com/AceDataCloud/SunoCrewAI/issues) · dev@acedata.cloud
+
+Development: `uv sync --group dev`, `uv run pytest`, `uv run ruff check .`, `uv build`. Tests mock paid HTTP calls. No paid generation is performed by CI.
+
+Release safety: HTTP errors retain only status and a safe message, never raw service bodies or credential-bearing headers. Explicit nested failed states terminate polling even before finished_at appears; a finished task without a valid audio URL is not success. Original cost output is restricted to Credits amount/list_amount/currency.

crewai_suno-0.1.0/README.pypi.md

@@ -0,0 +1,115 @@
+# Suno by Ace Data Cloud for CrewAI
+
+Generate Suno music and retrieve the same asynchronous task from native CrewAI tools. **Ace Data Cloud provides this integration; it is not an official Suno or CrewAI product.**
+
+[简体中文](https://github.com/AceDataCloud/SunoCrewAI/blob/v0.1.0-preview.1/readme/README_zh_Hans.md) · [Current models and pricing](https://platform.acedata.cloud/models?utm_source=pypi&utm_medium=referral&utm_campaign=evergreen&utm_content=sunocrewai_package_pricing)
+
+## 1. Install the integration
+
+This is the standalone **Suno** package, not an all-services bundle. A [GitHub review preview with wheel and source archive](https://github.com/AceDataCloud/SunoCrewAI/releases/tag/v0.1.0-preview.1) is available; implementation remains under review. **No PyPI release or official CrewAI catalog listing is claimed.** Use the exact source commit below, or the hash-pinned wheel command after it. Do not install an attachment merely by tag name:
+
+```bash
+uv add 'crewai-suno @ git+https://github.com/AceDataCloud/SunoCrewAI.git@e5eeb04661ed7b9a86e1f2f970a9e7943b027ca2'
+```
+
+```bash
+uv add 'crewai-suno @ https://github.com/AceDataCloud/SunoCrewAI/releases/download/v0.1.0-preview.1/crewai_suno-0.1.0-py3-none-any.whl#sha256=d31998ca7f33f54c9603a0acb0d906f25933e858be6c83babc5a6d0e5a478e51'
+```
+
+The wheel was built from the exact source SHA above. Its SHA256 is pinned in the URL; if an asset is replaced, installation must fail the digest check. The release page is informational, not the trust anchor.
+
+The source SHA identifies the reviewed preview; inspect the [implementation PR](https://github.com/AceDataCloud/SunoCrewAI/pull/1) before adoption. After a verified PyPI release, the standard entry will be `uv add crewai-suno`. Do not interpret a repository or built wheel as an official listing. CrewAI currently requires Python 3.10–3.13; on Intel macOS its mandatory `lancedb` dependency may lack a wheel. Use a supported Linux environment rather than skipping dependencies for production.
+
+## 2. Register, sign in and obtain your own Token
+
+1. Open [Ace Data Cloud → Applications](https://platform.acedata.cloud/console/applications?utm_source=pypi&utm_medium=referral&utm_campaign=evergreen&utm_content=sunocrewai_package_api_key). Register or sign in. If needed, choose **Initialize General Application**.
+2. Open **General application**. Check **Suno** access, current price and balance before generating. A service-specific application can only use its allowed service.
+3. Copy the selected API key with the copy icon **1**, or choose **Manage Keys** **2** to create a separate key.
+
+![Copy API Key or open Manage Keys; credentials redacted](https://raw.githubusercontent.com/AceDataCloud/SunoCrewAI/v0.1.0-preview.1/assets/tutorial/get-api-key-en.png)
+
+4. Choose **Create**, name the key `CrewAI Suno`, and configure expiration/restrictions as needed. If **Allowed APIs** is enabled, allow both `/suno/audios` and `/suno/tasks`.
+
+![Create optional dedicated API Key; historical screenshot](https://raw.githubusercontent.com/AceDataCloud/SunoCrewAI/v0.1.0-preview.1/assets/tutorial/create-api-key-en.png)
+
+These redacted screenshots are reused unchanged from the Ace SunoDify tutorial, revision `8d3d03570e73324220f111f7fe343da0792a8071`, retrieved 2026-10-18. The historical name `Dify tutorial` in the second screenshot is only an example; use `CrewAI Suno`. No visible real credential is included. See [image sources](https://raw.githubusercontent.com/AceDataCloud/SunoCrewAI/v0.1.0-preview.1/assets/tutorial/source.json).
+
+Set the raw API-consumer Token in the environment variable `ACEDATACLOUD_API_KEY` using your secret manager or terminal's secure input. Do not prepend `Bearer`, use a platform management Token, put the key in prompts, or commit `.env` files. Tools also accept `api_key=...` when a secure credential store supplies it; it is excluded from serialization.
+
+## 3. Add the named Suno tools to your CrewAI agent
+
+```python
+from crewai import Agent
+from suno_crewai import SunoGenerateMusicTool, SunoRetrieveTaskTool
+
+agent = Agent(
+    role="Music producer",
+    goal="Create the requested music and check its task result",
+    backstory="Use Suno through Ace Data Cloud within the user's approved budget.",
+    llm=your_configured_llm,
+    tools=[SunoGenerateMusicTool(), SunoRetrieveTaskTool()],
+    allow_delegation=False,
+    max_retry_limit=0,
+)
+```
+
+These are actual CrewAI `BaseTool` implementations with input schemas and discoverable names **Suno by Ace Data Cloud - Generate Music** and **Suno by Ace Data Cloud - Retrieve Task**. They need no MCP server configuration. Adding a generation tool does not itself submit a request. The caller is responsible for approving the workflow's paid actions. The generation tool defaults to one use per instance to reduce duplicate submissions; this is not a funds cap or permission system.
+
+## 4. First use: submit once, then query the same ID
+
+First inspect the current [model and price catalog](https://platform.acedata.cloud/models?utm_source=pypi&utm_medium=referral&utm_campaign=evergreen&utm_content=sunocrewai_package_first_use). Select a currently supported Suno model; `chirp-v6` is an example from the current Suno API contract, not a permanent default.
+
+A generation invocation is **billable**. Run it only after agreeing the model and budget:
+
+```python
+import json
+from suno_crewai import SunoGenerateMusicTool, SunoRetrieveTaskTool
+
+# BILLABLE when run; this README does not execute it.
+submitted = json.loads(SunoGenerateMusicTool().run(
+    prompt="A gentle instrumental piano melody for a sunrise, no vocals.",
+    model="chirp-v6",
+    instrumental=True,
+))
+print(submitted["task_id"])
+
+# accepted/pending is not completion. Preserve this same ID.
+result = SunoRetrieveTaskTool().run(task_id=submitted["task_id"], wait_seconds=240)
+print(result)
+```
+
+A pending result looks like `{"status":"pending","success":false,"task_id":"...","media_urls":[]}`. Do not rerun the generation if pending, timeout or an unknown submission outcome occurs. Query the same ID again. A terminal successful result includes `status=succeeded`, `success=true`, audio URLs and the original `cost`, when returned by the service. Costs are Credits; they are not USD. A link's presence does not verify that it remains playable.
+
+For an existing task, run only this **read-only** example:
+
+```bash
+uv run python examples/query_existing.py YOUR_EXISTING_TASK_ID
+```
+
+The ID must belong to your Key. The published payloads are `/suno/audios` with `async=true` and `/suno/tasks` with `action=retrieve,id=...`; model IDs pass through unchanged. No substitute model or automatic paid HTTP retry is added. Bounded polling only queries the same task.
+
+## 5. Inspect execution and output
+
+![Official historical CrewAI execution trace, not Ace runtime evidence](https://raw.githubusercontent.com/AceDataCloud/SunoCrewAI/v0.1.0-preview.1/assets/tutorial/official-crewai-tracing.png)
+
+Official CrewAI reference, downloaded 2026-10-18 from its tracing documentation. The screenshot's historical date marker is `10/1/2025`; its capture version is unspecified. It shows a task timeline and Response output, **not this Suno tool running**, not an Ace result, and not a new GUI promised by this package. Inputs are not expanded in this image. For your own run, inspect the named Suno tool event and its returned task status. See [official tracing guide](https://docs.crewai.com/en/observability/tracing) for optional account/authentication requirements; tracing is not enabled by this package.
+
+## Troubleshooting and cost boundaries
+
+| Result | Action |
+|---|---|
+| 401 / 403 | Check raw consumer Token, expiry, Suno entitlement, Allowed APIs and balance; inspect the actual business error. A 403 is not always moderation. |
+| 400 | Use current public model ID and schema; this first tool only exposes basic text-to-music. Duration/custom actions are not silently guessed. |
+| pending / empty media list | Query the same task ID; never regenerate to poll. |
+| 429 | Reduce concurrency and wait; the tool makes one HTTP attempt. Your agent/LLM may have separate retry behavior. |
+| Timeout / 5xx | Submission may have reached the service; inspect request history before creating a new job. |
+| ToolFailure | The terminal task failed; failure is structured and non-retryable by default. Preserve task/trace ID for support, never the key. |
+| Media won't open | Verify terminal success and network access to the returned HTTPS audio URL. |
+
+The integration code is free; API generation and any configured LLM follow their current prices. `cost` is the original task's Credits cost, not a new charge for querying it. Do not use a test count, install count or trace screenshot as revenue evidence. The tool sends the provided music prompt and consumer Token to `api.acedata.cloud`; only filtered result fields are returned to the agent. Do not submit private content without authorization.
+
+[Source](https://github.com/AceDataCloud/SunoCrewAI) · [Issues](https://github.com/AceDataCloud/SunoCrewAI/issues) · dev@acedata.cloud
+
+Development: `uv sync --group dev`, `uv run pytest`, `uv run ruff check .`, `uv build`. Tests mock paid HTTP calls. No paid generation is performed by CI.
+
+Release safety: HTTP errors retain status without raw bodies/headers; nested explicit failure is terminal before finished_at, and terminal missing audio is not success. Cost output is filtered.

crewai_suno-0.1.0/assets/tutorial/source.json

@@ -0,0 +1,8 @@
+{
+  "retrieved_at": "2026-10-18",
+  "images": [
+    {"file":"get-api-key-en.png","source_url":"https://raw.githubusercontent.com/AceDataCloud/SunoDify/8d3d03570e73324220f111f7fe343da0792a8071/_assets/tutorial/get-api-key-en.png","what_it_shows":"Redacted General application API Key copy and Manage Keys controls","limits":"Historical screenshot; no credentials visible; reused unchanged"},
+    {"file":"create-api-key-en.png","source_url":"https://raw.githubusercontent.com/AceDataCloud/SunoDify/8d3d03570e73324220f111f7fe343da0792a8071/_assets/tutorial/create-api-key-en.png","what_it_shows":"Create credential dialog","limits":"Historical example says Dify tutorial; README explains to use CrewAI Suno; reused unchanged"},
+    {"file":"official-crewai-tracing.png","source_url":"https://raw.githubusercontent.com/crewAIInc/crewAI/40bb2d3b586e8367d206090cc62df5242206008f/docs/images/crewai-tracing.png","official_page_url":"https://docs.crewai.com/v1.15.28/en/observability/tracing","what_it_shows":"Official CrewAI execution timeline and Response output","limits":"Historical date marker 10/1/2025; unknown capture version; not Ace runtime, not Suno package validation, not promised GUI"}
+  ]
+}

crewai_suno-0.1.0/examples/query_existing.py

@@ -0,0 +1,10 @@
+"""Free read-only example; requires a task already owned by your API Key."""
+
+import argparse
+
+from suno_crewai import SunoRetrieveTaskTool
+
+parser = argparse.ArgumentParser(description=__doc__)
+parser.add_argument("task_id")
+args = parser.parse_args()
+print(SunoRetrieveTaskTool().run(task_id=args.task_id, wait_seconds=0))

crewai_suno-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "crewai-suno"
+version = "0.1.0"
+description = "Suno by Ace Data Cloud: native CrewAI music generation and same-task retrieval tools"
+readme = "README.pypi.md"
+requires-python = ">=3.10,<3.14"
+license = "MIT"
+authors = [{name = "Ace Data Cloud Dev", email = "dev@acedata.cloud"}]
+keywords = ["crewai", "suno", "music", "audio", "agents", "acedatacloud"]
+dependencies = ["crewai>=1.15.28,<2", "httpx>=0.28,<1", "pydantic>=2.11,<3"]
+
+[project.urls]
+Homepage = "https://github.com/AceDataCloud/SunoCrewAI"
+Repository = "https://github.com/AceDataCloud/SunoCrewAI"
+Documentation = "https://github.com/AceDataCloud/SunoCrewAI#readme"
+Issues = "https://github.com/AceDataCloud/SunoCrewAI/issues"
+
+[dependency-groups]
+dev = ["pytest>=8,<10", "ruff==0.15.1", "build>=1,<2", "twine>=6,<7"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/suno_crewai"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+ignore = ["E501"]

crewai_suno-0.1.0/readme/README_zh_Hans.md

@@ -0,0 +1,105 @@
+# Suno by Ace Data Cloud：CrewAI 原生音乐工具
+
+本集成由 **Ace Data Cloud** 提供，不是 Suno 或 CrewAI 官方产品。独立 Suno 品牌包，不是 17 服务合集。[English](../README.md)
+
+## 安装入口
+
+已有 [GitHub 预览 wheel 与源码包](https://github.com/AceDataCloud/SunoCrewAI/releases/tag/v0.1.0-preview.1)，源码仍在审阅，**尚未 PyPI 发布或 CrewAI 官方目录收录**。先审阅[本仓库 PR](https://github.com/AceDataCloud/SunoCrewAI/pulls)，固定下列源码，或使用带 SHA256 校验的 wheel；不要仅按 tag 名称安装附件：
+
+```bash
+uv add 'crewai-suno @ git+https://github.com/AceDataCloud/SunoCrewAI.git@e5eeb04661ed7b9a86e1f2f970a9e7943b027ca2'
+```
+
+```bash
+uv add 'crewai-suno @ https://github.com/AceDataCloud/SunoCrewAI/releases/download/v0.1.0-preview.1/crewai_suno-0.1.0-py3-none-any.whl#sha256=d31998ca7f33f54c9603a0acb0d906f25933e858be6c83babc5a6d0e5a478e51'
+```
+
+wheel 来自同一固定源码 SHA，URL 强制校验 SHA256；若附件替换，摘要不符必须失败。release 页面仅提供信息，不作为信任锚。
+
+发布后目标命令为 `uv add crewai-suno`，尚未发布前不要把它当现成安装入口。CrewAI 要求 Python 3.10–3.13；Intel macOS 可能缺 lancedb wheel，正式使用请选择支持的 Linux 环境，不跳过依赖冒充完整安装。
+
+## 获取自己的 API Token
+
+1. 打开 [Ace Applications](https://platform.acedata.cloud/console/applications?utm_source=github&utm_medium=referral&utm_campaign=evergreen&utm_content=sunocrewai_readme_zh_api_key)，注册并登录。必要时选择 **Initialize General Application**。
+2. 打开 **General application**，确认 Suno 权限、当前余额和[价格](https://platform.acedata.cloud/models?utm_source=github&utm_medium=referral&utm_campaign=evergreen&utm_content=sunocrewai_readme_zh_pricing)。服务专属应用只支持授权的服务。
+3. 点击下图 **1** 复制已有 Key，或 **2 Manage Keys → Create** 创建独立 Key。
+
+![复制 API Key 或进入 Manage Keys，凭据均已遮挡](../assets/tutorial/get-api-key-en.png)
+
+4. 将新 Key 命名为 `CrewAI Suno`，按需配置过期、额度和权限。若启用 **Allowed APIs**，同时允许 `/suno/audios` 与 `/suno/tasks`。
+
+![创建专用 Key 的历史真实截图](../assets/tutorial/create-api-key-en.png)
+
+图片于 2026-10-18 从 SunoDify 固定版本原样复用，来源见 [source.json](../assets/tutorial/source.json)。第二图历史名称是 `Dify tutorial`，这里只是示例，请填写 `CrewAI Suno`。没有可见真实凭据。
+
+用安全输入或密钥管理器设置环境变量 `ACEDATACLOUD_API_KEY`。只放 Token 原文，不加 `Bearer`、引号或空格；不要用 platform 管理 Token，也不要把 Key 放进 prompt 或提交到 `.env`。工具可从安全凭据存储接收 `api_key=...`，序列化不包含它。
+
+## 在 CrewAI 中添加 Suno 工具
+
+```python
+from crewai import Agent
+from suno_crewai import SunoGenerateMusicTool, SunoRetrieveTaskTool
+
+agent = Agent(
+    role="音乐制作人",
+    goal="按用户已批准预算生成音乐，并查询同一任务结果",
+    backstory="使用 Ace Data Cloud 的 Suno 服务",
+    llm=your_configured_llm,
+    tools=[SunoGenerateMusicTool(), SunoRetrieveTaskTool()],
+    allow_delegation=False,
+    max_retry_limit=0,
+)
+```
+
+工具名称为 **Suno by Ace Data Cloud - Generate Music** 和 **Suno by Ace Data Cloud - Retrieve Task**，有原生输入 schema，无需配置 MCP。只是添加工具不会调用接口；调用者负责批准付费行为。生成工具每个实例默认只允许一次调用，防止重复提交，但这不是额度上限或权限系统。
+
+## 首用与同 ID 查询
+
+先查当前模型目录，选择公开 Suno model ID；`chirp-v6` 是当前 API 合同示例，不是永久默认。生成请求收费，须先确定模型与额度：
+
+```python
+import json
+from suno_crewai import SunoGenerateMusicTool, SunoRetrieveTaskTool
+
+# 实际执行会收费；本教程没有运行该调用。
+submitted = json.loads(SunoGenerateMusicTool().run(
+    prompt="A gentle instrumental piano melody for a sunrise, no vocals.",
+    model="chirp-v6", instrumental=True,
+))
+result = SunoRetrieveTaskTool().run(task_id=submitted["task_id"], wait_seconds=240)
+print(result)
+```
+
+accepted / pending 不等于成功；保存原 `task_id`，未完成、超时或提交结果不明时，不要重跑生成。继续查询同一 ID。成功返回 `status=succeeded`、`success=true`、`media_urls` 及接口返回的原 `cost`（Credits，不是 USD）。媒体链接存在不代表已验证可播放。
+
+对用户自己的旧任务，可直接免费只读查询：
+
+```bash
+uv run python examples/query_existing.py YOUR_EXISTING_TASK_ID
+```
+
+实际接口是 `/suno/audios` + `async=true`，以及 `/suno/tasks` + `action=retrieve,id=...`。只做初始文字生成，不猜测 duration 或高级动作，不加模型 fallback，不自动重试收费 HTTP 提交；有界等待只查询同一个任务。
+
+## 在真实 CrewAI 界面查看执行
+
+![CrewAI 官方历史执行详情，仅作交互参考，非 Ace 跑通](../assets/tutorial/official-crewai-tracing.png)
+
+图为 CrewAI 官方历史原图，2026-10-18 下载，原图日期标记 `10/1/2025`、版本未注明；左侧是执行步骤，右侧展开 Response，输入未展开。**不是本 Suno 包运行截图，不证明 Ace 上线，也不承诺新增 GUI**。你的实际执行应检查具名 Suno 工具事件和 task 状态；可选 tracing 的账号/认证见[官方文档](https://docs.crewai.com/en/observability/tracing)，本包不自动开启追踪。
+
+## 常见问题
+
+| 情况 | 处理 |
+|---|---|
+| 401 / 403 | 检查完整消费者 Token、过期、Suno 权限、Allowed APIs 和余额；403 不一概等于内容审核。 |
+| 400 | 对照当前模型及输入 schema；本工具不隐式支持所有高级动作。 |
+| pending / 无结果 | 只查同一任务 ID，不重新生成。 |
+| 429 | 降低并发并等待；工具只发一次 HTTP，LLM / agent 自身可能另有重试。 |
+| 超时 / 5xx | 提交可能已到服务端，先看请求历史再决定是否重新生成。 |
+| ToolFailure | 已明确失败；结构化错误默认不可重试。保留 task/trace ID 联系支持，不提供 Key。 |
+| 音频无法打开 | 确认终态成功，再检查返回 HTTPS URL 的网络访问。 |
+
+代码免费，生成和你配置的 LLM 按当前价格计费；查询中的 cost 是原任务费用，不是新增营收或新扣款证据。工具把用户 prompt 与 Token 发往 `api.acedata.cloud`，仅向 agent 返回过滤后的结果，不返回原始请求和身份字段。测试均 Mock 收费 HTTP，不把安装、测试次数当用户或收入。
+
+[源码](https://github.com/AceDataCloud/SunoCrewAI) · [反馈](https://github.com/AceDataCloud/SunoCrewAI/issues) · dev@acedata.cloud
+
+发布安全：HTTP错误仅保留状态与安全说明，不返回原始服务body或凭据headers；嵌套failed等状态在finished_at尚未写入时也停止轮询。终态缺有效音频URL不算成功；原费用只保留Credits的amount/list_amount/currency。

crewai_suno-0.1.0/src/suno_crewai/__init__.py

@@ -0,0 +1,5 @@
+"""Suno by Ace Data Cloud for CrewAI. Not affiliated with Suno or CrewAI."""
+
+from suno_crewai.tools import SunoGenerateMusicTool, SunoRetrieveTaskTool
+
+__all__ = ["SunoGenerateMusicTool", "SunoRetrieveTaskTool"]

crewai_suno-0.1.0/src/suno_crewai/_base.py

@@ -0,0 +1,233 @@
+"""Single-attempt consumer-token transport and strict asynchronous task results.
+
+Shared safety semantics with the independently reviewed media packages.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from typing import Any, ClassVar
+from urllib.parse import urlsplit
+
+import httpx
+from crewai.tools import BaseTool, EnvVar
+from crewai.tools.tool_failure import ToolFailure, ToolFailureReason
+from pydantic import BaseModel, Field, PrivateAttr
+
+API_BASE = "https://api.acedata.cloud"
+FAILED = {"failed", "error", "cancelled", "canceled", "rejected"}
+PENDING = {"pending", "queued", "processing", "running", "submitted", "created"}
+
+
+class ServiceHTTPError(RuntimeError):
+    """Preserve HTTP meaning without exposing response bodies or request headers."""
+
+    def __init__(self, status_code: int) -> None:
+        self.status_code = status_code
+        super().__init__(
+            f"Service HTTP {status_code}; inspect the request using its task/trace ID. Do not include your Token."
+        )
+
+
+class RetrieveTaskInput(BaseModel):
+    task_id: str = Field(
+        min_length=1,
+        description="The original task_id from generation; never create another job to poll",
+    )
+    wait_seconds: int = Field(
+        default=0, ge=0, le=240, description="Bounded same-ID polling; 0 queries once"
+    )
+
+
+class ServiceTool(BaseTool):
+    _api_key: str = PrivateAttr()
+    service: ClassVar[str]
+    task_path: ClassVar[str]
+    env_vars: list[EnvVar] = Field(
+        default_factory=lambda: [
+            EnvVar(
+                name="ACEDATACLOUD_API_KEY",
+                description="Raw Ace API-consumer Token with the selected service access",
+                required=True,
+            )
+        ]
+    )
+
+    def __init__(self, api_key: str | None = None, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        token = api_key or os.environ.get("ACEDATACLOUD_API_KEY", "")
+        if (
+            not token
+            or token != token.strip()
+            or token.lower().startswith(("bearer ", "platform-"))
+        ):
+            raise ValueError(
+                "Set ACEDATACLOUD_API_KEY to the raw API-consumer Token, without Bearer, spaces or platform management credentials"
+            )
+        self._api_key = token
+
+    def _request(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        try:
+            with httpx.Client(timeout=45, follow_redirects=False) as client:
+                response = client.post(
+                    API_BASE + path,
+                    headers={
+                        "Authorization": f"Bearer {self._api_key}",
+                        "Accept": "application/json",
+                    },
+                    json=payload,
+                )
+                if response.status_code >= 300:
+                    raise ServiceHTTPError(response.status_code)
+                try:
+                    body = response.json()
+                except ValueError:
+                    raise ValueError(
+                        "Invalid service JSON; check request history before submitting again"
+                    ) from None
+        except httpx.TimeoutException:
+            raise TimeoutError(
+                "Request timed out; submission outcome may be unknown. Inspect request history before any resubmission."
+            ) from None
+        except httpx.TransportError:
+            raise ConnectionError(
+                "Service connection failed; inspect request history before any resubmission."
+            ) from None
+        if not isinstance(body, dict):
+            raise ValueError(
+                "Invalid service response shape; check request history before submitting again"
+            )
+        return body
+
+    def _failure(self, task_id: str, code: str = "task_failed") -> ToolFailure:
+        return ToolFailure(
+            message=f"{self.service} task failed or returned an invalid terminal result; inspect its task/trace ID before resubmitting.",
+            reason=ToolFailureReason.TOOL_REPORTED,
+            code=code,
+            retryable=False,
+            details={"task_id": task_id},
+        )
+
+    def _media_urls(self, result: dict[str, Any]) -> list[str]:
+        raise NotImplementedError
+
+    def _normalize(
+        self, body: dict[str, Any], task_id: str, *, retrieved: bool
+    ) -> dict[str, Any] | ToolFailure:
+        if retrieved:
+            returned_id = body.get("id") or body.get("task_id")
+            if returned_id and returned_id != task_id:
+                raise ValueError("Returned task ID does not match the requested task")
+        result = body.get("response") if retrieved else body
+        if isinstance(result, str):
+            try:
+                result = json.loads(result)
+            except ValueError:
+                return self._failure(task_id, "invalid_terminal_result")
+        result = result if isinstance(result, dict) else {}
+        resolved_id = task_id or str(
+            body.get("task_id")
+            or (
+                body.get("task", {}).get("id")
+                if isinstance(body.get("task"), dict)
+                else ""
+            )
+            or ""
+        )
+        finished = retrieved and bool(body.get("finished_at"))
+        # Check service state within data/content, including item lists, before
+        # interpreting the envelope success flag. Do not recurse arbitrary fields.
+        states: list[str] = [
+            str(body[key]).lower()
+            for key in ("state", "status")
+            if isinstance(body.get(key), str)
+        ]
+        errors = [bool(body.get("error")), bool(result.get("error"))]
+
+        def inspect(node: Any) -> None:
+            if isinstance(node, list):
+                for item in node:
+                    inspect(item)
+            elif isinstance(node, dict):
+                for key in ("state", "status"):
+                    if isinstance(node.get(key), str):
+                        states.append(node[key].lower())
+                if node.get("error") or node.get("success") is False:
+                    errors.append(True)
+                for key in ("data", "content", "task"):
+                    if key in node:
+                        inspect(node[key])
+
+        inspect(body if not retrieved else result)
+        failed = any(errors) or any(state in FAILED for state in states)
+        if (
+            any(state in FAILED for state in states)
+            or body.get("error")
+            or (finished and failed)
+            or (not retrieved and failed)
+        ):
+            return self._failure(resolved_id)
+        if not resolved_id:
+            raise ValueError(
+                "No task ID returned; inspect request history before any resubmission"
+            )
+        succeeded = (
+            finished
+            and result.get("success") is True
+            and not any(s in PENDING for s in states)
+        )
+        urls = self._media_urls(result) if succeeded else []
+        if succeeded and not urls:
+            return self._failure(resolved_id, "missing_terminal_media")
+        cost = result.get("cost") if succeeded else None
+        cost = (
+            {
+                k: v
+                for k, v in cost.items()
+                if (
+                    k in {"amount", "list_amount"}
+                    and isinstance(v, (int, float))
+                    and not isinstance(v, bool)
+                )
+                or (k == "currency" and v == "credit")
+            }
+            if isinstance(cost, dict)
+            else None
+        )
+        return {
+            "status": "succeeded" if succeeded else "pending",
+            "success": succeeded,
+            "task_id": resolved_id,
+            "media_urls": urls,
+            "cost": cost,
+        }
+
+    def _retrieve(self, task_id: str, wait_seconds: int = 0) -> str | ToolFailure:
+        deadline = time.monotonic() + wait_seconds
+        while True:
+            body = self._request(self.task_path, {"action": "retrieve", "id": task_id})
+            result = self._normalize(body, task_id, retrieved=True)
+            if isinstance(result, ToolFailure):
+                return result
+            remaining = deadline - time.monotonic()
+            if result["status"] != "pending" or remaining <= 0:
+                return json.dumps(result)
+            time.sleep(min(5, remaining))
+
+
+def https_urls(values: list[Any]) -> list[str]:
+    urls = []
+    for value in values:
+        if isinstance(value, str):
+            parts = urlsplit(value)
+            if (
+                parts.scheme == "https"
+                and parts.hostname
+                and not parts.username
+                and not parts.password
+                and value not in urls
+            ):
+                urls.append(value)
+    return urls

crewai_suno-0.1.0/src/suno_crewai/tools.py

@@ -0,0 +1,75 @@
+"""Suno music generation and same-task retrieval for CrewAI."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from crewai.tools.tool_failure import ToolFailure
+from pydantic import BaseModel, ConfigDict, Field
+
+from suno_crewai._base import RetrieveTaskInput, ServiceTool, https_urls
+
+
+class GenerateMusicInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    prompt: str = Field(min_length=1, description="Description of music to generate")
+    model: str = Field(
+        min_length=1, description="Current public Suno model ID, passed unchanged"
+    )
+    instrumental: bool = Field(
+        default=True, description="Generate instrumental music without vocals"
+    )
+
+
+class _SunoTool(ServiceTool):
+    service = "Suno"
+    task_path = "/suno/tasks"
+
+    def _media_urls(self, result: dict[str, Any]) -> list[str]:
+        data = result.get("data") or []
+        return https_urls(
+            [item.get("audio_url") for item in data if isinstance(item, dict)]
+            if isinstance(data, list)
+            else []
+        )
+
+
+class SunoGenerateMusicTool(_SunoTool):
+    name: str = "Suno by Ace Data Cloud - Generate Music"
+    description: str = (
+        "Generate music with Suno through Ace Data Cloud. This submits one billable job; "
+        "accepted is pending, not complete. Save task_id and use Retrieve Task to wait. "
+        "Never repeat generation to poll or recover an unknown submission outcome."
+    )
+    args_schema: type[BaseModel] = GenerateMusicInput
+    max_usage_count: int | None = 1
+
+    def _run(
+        self, prompt: str, model: str, instrumental: bool = True
+    ) -> str | ToolFailure:
+        body = self._request(
+            "/suno/audios",
+            {
+                "action": "generate",
+                "custom": False,
+                "prompt": prompt,
+                "model": model,
+                "instrumental": instrumental,
+                "async": True,
+            },
+        )
+        result = self._normalize(body, "", retrieved=False)
+        return result if isinstance(result, ToolFailure) else json.dumps(result)
+
+
+class SunoRetrieveTaskTool(_SunoTool):
+    name: str = "Suno by Ace Data Cloud - Retrieve Task"
+    description: str = (
+        "Read an existing Suno task_id, optionally wait up to240 seconds. pending is not success. "
+        "This tool never creates music; query the same ID if still pending."
+    )
+    args_schema: type[BaseModel] = RetrieveTaskInput
+
+    def _run(self, task_id: str, wait_seconds: int = 0) -> str | ToolFailure:
+        return self._retrieve(task_id, wait_seconds)

crewai_suno-0.1.0/tests/contract-source.json

@@ -0,0 +1,7 @@
+{
+  "as_of": "2026-10-18",
+  "source": "https://github.com/AceDataCloud/SunoDify/blob/main/tools/api_contracts.py",
+  "generation": "POST /suno/audios action=generate custom=false prompt/model/instrumental async=true",
+  "retrieve": "POST /suno/tasks action=retrieve id=<same task>",
+  "scope": "basic text-to-music and one existing task; no fallback, advanced actions, duration guessing or paid retry"
+}

crewai_suno-0.1.0/tests/live-readonly-evidence.json

@@ -0,0 +1,16 @@
+{
+  "service": "Suno",
+  "as_of": "2026-10-18",
+  "task_id_matches": true,
+  "status": "succeeded",
+  "success": true,
+  "media_count": 2,
+  "original_cost": {
+    "amount": 0.504,
+    "currency": "credit",
+    "list_amount": 0.56
+  },
+  "new_generation_calls": 0,
+  "paid_model_calls": 0,
+  "limits": "Read-only existing task, no new bill/unique-bill or media playback verification; runtime missing mandatory lancedb, Linux CI pending."
+}

crewai_suno-0.1.0/tests/test_agent.py

@@ -0,0 +1,135 @@
+"""A real CrewAI tool cycle, with a local model fixture and mocked Suno query."""
+
+import json
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from unittest.mock import patch
+
+import httpx
+from crewai import LLM, Agent, Crew, Task
+
+from suno_crewai import SunoRetrieveTaskTool
+
+
+def test_agent_queries_existing_suno_task_without_generation(monkeypatch):
+    monkeypatch.setenv("CREWAI_TELEMETRY_DISABLED", "true")
+    monkeypatch.setenv("OTEL_SDK_DISABLED", "true")
+    monkeypatch.setenv("CREWAI_TRACING_ENABLED", "false")
+    requests = []
+
+    class ModelFixture(BaseHTTPRequestHandler):
+        def log_message(self, *_args):
+            pass
+
+        def do_POST(self):
+            body = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
+            requests.append(body)
+            tool_results = [m for m in body["messages"] if m.get("role") == "tool"]
+            if tool_results:
+                result = json.loads(tool_results[-1]["content"])
+                assert result["status"] == "succeeded"
+                message = {
+                    "role": "assistant",
+                    "content": "Existing Suno task succeeded.",
+                }
+                finish_reason = "stop"
+            else:
+                assert len(body["tools"]) == 1
+                name = body["tools"][0]["function"]["name"]
+                assert "suno" in name.lower() and "retrieve" in name.lower()
+                message = {
+                    "role": "assistant",
+                    "content": None,
+                    "tool_calls": [
+                        {
+                            "id": "read-only",
+                            "type": "function",
+                            "function": {
+                                "name": name,
+                                "arguments": json.dumps(
+                                    {"task_id": "existing", "wait_seconds": 0}
+                                ),
+                            },
+                        }
+                    ],
+                }
+                finish_reason = "tool_calls"
+            response = json.dumps(
+                {
+                    "id": "local",
+                    "object": "chat.completion",
+                    "created": 1,
+                    "model": body["model"],
+                    "choices": [
+                        {"index": 0, "message": message, "finish_reason": finish_reason}
+                    ],
+                    "usage": {
+                        "prompt_tokens": 1,
+                        "completion_tokens": 1,
+                        "total_tokens": 2,
+                    },
+                }
+            ).encode()
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(response)))
+            self.end_headers()
+            self.wfile.write(response)
+
+    server = ThreadingHTTPServer(("127.0.0.1", 0), ModelFixture)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    try:
+        llm = LLM(
+            model="gpt-4.1-mini",
+            custom_openai=True,
+            base_url=f"http://127.0.0.1:{server.server_port}/v1",
+            api_key="local-fixture",
+            max_retries=0,
+        )
+        tool = SunoRetrieveTaskTool(api_key="test-key")
+        agent = Agent(
+            role="Suno task reader",
+            goal="Query the existing task once",
+            backstory="Never generate new music",
+            tools=[tool],
+            llm=llm,
+            function_calling_llm=llm,
+            allow_delegation=False,
+            max_iter=3,
+            max_retry_limit=0,
+        )
+        task = Task(
+            description="Query existing task existing and report its state",
+            expected_output="Task state",
+            agent=agent,
+        )
+        body = {
+            "id": "existing",
+            "finished_at": 1,
+            "response": {
+                "success": True,
+                "data": [{"audio_url": "https://example.com/audio.mp3"}],
+            },
+        }
+        response = httpx.Response(
+            200,
+            json=body,
+            request=httpx.Request("POST", "https://api.acedata.cloud/suno/tasks"),
+        )
+        with patch("httpx.Client.post", return_value=response) as query:
+            result = Crew(
+                agents=[agent], tasks=[task], memory=False, tracing=False
+            ).kickoff()
+        assert result.raw == "Existing Suno task succeeded."
+        assert query.call_count == 1
+        assert query.call_args.args[0] == "https://api.acedata.cloud/suno/tasks"
+        assert query.call_args.kwargs["json"] == {
+            "action": "retrieve",
+            "id": "existing",
+        }
+        assert len(requests) == 2
+    finally:
+        server.shutdown()
+        server.server_close()
+        thread.join(timeout=2)

crewai_suno-0.1.0/tests/test_tools.py

@@ -0,0 +1,191 @@
+import json
+from unittest.mock import patch
+
+import httpx
+import pytest
+from crewai.tools.tool_failure import ToolFailure
+
+from suno_crewai import SunoGenerateMusicTool, SunoRetrieveTaskTool
+from suno_crewai._base import ServiceHTTPError
+
+
+def reply(body, status=200):
+    return httpx.Response(
+        status,
+        json=body,
+        request=httpx.Request("POST", "https://api.acedata.cloud/suno/tasks"),
+    )
+
+
+def completed():
+    return {
+        "id": "existing",
+        "finished_at": 1,
+        "request": {"secret": "not-for-agent"},
+        "response": {
+            "success": True,
+            "data": [{"audio_url": "https://example.com/music.mp3"}],
+            "cost": {"amount": 0.1, "currency": "credit"},
+        },
+    }
+
+
+def test_submit_once_and_accepted_is_pending():
+    tool = SunoGenerateMusicTool(api_key="test-consumer-key")
+    with patch(
+        "httpx.Client.post", return_value=reply({"success": True, "task_id": "new"})
+    ) as post:
+        result = json.loads(tool.run(prompt="piano", model="public-model"))
+        assert post.call_count == 1
+        assert post.call_args.args[0] == "https://api.acedata.cloud/suno/audios"
+        assert post.call_args.kwargs["json"] == {
+            "action": "generate",
+            "custom": False,
+            "prompt": "piano",
+            "model": "public-model",
+            "instrumental": True,
+            "async": True,
+        }
+        assert result == {
+            "status": "pending",
+            "success": False,
+            "task_id": "new",
+            "media_urls": [],
+            "cost": None,
+        }
+        assert isinstance(tool.run(prompt="again", model="public-model"), ToolFailure)
+        assert post.call_count == 1
+
+
+def test_read_same_id_and_filter_private_fields():
+    tool = SunoRetrieveTaskTool(api_key="test-consumer-key")
+    with patch("httpx.Client.post", return_value=reply(completed())) as post:
+        result = json.loads(tool.run(task_id="existing"))
+    assert post.call_args.kwargs["json"] == {"action": "retrieve", "id": "existing"}
+    assert result["status"] == "succeeded" and result["success"]
+    assert result["media_urls"] == ["https://example.com/music.mp3"]
+    assert "not-for-agent" not in str(result)
+    assert "test-consumer-key" not in str(tool.model_dump())
+
+
+def test_unfinished_preview_is_pending():
+    body = completed()
+    body["finished_at"] = None
+    with patch("httpx.Client.post", return_value=reply(body)):
+        result = json.loads(SunoRetrieveTaskTool(api_key="key").run(task_id="existing"))
+    assert result["status"] == "pending" and not result["media_urls"]
+
+
+def test_terminal_failure_is_structured_and_not_retryable():
+    body = {
+        "id": "existing",
+        "finished_at": 1,
+        "response": {"success": False, "error": "fixture"},
+    }
+    with patch("httpx.Client.post", return_value=reply(body)):
+        result = SunoRetrieveTaskTool(api_key="key").run(task_id="existing")
+    assert isinstance(result, ToolFailure) and not result.retryable
+    assert result.code == "task_failed"
+
+
+@pytest.mark.parametrize("status", [401, 403, 429, 500])
+def test_http_status_retained_without_retry(status):
+    with patch(
+        "httpx.Client.post", return_value=reply({"error": "fixture"}, status)
+    ) as post:
+        with pytest.raises(ServiceHTTPError) as caught:
+            SunoGenerateMusicTool(api_key="key").run(prompt="piano", model="model")
+    assert caught.value.status_code == status
+    assert post.call_count == 1
+
+
+def test_timeout_is_not_retried():
+    with patch(
+        "httpx.Client.post", side_effect=httpx.ReadTimeout("unknown submission outcome")
+    ) as post:
+        with pytest.raises(TimeoutError):
+            SunoGenerateMusicTool(api_key="key").run(prompt="piano", model="model")
+    assert post.call_count == 1
+
+
+def test_bounded_wait_queries_only_same_task():
+    pending = {"id": "existing", "finished_at": None, "response": None}
+    with (
+        patch(
+            "httpx.Client.post", side_effect=[reply(pending), reply(completed())]
+        ) as post,
+        patch("suno_crewai._base.time.monotonic", side_effect=[0, 1, 2]),
+        patch("suno_crewai._base.time.sleep"),
+    ):
+        result = json.loads(
+            SunoRetrieveTaskTool(api_key="key").run(task_id="existing", wait_seconds=10)
+        )
+    assert result["success"] and post.call_count == 2
+    assert all(call.kwargs["json"]["id"] == "existing" for call in post.call_args_list)
+    assert all(call.args[0].endswith("/suno/tasks") for call in post.call_args_list)
+
+
+def test_input_and_identity_checks():
+    with pytest.raises(ValueError):
+        SunoRetrieveTaskTool(api_key="key").run(task_id="existing", wait_seconds=241)
+    with patch("httpx.Client.post", return_value=reply(completed())):
+        with pytest.raises(ValueError, match="does not match"):
+            SunoRetrieveTaskTool(api_key="key").run(task_id="another")
+    with pytest.raises(ValueError, match="without Bearer"):
+        SunoRetrieveTaskTool(api_key="Bearer key")
+
+
+def test_missing_key_fails_before_network(monkeypatch):
+    monkeypatch.delenv("ACEDATACLOUD_API_KEY", raising=False)
+    with pytest.raises(ValueError, match="ACEDATACLOUD_API_KEY"):
+        SunoRetrieveTaskTool()
+
+
+def test_missing_submission_id_is_unknown_not_success():
+    with patch("httpx.Client.post", return_value=reply({"success": True})):
+        with pytest.raises(ValueError, match="No task ID"):
+            SunoGenerateMusicTool(api_key="key").run(prompt="piano", model="model")
+
+
+@pytest.mark.parametrize("where", ["top", "nested"])
+def test_failed_state_before_timestamp_is_terminal(where):
+    body = completed()
+    body["finished_at"] = None
+    if where == "top":
+        body["state"] = "failed"
+    else:
+        body["response"]["data"][0]["status"] = "failed"
+    with patch("httpx.Client.post", return_value=reply(body)):
+        result = SunoRetrieveTaskTool(api_key="key").run(task_id="existing")
+    assert isinstance(result, ToolFailure) and not result.retryable
+
+
+def test_no_terminal_audio_is_not_success():
+    body = completed()
+    body["response"]["data"] = []
+    with patch("httpx.Client.post", return_value=reply(body)):
+        result = SunoRetrieveTaskTool(api_key="key").run(task_id="existing")
+    assert isinstance(result, ToolFailure) and result.code == "missing_terminal_media"
+
+
+def test_error_and_cost_payloads_do_not_leak_private_fields():
+    with patch(
+        "httpx.Client.post",
+        return_value=reply({"error": "private service diagnostic secret-fixture"}, 403),
+    ):
+        with pytest.raises(ServiceHTTPError) as error:
+            SunoRetrieveTaskTool(api_key="secret-fixture").run(task_id="existing")
+    assert error.value.status_code == 403
+    assert "private service" not in str(error.value) and "secret-fixture" not in str(
+        error.value
+    )
+    body = completed()
+    body["response"]["cost"]["private_key"] = "private account data"
+    with patch("httpx.Client.post", return_value=reply(body)):
+        result = SunoRetrieveTaskTool(api_key="key").run(task_id="existing")
+    assert "private account data" not in result
+
+
+def test_management_token_is_rejected_before_network():
+    with pytest.raises(ValueError):
+        SunoRetrieveTaskTool(api_key="platform-management-fixture")