@laitszkin/apollo-toolkit 2.0.0

package/discover-edge-cases/references/code-edge-cases.md

@@ -0,0 +1,46 @@
+# Common Code-level Edge Cases (Reference List)
+
+## How to use
+- Pick only 2-5 items directly related to the current change.
+- Prioritize observable failures and high-risk inputs.
+
+## Input and typing
+- Null/missing fields: None/null, empty string, empty collection
+- Unexpected types: string-number mixing, boolean-integer confusion
+- Oversized input: long strings, large arrays, deeply nested objects
+- Encoding issues: UTF-8/non-ASCII, invisible characters
+
+## Boundaries and numerics
+- Off-by-one: index 0/1 and length boundaries
+- Overflow/underflow: integer/timestamp boundaries
+- NaN/Inf: floating-point special values
+- Precision loss: money/ratio calculations
+- Negative values where invalid
+
+## Structure and ordering
+- Duplicate elements: dedup/accumulation logic
+- Ordering assumptions: sorting stability, input-order dependence
+- Empty/singleton collections: reduce/min/max/avg behavior
+- Mutable/immutable mismatch: in-place mutation of input data
+
+## Exceptions and error handling
+- Parsing failures: date/timezone, JSON, CSV
+- External dependency failures: 429/500/timeout
+- Swallowed errors: `except pass` or missing logs
+- Recovery strategy: retry count, backoff, degradation
+
+## State and side effects
+- Reentrancy: same request invoked multiple times
+- Global state contamination: cache/singleton bleed-through
+- Mutable default parameters: Python list/dict defaults
+- Resource release: file/connection not closed
+
+## Security and validation
+- Insufficient authorization behavior
+- Validation bypass via null/0/False
+- Path/injection risks from string concatenation
+
+## Performance and limits
+- N+1 query patterns inside loops
+- Large-data stress: timeout/memory pressure
+- Hotspots: lock contention under high-frequency calls

package/docs-to-voice/.env.example

@@ -0,0 +1,106 @@
+# docs-to-voice environment example
+#
+# MODE:
+# - say: macOS built-in `say`
+# - api: Alibaba Cloud Model Studio (Bailian) TTS API
+DOCS_TO_VOICE_MODE="say"
+
+# -----------------------------
+# say mode defaults
+# -----------------------------
+# If --voice is provided, it overrides this value.
+DOCS_TO_VOICE_VOICE="Eddy (中文（台灣）)"
+
+# -----------------------------
+# api mode defaults (Model Studio)
+# -----------------------------
+# Required for mode=api.
+DASHSCOPE_API_KEY=""
+#
+# Region endpoint (direct Model Studio API; choose ONE):
+# - China Mainland (Beijing):
+#   https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
+# - International (Singapore):
+#   https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
+# - US (Virginia):
+#   https://dashscope-us.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
+#
+# NOTE:
+# - API Key and endpoint region must match.
+# - If you use OpenAI-compatible mode in other clients, base URL is:
+#   - https://dashscope.aliyuncs.com/compatible-mode/v1
+#   - https://dashscope-intl.aliyuncs.com/compatible-mode/v1
+#   - https://dashscope-us.aliyuncs.com/compatible-mode/v1
+DOCS_TO_VOICE_API_ENDPOINT="https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation"
+
+# Model options (choose one available in your region/account):
+# - qwen3-tts
+# - qwen3-tts-flash
+# - qwen3-tts-instruct-flash
+# - qwen-tts
+# - qwen-tts-latest
+DOCS_TO_VOICE_API_MODEL="qwen3-tts"
+
+# Voice options (DOCS_TO_VOICE_API_VOICE) and style:
+# - Cherry: 芊悅｜陽光積極、親切自然小姐姐（女）
+# - Serena: 蘇瑤｜溫柔小姐姐（女）
+# - Ethan: 晨煦｜陽光溫暖、朝氣男聲（男）
+# - Chelsie: 千雪｜二次元虛擬女友（女）
+# - Momo: 茉兔｜撒嬌搞怪（女）
+# - Vivian: 十三｜拽拽可愛小暴躁（女）
+# - Moon: 月白｜率性帥氣（男）
+# - Maia: 四月｜知性溫柔（女）
+# - Kai: 凱｜通用中性
+# - Nofish: 不吃魚｜不會翹舌音的設計師（男）
+# - Bella: 萌寶｜小蘿莉感（女）
+# - Jennifer: 詹妮弗｜品牌感美語女聲（女）
+# - Ryan: 甜茶｜節奏感強、戲感足（男）
+# - Katerina: 卡捷琳娜｜御姐音色（女）
+# - Aiden: 艾登｜美語暖男（男）
+# - Eldric Sage: 滄明子｜沉穩睿智老者（男）
+# - Mia: 乖小妹｜溫順乖巧（女）
+# - Mochi: 沙小彌｜早慧童聲（男）
+# - Bellona: 燕錚鶯｜洪亮、戲劇張力強（女）
+# - Vincent: 田叔｜沙啞煙嗓（男）
+# - Bunny: 萌小姬｜萌系蘿莉（女）
+# - Neil: 阿聞｜新聞主持風（男）
+# - Elias: 墨講師｜知性講解（女）
+# - Arthur: 徐大爺｜質樸長者敘事（男）
+# - Nini: 鄰家妹妹｜甜妹黏糯感（女）
+# - Ebona: 詭婆婆｜驚悚詭譎（女）
+# - Seren: 小婉｜助眠舒緩（女）
+# - Pip: 頑屁小孩｜調皮童真（男）
+# - Stella: 少女阿月｜元氣少女（女）
+# - Bodega: 博德加｜熱情西語大叔（男）
+# - Sonrisa: 索尼莎｜熱情拉美女聲（女）
+# - Alek: 阿列克｜冷暖反差俄語男聲（男）
+# - Dolce: 多爾切｜慵懶義式大叔（男）
+# - Sohee: 素熙｜溫柔開朗韓系女聲（女）
+# - Ono Anna: 小野杏｜鬼靈精怪日系女聲（女）
+# - Lenn: 萊恩｜理性德系青年（男）
+# - Emilien: 埃米爾安｜法式浪漫男聲（男）
+# - Andre: 安德雷｜沉穩磁性男聲（男）
+# - Radio Gol: 拉迪奧·戈爾｜足球解說風
+# - Jada: 上海-阿珍｜上海話（女）
+# - Dylan: 北京-曉東｜北京話（男）
+# - Li: 南京-老李｜南京話（男）
+# - Marcus: 陝西-秦川｜陝西話（男）
+# - Roy: 閩南-阿杰｜閩南語（男）
+# - Peter: 天津-李彼得｜天津話相聲風（男）
+# - Sunny: 四川-晴兒｜四川話甜美女聲（女）
+# - Eric: 四川-程川｜四川話（男）
+# - Rocky: 粵語-阿強｜粵語（男）
+# - Kiki: 粵語-阿清｜粵語（女）
+DOCS_TO_VOICE_API_VOICE="Cherry"
+
+# Long text chunking:
+# - Empty means api mode auto-discovers model max input length before chunking.
+# - Set a positive integer to force a custom chunk limit.
+# - 0 disables chunking.
+DOCS_TO_VOICE_MAX_CHARS=""
+
+# Optional post-process speech speed multiplier:
+# - Empty keeps original speed.
+# - Set a positive number (e.g. 1.2 faster, 0.8 slower).
+# - Requires ffmpeg when value is not 1.
+DOCS_TO_VOICE_SPEECH_RATE=""

package/docs-to-voice/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on Keep a Changelog.
+
+## [Unreleased]
+
+## [0.5.0] - 2026-02-18
+
+### Added
+- Added `--speech-rate` (and `DOCS_TO_VOICE_SPEECH_RATE`) for optional ffmpeg-based post-process speed adjustment.
+- Added speech-rate unit tests for input validation, filter-chain generation, and timeline duration scaling.
+
+### Fixed
+- Rejected non-finite `--speech-rate` values (for example `nan`/`inf`) to avoid invalid ffmpeg filter generation.
+
+## [0.4.0] - 2026-02-15
+
+### Changed
+- API mode now sends TTS requests sentence-by-sentence and still merges all generated audio into one final output file.
+- API sentence timelines now prefer measured per-sentence audio durations to produce more precise subtitle timestamps.
+
+### Added
+- Added `split_text_into_api_sentence_requests` to keep sentence boundaries in API synthesis while still splitting only oversized sentences by `--max-chars`.
+- Added timeline tests covering sentence-based API request splitting and sentence-duration timestamp output.
+
+## [0.3.0] - 2026-02-15
+
+### Added
+- Added API-mode max-length discovery that first checks model catalog metadata and then probes API length validation when metadata is unavailable.
+
+### Changed
+- API mode now auto-splits long text by discovered max input length when `--max-chars` (or `DOCS_TO_VOICE_MAX_CHARS`) is not provided.
+- API chunking now applies weighted input-unit counting for CJK text to match qwen3-tts length rules.
+
+### Fixed
+- Added explicit `0` handling for `--max-chars` / `DOCS_TO_VOICE_MAX_CHARS` so users can still disable chunking.
+- Wrapped transient HTTP disconnect exceptions as user-facing CLI errors instead of raw tracebacks.
+
+## [0.2.1] - 2026-02-15
+
+### Added
+- Added unit tests for `resolve_setting` to lock configuration precedence and fallback behavior.
+
+### Fixed
+- Fixed configuration precedence so omitted CLI mode/options now prefer `.env` values before shell environment variables.
+- Prevented blank CLI values from incorrectly overriding `.env` settings.
+
+## [0.2.0] - 2026-02-14
+
+### Added
+- Added `scripts/docs_to_voice.py` as the primary CLI implementation for both `say` and `api` modes.
+- Added built-in Python API handling for Model Studio requests/responses (URL and base64 audio paths) to simplify API mode operations.
+- Added long-text chunking via `--max-chars` and `DOCS_TO_VOICE_MAX_CHARS`, with automatic per-chunk synthesis and final audio concatenation.
+
+### Changed
+- Replaced `scripts/docs_to_voice.sh` logic with a lightweight compatibility wrapper that delegates to the Python CLI.
+- Updated README, SKILL, `.env.example`, and agent prompt guidance to use the Python script as the default entrypoint and document chunked generation for long text.
+
+## [0.1.0] - 2026-02-14
+
+### Added
+- Added `api` mode for Alibaba Cloud Model Studio TTS, including endpoint/model/voice configuration and API key support.
+- Added sentence-level timeline outputs for each generated audio file: `.timeline.json` and `.srt`.
+- Added timeline metadata with per-sentence start/end offsets (seconds and milliseconds) to support subtitle alignment.
+
+### Changed
+- Updated `.env.example` with full mode selection, endpoint guidance, and API voice/model defaults.
+- Updated skill and README documentation to describe dual-mode generation and subtitle timeline artifacts.
+- Updated agent default prompt to include timeline generation behavior.

package/docs-to-voice/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tszkinlai
+
+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.

package/docs-to-voice/README.md

@@ -0,0 +1,118 @@
+# docs-to-voice
+
+Convert text into voice files and always write outputs to:
+
+`project_dir/audio/{project_name}/`
+
+Each run also generates subtitle timeline files in the same folder:
+
+- `{audio_name_without_extension}.timeline.json`: sentence-level subtitle start/end timestamps (seconds and milliseconds)
+- `{audio_name_without_extension}.srt`: ready-to-use subtitle track file
+
+Two modes are supported:
+
+- `say`: built-in macOS `say`
+- `api`: Alibaba Cloud Model Studio TTS API (for example `qwen3-tts`)
+
+## Features
+
+- Supports both `--text` and `--input-file`
+- Supports `--mode say|api`
+- Supports `.env` for API key/model/voice settings
+- Supports `--output-name` for deterministic output filename
+- `say` mode enables punctuation prosody enhancement by default (disable with `--no-auto-prosody`)
+- `api` mode sends sentence-level TTS requests and merges output into one audio file
+- `api` mode auto-detects model max input length and segments over-limit sentences
+- `--max-chars` (or `.env`) can override segment length limit manually
+- `--speech-rate` (or `.env`) can apply post-processing speech-rate adjustment (requires `ffmpeg`)
+- API timeline prefers real per-sentence audio duration for higher subtitle precision
+- Automatically outputs sentence-level timeline files (`.timeline.json` + `.srt`)
+
+## Requirements
+
+- `say` mode: macOS + `say` + `python3`
+- `api` mode: `python3` + Model Studio API key
+- Long-text merge workflow: `ffmpeg` recommended (especially for AIFF output)
+
+## Quick start
+
+### 1) say mode
+
+```bash
+python3 scripts/docs_to_voice.py \
+  --project-dir "/path/to/project" \
+  --mode say \
+  --text "Hello, this is a voice synthesis test."
+```
+
+### 2) api mode (Model Studio)
+
+```bash
+python3 scripts/docs_to_voice.py \
+  --project-dir "/path/to/project" \
+  --mode api \
+  --text "Hello, this is a qwen3-tts test."
+```
+
+> Compatibility note: `scripts/docs_to_voice.sh` still works and internally delegates to the Python script.
+
+## `.env` settings
+
+1. Copy template
+
+```bash
+cp .env.example .env
+```
+
+2. Configure mode and API parameters (example)
+
+```env
+DOCS_TO_VOICE_MODE="api"
+DASHSCOPE_API_KEY="sk-xxx"
+DOCS_TO_VOICE_API_ENDPOINT="https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation"
+DOCS_TO_VOICE_API_MODEL="qwen3-tts"
+DOCS_TO_VOICE_API_VOICE="Cherry"
+DOCS_TO_VOICE_MAX_CHARS=""
+DOCS_TO_VOICE_SPEECH_RATE=""
+```
+
+> CLI args `--mode`, `--api-model`, `--api-voice`, `--api-endpoint`, and `--speech-rate` override `.env`. If omitted, values are loaded from `.env` first, then fallback to same-name shell environment variables.
+
+## Parameters
+
+```text
+--project-dir DIR         required, project root path
+--text TEXT               choose one of --text / --input-file
+--input-file FILE         choose one of --text / --input-file
+--project-name NAME       optional, defaults to project_dir folder name
+--output-name NAME        optional, defaults to voice-YYYYmmdd-HHMMSS + mode extension
+--env-file FILE           optional, default: skill-folder/.env
+--mode MODE               optional, say or api
+--voice NAME              optional for say mode
+--rate N                  optional for say mode
+--speech-rate N           optional, speech-rate multiplier (>0; 1.2=faster, 0.8=slower; requires ffmpeg)
+--api-endpoint URL        optional for api mode (Model Studio endpoint)
+--api-model NAME          optional for api mode
+--api-voice NAME          optional for api mode
+--max-chars N             optional, manual segment limit (api mode auto-detects if omitted; 0 means no segmentation)
+--no-auto-prosody         optional for say mode, disable punctuation prosody enhancement
+--force                   optional, overwrite existing files
+```
+
+## Long-text notes
+
+- API mode uses sentence-level TTS by default and only segments when a sentence exceeds model limits.
+- If you already know a suitable limit, set `--max-chars` (or `DOCS_TO_VOICE_MAX_CHARS` in `.env`).
+- For many `qwen3-tts` models, CJK chars typically count as 2 units and other chars as 1 unit; this script segments using that convention.
+
+## Endpoint note
+
+If you need direct Model Studio `qwen3-tts` integration, use:
+
+`https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation`
+
+`https://dashscope-intl.aliyuncs.com/compatible-mode/v1` is the OpenAI-compatible base URL (typically for chat/completions), not the default direct Model Studio TTS endpoint used by this script.
+
+## License
+
+MIT License (see `LICENSE`).

package/docs-to-voice/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: docs-to-voice
+description: Convert text and document content into audio files and sentence-level subtitle timelines under project_dir/audio/{project_name}/. Supports both macOS say and Alibaba Cloud Model Studio API modes.
+---
+
+# Docs to Voice
+
+## Dependencies
+
+- Required: none.
+- Conditional: none.
+- Optional: none.
+- Fallback: not applicable.
+
+## Standards
+
+- Evidence: Confirm `project_dir`, input source, mode, and environment-backed settings before generation.
+- Execution: Use `scripts/docs_to_voice.py` to write audio plus matching timeline and subtitle files under `project_dir/audio/{project_name}/`.
+- Quality: Respect mode-specific options, sentence splitting rules, and post-process requirements such as `ffmpeg` for speed changes.
+- Output: Return the absolute output audio path together with the generated `.timeline.json` and `.srt` companions.
+
+## Overview
+
+Use `scripts/docs_to_voice.py` to convert raw text or text files into audio and always save under:
+
+`project_dir/audio/{project_name}/`
+
+Alongside each audio file, the script also writes:
+
+- `{audio_name_without_extension}.timeline.json`
+- `{audio_name_without_extension}.srt`
+
+Modes:
+
+- `say`: local macOS `say`
+- `api`: Alibaba Cloud Model Studio TTS API (for example `qwen3-tts`)
+
+## Workflow
+
+1. Collect inputs.
+   - Require `project_dir`.
+   - Accept either raw text or one input text file.
+   - Set `project_name`; default to basename of `project_dir`.
+
+2. Select mode.
+   - `--mode say` for local generation.
+   - `--mode api` for Model Studio API generation.
+   - If omitted, load `DOCS_TO_VOICE_MODE` from `.env`, then shell environment variables; fallback `say`.
+
+3. Prepare output path.
+   - Build `project_dir/audio/{project_name}/`.
+   - Create directory if it does not exist.
+
+4. Generate audio.
+   - `say` mode supports `--voice`, `--rate`, and punctuation-pause enhancement.
+   - `api` mode supports `--api-endpoint`, `--api-model`, `--api-voice`, and reads `DASHSCOPE_API_KEY`.
+   - `api` mode sends one request per sentence and concatenates all sentence audio into one final file.
+   - `api` mode auto discovers model max input length; only oversized sentences are split by that limit.
+   - `--max-chars` (or `DOCS_TO_VOICE_MAX_CHARS`) can override the sentence split limit; `0` disables chunking.
+   - `--speech-rate` (or `DOCS_TO_VOICE_SPEECH_RATE`) applies optional post-process speed adjustment and requires `ffmpeg` when value is not `1`.
+   - API splitting uses model counting rules (for `qwen3-tts`, CJK chars count as 2 units).
+
+5. Generate sentence-level timeline files.
+   - Write JSON timeline and SRT subtitle files next to audio output.
+   - In `api` mode, timeline start/end uses per-sentence audio durations whenever available.
+
+6. Return completion details.
+   - Report absolute output audio path.
+
+## Script Reference
+
+`scripts/docs_to_voice.py` flags:
+
+- `--project-dir` (required)
+- `--project-name` (optional)
+- `--text` or `--input-file` (exactly one required)
+- `--env-file` (optional, default: `skill_dir/.env`)
+- `--mode` (`say|api`, optional)
+- `--voice` (optional, say mode)
+- `--rate` (optional, say mode)
+- `--speech-rate` (optional, post-process speed multiplier)
+- `--api-endpoint` (optional, api mode)
+- `--api-model` (optional, api mode)
+- `--api-voice` (optional, api mode)
+- `--max-chars` (optional, auto chunking threshold for long text)
+- `--output-name` (optional)
+- `--no-auto-prosody` (optional, say mode)
+- `--force` (optional)
+
+Environment variables:
+
+- `DOCS_TO_VOICE_MODE`
+- `DOCS_TO_VOICE_VOICE`
+- `DOCS_TO_VOICE_API_ENDPOINT`
+- `DOCS_TO_VOICE_API_MODEL`
+- `DOCS_TO_VOICE_API_VOICE`
+- `DOCS_TO_VOICE_MAX_CHARS`
+- `DOCS_TO_VOICE_SPEECH_RATE`
+- `DASHSCOPE_API_KEY`
+
+## Troubleshooting
+
+- `say` mode: confirm `command -v say` and `command -v python3`.
+- `api` mode: confirm `command -v python3` and valid `DASHSCOPE_API_KEY`.
+- Long-text chunk merge (especially AIFF output): recommend `command -v ffmpeg`.
+- If output exists, use `--force` or a new `--output-name`.
+- `scripts/docs_to_voice.sh` is kept as a compatibility wrapper for existing workflows.

package/docs-to-voice/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Docs to Voice"
+  short_description: "Convert text into voice files with macOS say or Model Studio API"
+  default_prompt: "Use $docs-to-voice to convert text into an audio file saved under project_dir/audio/{project_name}/, generate sentence timelines (.timeline.json and .srt), synthesize API mode sentence-by-sentence, and concatenate all generated parts into one final audio file."