dragontts/app/api/v1/tts.py:235

• In /tts/create/bulk, invalid audio_base64 will raise during b64decode() and abort the entire batch with a 500 (it’s not caught by any except). Handle decode errors per-item (like other per-item errors) so one bad entry doesn’t fail the whole request.

            audio_override = None
            if req.audio_base64:
                audio_override = base64.b64decode(req.audio_base64)
            key, status, source, size, provider, model, _enc, _rate = (

dragontts/app/schemas/cache.py (1)

45-50: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Encode the documented response values with Literal.

CreateResponse and DeleteResponse currently accept arbitrary strings even though their docstrings/comments define fixed values. Invalid provider responses could therefore pass schema validation.

Proposed fix

-from pydantic import BaseModel
+from typing import Literal
+
+from pydantic import BaseModel

 class CreateResponse(BaseModel):
-    status: str
-    source: str
+    status: Literal["CREATED", "OVERRIDDEN"]
+    source: Literal["synth", "base64"]

 class DeleteResponse(BaseModel):
-    status: str  # "deleted" | "not_found"
+    status: Literal["deleted", "not_found"]

Also applies to: 59-60

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@dragontts/app/schemas/cache.py` around lines 45 - 50, Update the
CreateResponse and DeleteResponse Pydantic models to use typing.Literal for each
documented fixed-value field, including status and source, so schema validation
rejects unsupported provider response values. Preserve the exact allowed values
stated in each model’s docstring or comments.

.github/workflows/dragontts-docker-publish.yml (2)

33-34: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick win

Disable checkout credential persistence.

The static scan flags the default persisted Git credentials. This job executes repository-controlled Docker/build steps after checkout; even with contents: read, keeping the token in .git/config is unnecessary. Set persist-credentials: false to reduce later-step exposure. (github.com)

Suggested change

       - name: Checkout code
         uses: actions/checkout@v4
+        with:
+          persist-credentials: false

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/dragontts-docker-publish.yml around lines 33 - 34, Update
the actions/checkout@v4 step in the workflow to set persist-credentials to
false, preventing the checkout token from being retained for subsequent
repository-controlled Docker/build steps.

Source: Linters/SAST tools

---

61-62: 🔒 Security & Privacy | 🔵 Trivial

Retain supply-chain attestations unless intentionally disabled.

provenance: false and sbom: false remove build provenance and SBOM metadata from the published image. Enable them, or document the policy exception and compensating controls if Artifact Registry or deployment policy relies on those artifacts.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/dragontts-docker-publish.yml around lines 61 - 62, Update
the Docker publish configuration by enabling provenance and SBOM generation
instead of setting provenance and sbom to false. If they must remain disabled,
document the intentional policy exception and define the required compensating
controls.

dragontts/.python-version (1)

1-1: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Align the local and container Python targets.

The local configuration and README use Python 3.11, while the Docker image uses Python 3.12. Both satisfy the minimum, but this permits version-specific failures between development and production. Choose one supported target or explicitly test both. As per coding guidelines, Python 3.11 or later is required.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@dragontts/.python-version` at line 1, Align the Python version declared by
.python-version, the README, and the Docker image so local development and
production use the same supported target; choose either Python 3.11 or 3.12, or
explicitly configure and test both versions.

Source: Coding guidelines

dragontts/Dockerfile (2)

7-11: 🚀 Performance & Scalability | 🔵 Trivial | ⚡ Quick win

Use production-only uv synchronization.

uv sync and uv run include the default dev group, and project installs are editable by default. Set UV_NO_DEV=1 or pass --no-dev, and use --no-editable for the final sync so the runtime image does not ship development tooling or depend on an editable source install. (docs.astral.sh)

Suggested change

 ENV PYTHONUNBUFFERED=1 \
     PYTHONDONTWRITEBYTECODE=1 \
     UV_LINK_MODE=copy \
     UV_COMPILE_BYTECODE=1 \
+    UV_NO_DEV=1 \
     MALLOC_ARENA_MAX=4

Use --no-editable on the final sync.

Also applies to: 18-22, 29-29

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@dragontts/Dockerfile` around lines 7 - 11, Update the Dockerfile’s uv
installation and execution flow to exclude the default dev dependency group and
ensure the final project synchronization uses a non-editable install. Apply the
production-only configuration consistently to every relevant uv sync/uv run
invocation, including the final sync, while preserving the existing runtime
behavior.

---

13-13: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick win

Pin the uv tool image by digest.

ghcr.io/astral-sh/uv:0.5.11 is a mutable tag, so the build tool can change without a Dockerfile diff. Use a reviewed SHA256 digest for reproducible builds; uv’s Docker guidance recommends digest pinning when reproducibility matters. (docs.astral.sh)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@dragontts/Dockerfile` at line 13, Update the uv image reference in the
Dockerfile’s COPY directive to pin ghcr.io/astral-sh/uv:0.5.11 by its reviewed
SHA256 digest, preserving the existing source image version and destination
path.

pyproject.toml (1)

74-76: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add CI coverage for DragonTTS.

dragontts/ only has a build-and-push workflow in .github/workflows/dragontts-docker-publish.yml; it does not run tests or a type check. Since project-excludes = ["dragontts"] makes the main pyrefly job skip this self-contained service, add a DragonTTS test/type-check job, or verify and reference the separate pipeline before relying on this exclusion.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@pyproject.toml` around lines 74 - 76, Add CI coverage for the self-contained
dragontts service by introducing a test and type-check job, or verify and
explicitly reference an existing separate pipeline that performs both checks.
Keep the project-excludes entry aligned with that coverage so DragonTTS is not
left unchecked by the main pyrefly job.

dragontts/app/core/logging.py (3)

14-25: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Reads os.environ directly instead of going through the central Settings.

LOG_JSON is read via os.environ.get(...) here, bypassing the Settings object defined in app/core/config.py for this same service. As per coding guidelines, "Load ALL configuration from app/core/config/static.py using get_required_env() for mandatory variables; never import directly from os.environ elsewhere." Even accounting for Settings being this service's own convention (via pydantic-settings) rather than the monorepo's static.py/get_required_env() pattern, this file should route through Settings rather than adding a second, independent env-read path.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@dragontts/app/core/logging.py` around lines 14 - 25, Update the _JSON
configuration in the logging module to obtain LOG_JSON through the central
Settings configuration from app.core.config instead of reading os.environ
directly. Preserve the current default-to-JSON behavior and false-value handling
while removing the independent environment lookup and any now-unused os import.

Source: Coding guidelines

---

56-98: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚖️ Poor tradeoff

No contextvars-based structured logging context.

As per coding guidelines, "Use Loguru logging with contextvars for structured logging." This sink/interceptor setup has no logger.contextualize() or bound contextvars (e.g. request ID) for correlating log lines across a single request. Given the API layer isn't in this review cohort, this may already be handled elsewhere — worth confirming request-scoped context is bound somewhere before requests reach the sink.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@dragontts/app/core/logging.py` around lines 56 - 98, Add request-scoped
contextvars-based structured logging to the logging setup, binding context such
as the request ID before API request logs reach InterceptHandler and the
configured logger sink. Ensure the context is propagated across the request and
cleared afterward, while preserving the existing stdlib-to-Loguru forwarding and
re-entrancy behavior.

Source: Coding guidelines

---

100-100: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

__all__ not alphabetically sorted.

Ruff RUF022 flags this, but per a prior learning, this repo's CI lint gate runs Black/isort/autoflake/pyrefly, not Ruff, so this is a non-blocking cleanup item rather than a CI-breaker.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@dragontts/app/core/logging.py` at line 100, Sort the public symbols in
__all__ alphabetically, placing InterceptHandler before logger while preserving
the existing exports.

Sources: Learnings, Linters/SAST tools

dragontts/app/cache/key.py (1)

20-26: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick win

Literal invisible Unicode characters embedded directly in source.

_ZW contains raw zero-width/invisible characters typed directly into the string literal. This is functionally fine, but such literals are opaque in diffs/code review (an editor or reviewer can't easily see or verify which characters are actually present) — the same category of risk as "Trojan Source" invisible-character obfuscation, independent of whether Ruff runs in CI. Using explicit \uXXXX escapes preserves identical behavior while making the literal auditable.

🔒 Suggested fix

-_ZW = "​‌‍‎‏­"
+_ZW = "\u200b\u200c\u200d\u200e\u200f\ufeff\u00ad"
 _ZW_TABLE = str.maketrans("", "", _ZW)

(Verify the exact code points against the current literal before applying — this is illustrative.)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@dragontts/app/cache/key.py` around lines 20 - 26, Update the _ZW string in
dragontts/app/cache/key.py to represent each existing invisible character with
explicit Unicode escape sequences instead of literal invisible characters.
Preserve the exact current code points and keep _ZW_TABLE unchanged so stripping
behavior remains identical.

Source: Linters/SAST tools

dragontts/app/core/config.py (1)

224-236: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

configured_providers duplicates ProviderRegistry.build()'s credential checks.

Both this property and ProviderRegistry.build() (dragontts/app/providers/registry.py) independently re-implement the same 4 credential-presence conditions. If a provider/credential is added or changed in one place, the other can silently drift out of sync (e.g. configured_providers reporting a provider as live that build() didn't actually register, or vice versa).

Consider deriving one from the other — e.g. have ProviderRegistry.build() iterate settings.configured_providers instead of re-checking each credential inline.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@dragontts/app/core/config.py` around lines 224 - 236, The credential checks
in Config.configured_providers and ProviderRegistry.build are duplicated and can
drift. Update ProviderRegistry.build to derive its provider registration
decisions by iterating settings.configured_providers, reusing the existing
provider construction logic while removing the parallel inline credential
checks; preserve the current provider names and registration behavior.

dragontts/app/main.py (1)

117-133: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Shutdown exceptions are silently swallowed (no logging).

All four try/except (asyncio.CancelledError, Exception): pass blocks during shutdown drop any non-cancellation exception with zero visibility. If checkpoint_task, ttl_purge_task, slack_summary_task, or the final metadata.checkpoint() actually crashed (rather than just being cancelled), there's no log trail to diagnose it.

🪵 Suggested fix

     try:
         await checkpoint_task
-    except (asyncio.CancelledError, Exception):
-        pass
+    except asyncio.CancelledError:
+        pass
+    except Exception as e:
+        logger.debug(f"checkpoint task shutdown failed: {e}")
     try:
         await ttl_purge_task
-    except (asyncio.CancelledError, Exception):
-        pass
+    except asyncio.CancelledError:
+        pass
+    except Exception as e:
+        logger.debug(f"ttl purge task shutdown failed: {e}")
     try:
         await slack_summary_task
-    except (asyncio.CancelledError, Exception):
-        pass
+    except asyncio.CancelledError:
+        pass
+    except Exception as e:
+        logger.debug(f"slack summary task shutdown failed: {e}")
     await cache.stop()  # flush write-behind metrics (graceful shutdown loses none)
     try:
         await metadata.checkpoint()  # compact the WAL before worker conns close
-    except Exception:
-        pass
+    except Exception as e:
+        logger.debug(f"final WAL checkpoint failed: {e}")

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@dragontts/app/main.py` around lines 117 - 133, Update the shutdown exception
handlers around checkpoint_task, ttl_purge_task, slack_summary_task, and
metadata.checkpoint() to log non-cancellation exceptions while continuing
shutdown. Preserve cancellation handling without noisy error logs, and use the
module’s existing logging mechanism with task-specific context.

Source: Linters/SAST tools

dragontts/app/cache/service.py (1)

921-932: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Add type hints to this signature (and a few peers). Coding guidelines require type hints on all function signatures; _stream_coalesced declares none, and __init__ (metadata, blobs), _produce/_produce_native (record) are also untyped. Annotating these (e.g. req: TTSRequest, key: str, fut: asyncio.Future, of: OutputFormat, instance: BaseTTSProvider, return tuple[dict, AsyncGenerator[bytes, None]]) restores parity with the rest of the module.

As per coding guidelines: "Include required type hints on all function signatures".

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@dragontts/app/cache/service.py` around lines 921 - 932, 添加类型注解以覆盖模块中缺失的函数签名：为
_stream_coalesced 的 req、key、fut、of、provider、instance、model、params_canon、record
参数补充合适类型并保留现有返回类型，同时为 __init__ 的 metadata 和 blobs 以及 _produce/_produce_native 的
record 参数补充类型；复用模块已有的请求、输出格式、提供者和记录类型定义。

Source: Coding guidelines

dragontts/app/providers/registry.py (1)

83-85: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Isolate per-provider close failures.

If one provider's aclose() raises, the loop stops and remaining providers are never closed (leaked sockets/channels on shutdown). GeminiProvider.aclose() happens to self-guard, but this loop shouldn't rely on every current/future provider doing the same.

♻️ Proposed fix

     async def aclose_all(self) -> None:
         for provider in self._providers.values():
-            await provider.aclose()
+            try:
+                await provider.aclose()
+            except Exception as e:
+                logger.warning(f"Provider '{provider.name}' close failed: {e}")

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@dragontts/app/providers/registry.py` around lines 83 - 85, Update
Registry.aclose_all so each provider’s aclose failure is isolated and the loop
always continues closing every provider. Catch exceptions around the individual
await provider.aclose() call, while preserving the existing iteration and
allowing shutdown to complete after one provider fails.

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes