diff --git a/.github/workflows/update-readme.yml b/.github/workflows/markdown-code-runner.yml similarity index 74% rename from .github/workflows/update-readme.yml rename to .github/workflows/markdown-code-runner.yml index b3ff51f28..81b672bea 100644 --- a/.github/workflows/update-readme.yml +++ b/.github/workflows/markdown-code-runner.yml @@ -1,4 +1,4 @@ -name: Update README.md +name: Update docs on: push: @@ -7,7 +7,7 @@ on: pull_request: jobs: - update_readme: + update_docs: runs-on: macos-latest steps: - name: Check out repository @@ -22,26 +22,27 @@ jobs: - name: Install uv uses: astral-sh/setup-uv@v6 - - name: Run markdown-code-runner + - name: Run update_docs.py env: TERM: dumb NO_COLOR: 1 TERMINAL_WIDTH: 90 run: | - uvx --with . markdown-code-runner README.md - sed -i '' 's/[[:space:]]*$//' README.md + uv sync + uv run python docs/update_docs.py + find . -name "*.md" -exec sed -i '' 's/[[:space:]]*$//' {} \; - - name: Commit updated README.md + - name: Commit updated docs id: commit run: | - git add README.md + git add -A git config --local user.email "github-actions[bot]@users.noreply.github.com" git config --local user.name "github-actions[bot]" if git diff --quiet && git diff --staged --quiet; then - echo "No changes in README.md, skipping commit." + echo "No changes in docs, skipping commit." echo "commit_status=skipped" >> $GITHUB_ENV else - git commit -m "Update README.md" + git commit -m "Update auto-generated docs" echo "commit_status=committed" >> $GITHUB_ENV fi diff --git a/README.md b/README.md index 7b6efc50b..e3bd6c11b 100644 --- a/README.md +++ b/README.md @@ -465,7 +465,7 @@ the `[defaults]` section of your configuration file. │ 'gemini'). │ │ [default: ollama] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: Ollama (local) ──────────────────────────────────────────╮ +╭─ LLM: Ollama ────────────────────────────────────────────────────────────────╮ │ --llm-ollama-model TEXT The Ollama model to use. Default is │ │ gemma3:4b. │ │ [default: gemma3:4b] │ @@ -473,7 +473,7 @@ the `[defaults]` section of your configuration file. │ http://localhost:11434. │ │ [default: http://localhost:11434] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: OpenAI ──────────────────────────────────────────────────╮ +╭─ LLM: OpenAI-compatible ─────────────────────────────────────────────────────╮ │ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ │ [default: gpt-5-mini] │ │ --openai-api-key TEXT Your OpenAI API key. Can also be set with │ @@ -484,7 +484,7 @@ the `[defaults]` section of your configuration file. │ http://localhost:8080/v1). │ │ [env var: OPENAI_BASE_URL] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: Gemini ──────────────────────────────────────────────────╮ +╭─ LLM: Gemini ────────────────────────────────────────────────────────────────╮ │ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ │ [default: gemini-2.5-flash] │ │ --gemini-api-key TEXT Your Gemini API key. Can also be set with │ @@ -545,9 +545,14 @@ the `[defaults]` section of your configuration file. Wyoming ASR Client for streaming microphone audio to a transcription server. ╭─ Options ────────────────────────────────────────────────────────────────────╮ -│ --extra-instructions TEXT Additional instructions for the LLM to │ -│ process the transcription. │ -│ --help -h Show this message and exit. │ +│ --help -h Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM Configuration ──────────────────────────────────────────────────────────╮ +│ --extra-instructions TEXT Additional instructions for the │ +│ LLM to process the transcription. │ +│ --llm --no-llm Use an LLM to process the │ +│ transcript. │ +│ [default: no-llm] │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Audio Recovery ─────────────────────────────────────────────────────────────╮ │ --from-file PATH Transcribe audio from a │ @@ -571,20 +576,20 @@ the `[defaults]` section of your configuration file. │ 'gemini'). │ │ [default: ollama] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration ──────────────────────────────────────────────────╮ +╭─ Audio Input ────────────────────────────────────────────────────────────────╮ │ --input-device-index INTEGER Index of the audio input device to use. │ │ --input-device-name TEXT Device name keywords for partial │ │ matching. │ │ --list-devices List available audio input and output │ │ devices and exit. │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration: Wyoming (local) ─────────────────────────────────╮ +╭─ Audio Input: Wyoming ───────────────────────────────────────────────────────╮ │ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ │ [default: localhost] │ │ --asr-wyoming-port INTEGER Wyoming ASR server port. │ │ [default: 10300] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration: OpenAI ──────────────────────────────────────────╮ +╭─ Audio Input: OpenAI-compatible ─────────────────────────────────────────────╮ │ --asr-openai-model TEXT The OpenAI model to use for ASR │ │ (transcription). │ │ [default: whisper-1] │ @@ -594,7 +599,7 @@ the `[defaults]` section of your configuration file. │ --asr-openai-prompt TEXT Custom prompt to guide transcription │ │ (optional). │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: Ollama (local) ──────────────────────────────────────────╮ +╭─ LLM: Ollama ────────────────────────────────────────────────────────────────╮ │ --llm-ollama-model TEXT The Ollama model to use. Default is │ │ gemma3:4b. │ │ [default: gemma3:4b] │ @@ -602,7 +607,7 @@ the `[defaults]` section of your configuration file. │ http://localhost:11434. │ │ [default: http://localhost:11434] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: OpenAI ──────────────────────────────────────────────────╮ +╭─ LLM: OpenAI-compatible ─────────────────────────────────────────────────────╮ │ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ │ [default: gpt-5-mini] │ │ --openai-api-key TEXT Your OpenAI API key. Can also be set with │ @@ -613,18 +618,14 @@ the `[defaults]` section of your configuration file. │ http://localhost:8080/v1). │ │ [env var: OPENAI_BASE_URL] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: Gemini ──────────────────────────────────────────────────╮ +╭─ LLM: Gemini ────────────────────────────────────────────────────────────────╮ │ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ │ [default: gemini-2.5-flash] │ │ --gemini-api-key TEXT Your Gemini API key. Can also be set with │ │ the GEMINI_API_KEY environment variable. │ │ [env var: GEMINI_API_KEY] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration ──────────────────────────────────────────────────────────╮ -│ --llm --no-llm Use an LLM to process the transcript. │ -│ [default: no-llm] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Process Management Options ─────────────────────────────────────────────────╮ +╭─ Process Management ─────────────────────────────────────────────────────────╮ │ --stop Stop any running background process. │ │ --status Check if a background process is running. │ │ --toggle Toggle the background process on/off. If the process is │ @@ -763,20 +764,20 @@ uv tool install "agent-cli[vad]" │ 'gemini'). │ │ [default: ollama] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration ──────────────────────────────────────────────────╮ +╭─ Audio Input ────────────────────────────────────────────────────────────────╮ │ --input-device-index INTEGER Index of the audio input device to use. │ │ --input-device-name TEXT Device name keywords for partial │ │ matching. │ │ --list-devices List available audio input and output │ │ devices and exit. │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration: Wyoming (local) ─────────────────────────────────╮ +╭─ Audio Input: Wyoming ───────────────────────────────────────────────────────╮ │ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ │ [default: localhost] │ │ --asr-wyoming-port INTEGER Wyoming ASR server port. │ │ [default: 10300] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration: OpenAI ──────────────────────────────────────────╮ +╭─ Audio Input: OpenAI-compatible ─────────────────────────────────────────────╮ │ --asr-openai-model TEXT The OpenAI model to use for ASR │ │ (transcription). │ │ [default: whisper-1] │ @@ -786,7 +787,7 @@ uv tool install "agent-cli[vad]" │ --asr-openai-prompt TEXT Custom prompt to guide transcription │ │ (optional). │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: Ollama (local) ──────────────────────────────────────────╮ +╭─ LLM: Ollama ────────────────────────────────────────────────────────────────╮ │ --llm-ollama-model TEXT The Ollama model to use. Default is │ │ gemma3:4b. │ │ [default: gemma3:4b] │ @@ -794,7 +795,7 @@ uv tool install "agent-cli[vad]" │ http://localhost:11434. │ │ [default: http://localhost:11434] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: OpenAI ──────────────────────────────────────────────────╮ +╭─ LLM: OpenAI-compatible ─────────────────────────────────────────────────────╮ │ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ │ [default: gpt-5-mini] │ │ --openai-api-key TEXT Your OpenAI API key. Can also be set with │ @@ -805,7 +806,7 @@ uv tool install "agent-cli[vad]" │ http://localhost:8080/v1). │ │ [env var: OPENAI_BASE_URL] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: Gemini ──────────────────────────────────────────────────╮ +╭─ LLM: Gemini ────────────────────────────────────────────────────────────────╮ │ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ │ [default: gemini-2.5-flash] │ │ --gemini-api-key TEXT Your Gemini API key. Can also be set with │ @@ -816,7 +817,7 @@ uv tool install "agent-cli[vad]" │ --llm --no-llm Use an LLM to process the transcript. │ │ [default: no-llm] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Process Management Options ─────────────────────────────────────────────────╮ +╭─ Process Management ─────────────────────────────────────────────────────────╮ │ --stop Stop any running background process. │ │ --status Check if a background process is running. │ ╰──────────────────────────────────────────────────────────────────────────────╯ @@ -883,7 +884,7 @@ uv tool install "agent-cli[vad]" │ 'kokoro'). │ │ [default: wyoming] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration ─────────────────────────────────────────╮ +╭─ Audio Output ───────────────────────────────────────────────────────────────╮ │ --output-device-index INTEGER Index of the audio output device to │ │ use for TTS. │ │ --output-device-name TEXT Output device name keywords for │ @@ -893,7 +894,7 @@ uv tool install "agent-cli[vad]" │ speed). │ │ [default: 1.0] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration: Wyoming (local) ────────────────────────╮ +╭─ Audio Output: Wyoming ──────────────────────────────────────────────────────╮ │ --tts-wyoming-ip TEXT Wyoming TTS server IP address. │ │ [default: localhost] │ │ --tts-wyoming-port INTEGER Wyoming TTS server port. │ @@ -904,7 +905,7 @@ uv tool install "agent-cli[vad]" │ 'en_US'). │ │ --tts-wyoming-speaker TEXT Speaker name for Wyoming TTS voice. │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration: OpenAI ─────────────────────────────────╮ +╭─ Audio Output: OpenAI-compatible ────────────────────────────────────────────╮ │ --tts-openai-model TEXT The OpenAI model to use for TTS. │ │ [default: tts-1] │ │ --tts-openai-voice TEXT The voice to use for OpenAI TTS. │ @@ -913,7 +914,7 @@ uv tool install "agent-cli[vad]" │ API (e.g., http://localhost:8000/v1 for a │ │ proxy). │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration: Kokoro ─────────────────────────────────╮ +╭─ Audio Output: Kokoro ───────────────────────────────────────────────────────╮ │ --tts-kokoro-model TEXT The Kokoro model to use for TTS. │ │ [default: kokoro] │ │ --tts-kokoro-voice TEXT The voice to use for Kokoro TTS. │ @@ -921,7 +922,7 @@ uv tool install "agent-cli[vad]" │ --tts-kokoro-host TEXT The base URL for the Kokoro API. │ │ [default: http://localhost:8880/v1] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration ──────────────────────────────────────────────────╮ +╭─ Audio Input ────────────────────────────────────────────────────────────────╮ │ --list-devices List available audio input and output devices and │ │ exit. │ ╰──────────────────────────────────────────────────────────────────────────────╯ @@ -935,7 +936,7 @@ uv tool install "agent-cli[vad]" │ --print-args Print the command line arguments, including │ │ variables taken from the configuration file. │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Process Management Options ─────────────────────────────────────────────────╮ +╭─ Process Management ─────────────────────────────────────────────────────────╮ │ --stop Stop any running background process. │ │ --status Check if a background process is running. │ │ --toggle Toggle the background process on/off. If the process is │ @@ -1007,25 +1008,25 @@ uv tool install "agent-cli[vad]" │ 'kokoro'). │ │ [default: wyoming] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration ──────────────────────────────────────────────────╮ +╭─ Audio Input ────────────────────────────────────────────────────────────────╮ │ --input-device-index INTEGER Index of the audio input device to use. │ │ --input-device-name TEXT Device name keywords for partial │ │ matching. │ │ --list-devices List available audio input and output │ │ devices and exit. │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration: Wyoming (local) ─────────────────────────────────╮ +╭─ Audio Input: Wyoming ───────────────────────────────────────────────────────╮ │ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ │ [default: localhost] │ │ --asr-wyoming-port INTEGER Wyoming ASR server port. │ │ [default: 10300] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration: OpenAI ──────────────────────────────────────────╮ +╭─ Audio Input: OpenAI-compatible ─────────────────────────────────────────────╮ │ --asr-openai-model TEXT The OpenAI model to use for ASR │ │ (transcription). │ │ [default: whisper-1] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: Ollama (local) ──────────────────────────────────────────╮ +╭─ LLM: Ollama ────────────────────────────────────────────────────────────────╮ │ --llm-ollama-model TEXT The Ollama model to use. Default is │ │ gemma3:4b. │ │ [default: gemma3:4b] │ @@ -1033,7 +1034,7 @@ uv tool install "agent-cli[vad]" │ http://localhost:11434. │ │ [default: http://localhost:11434] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: OpenAI ──────────────────────────────────────────────────╮ +╭─ LLM: OpenAI-compatible ─────────────────────────────────────────────────────╮ │ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ │ [default: gpt-5-mini] │ │ --openai-api-key TEXT Your OpenAI API key. Can also be set with │ @@ -1044,14 +1045,14 @@ uv tool install "agent-cli[vad]" │ http://localhost:8080/v1). │ │ [env var: OPENAI_BASE_URL] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: Gemini ──────────────────────────────────────────────────╮ +╭─ LLM: Gemini ────────────────────────────────────────────────────────────────╮ │ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ │ [default: gemini-2.5-flash] │ │ --gemini-api-key TEXT Your Gemini API key. Can also be set with │ │ the GEMINI_API_KEY environment variable. │ │ [env var: GEMINI_API_KEY] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration ─────────────────────────────────────────╮ +╭─ Audio Output ───────────────────────────────────────────────────────────────╮ │ --tts --no-tts Enable text-to-speech for │ │ responses. │ │ [default: no-tts] │ @@ -1064,7 +1065,7 @@ uv tool install "agent-cli[vad]" │ 0.5 = half speed). │ │ [default: 1.0] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration: Wyoming (local) ────────────────────────╮ +╭─ Audio Output: Wyoming ──────────────────────────────────────────────────────╮ │ --tts-wyoming-ip TEXT Wyoming TTS server IP address. │ │ [default: localhost] │ │ --tts-wyoming-port INTEGER Wyoming TTS server port. │ @@ -1075,7 +1076,7 @@ uv tool install "agent-cli[vad]" │ 'en_US'). │ │ --tts-wyoming-speaker TEXT Speaker name for Wyoming TTS voice. │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration: OpenAI ─────────────────────────────────╮ +╭─ Audio Output: OpenAI-compatible ────────────────────────────────────────────╮ │ --tts-openai-model TEXT The OpenAI model to use for TTS. │ │ [default: tts-1] │ │ --tts-openai-voice TEXT The voice to use for OpenAI TTS. │ @@ -1084,7 +1085,7 @@ uv tool install "agent-cli[vad]" │ API (e.g., http://localhost:8000/v1 for a │ │ proxy). │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration: Kokoro ─────────────────────────────────╮ +╭─ Audio Output: Kokoro ───────────────────────────────────────────────────────╮ │ --tts-kokoro-model TEXT The Kokoro model to use for TTS. │ │ [default: kokoro] │ │ --tts-kokoro-voice TEXT The voice to use for Kokoro TTS. │ @@ -1092,7 +1093,7 @@ uv tool install "agent-cli[vad]" │ --tts-kokoro-host TEXT The base URL for the Kokoro API. │ │ [default: http://localhost:8880/v1] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Process Management Options ─────────────────────────────────────────────────╮ +╭─ Process Management ─────────────────────────────────────────────────────────╮ │ --stop Stop any running background process. │ │ --status Check if a background process is running. │ │ --toggle Toggle the background process on/off. If the process is │ @@ -1171,7 +1172,7 @@ uv tool install "agent-cli[vad]" │ 'kokoro'). │ │ [default: wyoming] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Wake Word Options ──────────────────────────────────────────────────────────╮ +╭─ Wake Word ──────────────────────────────────────────────────────────────────╮ │ --wake-server-ip TEXT Wyoming wake word server IP address. │ │ [default: localhost] │ │ --wake-server-port INTEGER Wyoming wake word server port. │ @@ -1180,25 +1181,25 @@ uv tool install "agent-cli[vad]" │ 'ok_nabu', 'hey_jarvis'). │ │ [default: ok_nabu] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration ──────────────────────────────────────────────────╮ +╭─ Audio Input ────────────────────────────────────────────────────────────────╮ │ --input-device-index INTEGER Index of the audio input device to use. │ │ --input-device-name TEXT Device name keywords for partial │ │ matching. │ │ --list-devices List available audio input and output │ │ devices and exit. │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration: Wyoming (local) ─────────────────────────────────╮ +╭─ Audio Input: Wyoming ───────────────────────────────────────────────────────╮ │ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ │ [default: localhost] │ │ --asr-wyoming-port INTEGER Wyoming ASR server port. │ │ [default: 10300] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration: OpenAI ──────────────────────────────────────────╮ +╭─ Audio Input: OpenAI-compatible ─────────────────────────────────────────────╮ │ --asr-openai-model TEXT The OpenAI model to use for ASR │ │ (transcription). │ │ [default: whisper-1] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: Ollama (local) ──────────────────────────────────────────╮ +╭─ LLM: Ollama ────────────────────────────────────────────────────────────────╮ │ --llm-ollama-model TEXT The Ollama model to use. Default is │ │ gemma3:4b. │ │ [default: gemma3:4b] │ @@ -1206,7 +1207,7 @@ uv tool install "agent-cli[vad]" │ http://localhost:11434. │ │ [default: http://localhost:11434] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: OpenAI ──────────────────────────────────────────────────╮ +╭─ LLM: OpenAI-compatible ─────────────────────────────────────────────────────╮ │ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ │ [default: gpt-5-mini] │ │ --openai-api-key TEXT Your OpenAI API key. Can also be set with │ @@ -1217,14 +1218,14 @@ uv tool install "agent-cli[vad]" │ http://localhost:8080/v1). │ │ [env var: OPENAI_BASE_URL] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: Gemini ──────────────────────────────────────────────────╮ +╭─ LLM: Gemini ────────────────────────────────────────────────────────────────╮ │ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ │ [default: gemini-2.5-flash] │ │ --gemini-api-key TEXT Your Gemini API key. Can also be set with │ │ the GEMINI_API_KEY environment variable. │ │ [env var: GEMINI_API_KEY] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration ─────────────────────────────────────────╮ +╭─ Audio Output ───────────────────────────────────────────────────────────────╮ │ --tts --no-tts Enable text-to-speech for │ │ responses. │ │ [default: no-tts] │ @@ -1237,7 +1238,7 @@ uv tool install "agent-cli[vad]" │ 0.5 = half speed). │ │ [default: 1.0] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration: Wyoming (local) ────────────────────────╮ +╭─ Audio Output: Wyoming ──────────────────────────────────────────────────────╮ │ --tts-wyoming-ip TEXT Wyoming TTS server IP address. │ │ [default: localhost] │ │ --tts-wyoming-port INTEGER Wyoming TTS server port. │ @@ -1248,7 +1249,7 @@ uv tool install "agent-cli[vad]" │ 'en_US'). │ │ --tts-wyoming-speaker TEXT Speaker name for Wyoming TTS voice. │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration: OpenAI ─────────────────────────────────╮ +╭─ Audio Output: OpenAI-compatible ────────────────────────────────────────────╮ │ --tts-openai-model TEXT The OpenAI model to use for TTS. │ │ [default: tts-1] │ │ --tts-openai-voice TEXT The voice to use for OpenAI TTS. │ @@ -1257,7 +1258,7 @@ uv tool install "agent-cli[vad]" │ API (e.g., http://localhost:8000/v1 for a │ │ proxy). │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration: Kokoro ─────────────────────────────────╮ +╭─ Audio Output: Kokoro ───────────────────────────────────────────────────────╮ │ --tts-kokoro-model TEXT The Kokoro model to use for TTS. │ │ [default: kokoro] │ │ --tts-kokoro-voice TEXT The voice to use for Kokoro TTS. │ @@ -1265,7 +1266,7 @@ uv tool install "agent-cli[vad]" │ --tts-kokoro-host TEXT The base URL for the Kokoro API. │ │ [default: http://localhost:8880/v1] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Process Management Options ─────────────────────────────────────────────────╮ +╭─ Process Management ─────────────────────────────────────────────────────────╮ │ --stop Stop any running background process. │ │ --status Check if a background process is running. │ │ --toggle Toggle the background process on/off. If the process is │ @@ -1351,20 +1352,20 @@ uv tool install "agent-cli[vad]" │ 'kokoro'). │ │ [default: wyoming] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration ──────────────────────────────────────────────────╮ +╭─ Audio Input ────────────────────────────────────────────────────────────────╮ │ --input-device-index INTEGER Index of the audio input device to use. │ │ --input-device-name TEXT Device name keywords for partial │ │ matching. │ │ --list-devices List available audio input and output │ │ devices and exit. │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration: Wyoming (local) ─────────────────────────────────╮ +╭─ Audio Input: Wyoming ───────────────────────────────────────────────────────╮ │ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ │ [default: localhost] │ │ --asr-wyoming-port INTEGER Wyoming ASR server port. │ │ [default: 10300] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration: OpenAI ──────────────────────────────────────────╮ +╭─ Audio Input: OpenAI-compatible ─────────────────────────────────────────────╮ │ --asr-openai-model TEXT The OpenAI model to use for ASR │ │ (transcription). │ │ [default: whisper-1] │ @@ -1374,7 +1375,7 @@ uv tool install "agent-cli[vad]" │ --asr-openai-prompt TEXT Custom prompt to guide transcription │ │ (optional). │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: Ollama (local) ──────────────────────────────────────────╮ +╭─ LLM: Ollama ────────────────────────────────────────────────────────────────╮ │ --llm-ollama-model TEXT The Ollama model to use. Default is │ │ gemma3:4b. │ │ [default: gemma3:4b] │ @@ -1382,7 +1383,7 @@ uv tool install "agent-cli[vad]" │ http://localhost:11434. │ │ [default: http://localhost:11434] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: OpenAI ──────────────────────────────────────────────────╮ +╭─ LLM: OpenAI-compatible ─────────────────────────────────────────────────────╮ │ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ │ [default: gpt-5-mini] │ │ --openai-api-key TEXT Your OpenAI API key. Can also be set with │ @@ -1393,14 +1394,14 @@ uv tool install "agent-cli[vad]" │ http://localhost:8080/v1). │ │ [env var: OPENAI_BASE_URL] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: Gemini ──────────────────────────────────────────────────╮ +╭─ LLM: Gemini ────────────────────────────────────────────────────────────────╮ │ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ │ [default: gemini-2.5-flash] │ │ --gemini-api-key TEXT Your Gemini API key. Can also be set with │ │ the GEMINI_API_KEY environment variable. │ │ [env var: GEMINI_API_KEY] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration ─────────────────────────────────────────╮ +╭─ Audio Output ───────────────────────────────────────────────────────────────╮ │ --tts --no-tts Enable text-to-speech for │ │ responses. │ │ [default: no-tts] │ @@ -1413,7 +1414,7 @@ uv tool install "agent-cli[vad]" │ 0.5 = half speed). │ │ [default: 1.0] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration: Wyoming (local) ────────────────────────╮ +╭─ Audio Output: Wyoming ──────────────────────────────────────────────────────╮ │ --tts-wyoming-ip TEXT Wyoming TTS server IP address. │ │ [default: localhost] │ │ --tts-wyoming-port INTEGER Wyoming TTS server port. │ @@ -1424,7 +1425,7 @@ uv tool install "agent-cli[vad]" │ 'en_US'). │ │ --tts-wyoming-speaker TEXT Speaker name for Wyoming TTS voice. │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration: OpenAI ─────────────────────────────────╮ +╭─ Audio Output: OpenAI-compatible ────────────────────────────────────────────╮ │ --tts-openai-model TEXT The OpenAI model to use for TTS. │ │ [default: tts-1] │ │ --tts-openai-voice TEXT The voice to use for OpenAI TTS. │ @@ -1433,7 +1434,7 @@ uv tool install "agent-cli[vad]" │ API (e.g., http://localhost:8000/v1 for a │ │ proxy). │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration: Kokoro ─────────────────────────────────╮ +╭─ Audio Output: Kokoro ───────────────────────────────────────────────────────╮ │ --tts-kokoro-model TEXT The Kokoro model to use for TTS. │ │ [default: kokoro] │ │ --tts-kokoro-voice TEXT The voice to use for Kokoro TTS. │ @@ -1441,7 +1442,7 @@ uv tool install "agent-cli[vad]" │ --tts-kokoro-host TEXT The base URL for the Kokoro API. │ │ [default: http://localhost:8880/v1] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Process Management Options ─────────────────────────────────────────────────╮ +╭─ Process Management ─────────────────────────────────────────────────────────╮ │ --stop Stop any running background process. │ │ --status Check if a background process is running. │ │ --toggle Toggle the background process on/off. If the process is │ @@ -1532,7 +1533,7 @@ uv tool install "agent-cli[vad]" │ insufficient. │ │ [default: rag-tools] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: OpenAI ──────────────────────────────────────────────────╮ +╭─ LLM: OpenAI-compatible ─────────────────────────────────────────────────────╮ │ --openai-base-url TEXT Custom base URL for OpenAI-compatible API │ │ (e.g., for llama-server: │ │ http://localhost:8080/v1). │ @@ -1686,7 +1687,7 @@ The `memory proxy` command is the core feature—a middleware server that gives │ [default: │ │ git-versioning] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: OpenAI ──────────────────────────────────────────────────╮ +╭─ LLM: OpenAI-compatible ─────────────────────────────────────────────────────╮ │ --openai-base-url TEXT Custom base URL for OpenAI-compatible API │ │ (e.g., for llama-server: │ │ http://localhost:8080/v1). │ diff --git a/agent_cli/agents/transcribe.py b/agent_cli/agents/transcribe.py index 555d05b8d..a78723784 100644 --- a/agent_cli/agents/transcribe.py +++ b/agent_cli/agents/transcribe.py @@ -415,6 +415,7 @@ def transcribe( # noqa: PLR0912 None, "--extra-instructions", help="Additional instructions for the LLM to process the transcription.", + rich_help_panel="LLM Configuration", ), from_file: Path | None = opts.FROM_FILE, last_recording: int = opts.LAST_RECORDING, diff --git a/agent_cli/docs_gen.py b/agent_cli/docs_gen.py new file mode 100644 index 000000000..138526008 --- /dev/null +++ b/agent_cli/docs_gen.py @@ -0,0 +1,419 @@ +"""Documentation generators for markdown-code-runner integration. + +This module provides functions to introspect Typer commands and generate +Markdown documentation. Use with markdown-code-runner to auto-generate +options tables in documentation. + +Example usage in Markdown files: + + + + + + ...auto-generated table... + +""" + +from __future__ import annotations + +from typing import Any, get_origin + +import click +from typer.main import get_command + +from agent_cli import opts +from agent_cli.cli import app + + +def _get_type_str(annotation: Any) -> str: + """Convert a type annotation to a readable string.""" + if annotation is None: + return "str" + + # Handle Optional types (Union[X, None]) + origin = get_origin(annotation) + if origin is type(None): + return "None" + + # Get the base type name + if hasattr(annotation, "__name__"): + return annotation.__name__.upper() + if hasattr(annotation, "__origin__"): + # Handle generic types like Optional[str] + args = getattr(annotation, "__args__", ()) + non_none_args = [a for a in args if a is not type(None)] + if non_none_args: + return _get_type_str(non_none_args[0]) + return str(annotation).replace("typing.", "").upper() + + +def _format_default(default: Any) -> str: + """Format a default value for display.""" + if default is None: + return "-" + if isinstance(default, bool): + return str(default).lower() + if isinstance(default, str) and default == "": + return '""' + return str(default) + + +def _get_click_command(command_path: str) -> click.Command | None: + """Get a Click command from a path like 'transcribe' or 'memory.proxy'.""" + parts = command_path.split(".") + click_app = get_command(app) + + cmd: click.Command | click.Group = click_app + for part in parts: + if isinstance(cmd, click.Group): + cmd = cmd.commands.get(part) # type: ignore[assignment] + if cmd is None: + return None + else: + return None + return cmd + + +def _extract_options_from_click(cmd: click.Command) -> list[dict[str, Any]]: + """Extract options from a Click command.""" + options = [] + for param in cmd.params: + if isinstance(param, click.Option): + # Get the primary option name (longest one, usually --foo) + opt_names = [n for n in param.opts if n.startswith("--")] + if not opt_names: + opt_names = param.opts + primary_name = max(opt_names, key=len) if opt_names else param.name + + # Handle boolean flags + if param.is_flag and param.secondary_opts: + # e.g., --llm/--no-llm + primary_name = f"{opt_names[0]}/{param.secondary_opts[0]}" + + # Get panel from rich_help_panel or use default + panel = getattr(param, "rich_help_panel", None) or "Options" + + options.append( + { + "name": primary_name, + "type": param.type.name.upper() if hasattr(param.type, "name") else "TEXT", + "default": _format_default(param.default), + "help": param.help or "", + "panel": panel, + "envvar": param.envvar[0] if param.envvar else None, + "required": param.required, + "is_flag": param.is_flag, + }, + ) + return options + + +def _get_command_options(command_path: str) -> list[dict[str, Any]]: + """Extract all options from a Typer command.""" + cmd = _get_click_command(command_path) + if cmd is None: + return [] + return _extract_options_from_click(cmd) + + +def _options_table( + command_path: str, + panel: str | None = None, + *, + include_type: bool = True, + include_default: bool = True, +) -> str: + """Generate a Markdown table of options for a command.""" + options = _get_command_options(command_path) + if panel: + options = [o for o in options if o["panel"] == panel] + + if not options: + return f"*No options found for panel '{panel}'*" if panel else "*No options found*" + + # Build header + header_parts = ["Option"] + if include_type: + header_parts.append("Type") + if include_default: + header_parts.append("Default") + header_parts.append("Description") + + header = "| " + " | ".join(header_parts) + " |" + separator = "|" + "|".join("-" * (len(p) + 2) for p in header_parts) + "|" + + lines = [header, separator] + + for opt in options: + row_parts = [f"`{opt['name']}`"] + if include_type: + row_parts.append(opt["type"]) + if include_default: + default = opt["default"] + row_parts.append(f"`{default}`" if default != "-" else "-") + row_parts.append(opt["help"]) + lines.append("| " + " | ".join(row_parts) + " |") + + return "\n".join(lines) + + +def _options_by_panel( + command_path: str, + *, + include_type: bool = True, + include_default: bool = True, + heading_level: int = 3, +) -> str: + """Generate options tables grouped by panel.""" + options = _get_command_options(command_path) + if not options: + return "*No options found*" + + # Group by panel, preserving order + panels: dict[str, list[dict[str, Any]]] = {} + for opt in options: + panel = opt["panel"] + if panel not in panels: + panels[panel] = [] + panels[panel].append(opt) + + heading_prefix = "#" * heading_level + output = [] + + for panel, panel_opts in panels.items(): + output.append(f"{heading_prefix} {panel}\n") + + # Build table for this panel + header_parts = ["Option"] + if include_type: + header_parts.append("Type") + if include_default: + header_parts.append("Default") + header_parts.append("Description") + + header = "| " + " | ".join(header_parts) + " |" + separator = "|" + "|".join("-" * (len(p) + 2) for p in header_parts) + "|" + + output.append(header) + output.append(separator) + + for opt in panel_opts: + row_parts = [f"`{opt['name']}`"] + if include_type: + row_parts.append(opt["type"]) + if include_default: + default = opt["default"] + row_parts.append(f"`{default}`" if default != "-" else "-") + row_parts.append(opt["help"]) + output.append("| " + " | ".join(row_parts) + " |") + + output.append("") # Blank line between panels + + return "\n".join(output) + + +def _list_commands() -> list[str]: + """List all available commands including subcommands.""" + click_app = get_command(app) + commands = [] + + def _walk(cmd: click.Command | click.Group, prefix: str = "") -> None: + if isinstance(cmd, click.Group): + for name, subcmd in cmd.commands.items(): + path = f"{prefix}.{name}" if prefix else name + if isinstance(subcmd, click.Group): + _walk(subcmd, path) + else: + commands.append(path) + elif prefix: + commands.append(prefix) + + _walk(click_app) + return sorted(commands) + + +def env_vars_table() -> str: + """Generate a table of all environment variables. + + Returns: + Markdown table of environment variables and descriptions + + """ + lines = [ + "| Variable | Description |", + "|----------|-------------|", + ] + + seen = set() + for name in dir(opts): + if name.startswith("_"): + continue + obj = getattr(opts, name) + if hasattr(obj, "envvar") and obj.envvar: + envvar = obj.envvar + if envvar not in seen: + seen.add(envvar) + help_text = getattr(obj, "help", "") or "" + lines.append(f"| `{envvar}` | {help_text} |") + + return "\n".join(lines) + + +def provider_matrix() -> str: + """Generate provider comparison matrix. + + Returns: + Markdown table comparing local vs cloud providers + + """ + return """| Capability | Local (Default) | Cloud Options | +|------------|-----------------|---------------| +| **LLM** | Ollama (`ollama`) | OpenAI (`openai`), Gemini (`gemini`) | +| **ASR** (Speech-to-Text) | Wyoming/Faster Whisper (`wyoming`) | OpenAI Whisper (`openai`) | +| **TTS** (Text-to-Speech) | Wyoming/Piper (`wyoming`), Kokoro (`kokoro`) | OpenAI TTS (`openai`) | +| **Wake Word** | Wyoming/openWakeWord | - |""" + + +def commands_table(category: str | None = None) -> str: + """Generate a table of available commands. + + Args: + category: Filter by category (voice, text, ai, install, config) or None for all + + Returns: + Markdown table of commands + + """ + # Define command metadata + command_info = { + "transcribe": ("Speech-to-text", "Record voice → text in clipboard", "voice"), + "transcribe-daemon": ("Continuous transcription", "Background VAD service", "voice"), + "speak": ("Text-to-speech", "Read text aloud", "voice"), + "voice-edit": ("Voice-powered editor", "Edit clipboard with voice", "voice"), + "assistant": ("Wake word assistant", "Hands-free voice interaction", "voice"), + "chat": ("Conversational AI", "Voice chat with tools", "voice"), + "autocorrect": ("Grammar & spelling", "Fix text from clipboard", "text"), + "rag-proxy": ("RAG server", "Chat with documents", "ai"), + "memory.proxy": ("Long-term memory", "Persistent conversation memory", "ai"), + "memory.add": ("Add memories", "Directly add facts to memory", "ai"), + "server": ("Transcription server", "HTTP API for transcription", "ai"), + "install-services": ("Install services", "Set up AI services", "install"), + "install-hotkeys": ("Install hotkeys", "Set up system hotkeys", "install"), + "start-services": ("Start services", "Launch all services", "install"), + "config": ("Configuration", "Manage config files", "config"), + } + + if category: + commands = {k: v for k, v in command_info.items() if v[2] == category} + else: + commands = command_info + + if not commands: + return "*No commands found*" + + lines = [ + "| Command | Purpose | Use Case |", + "|---------|---------|----------|", + ] + + for cmd, (purpose, use_case, _) in commands.items(): + # Convert command path to link + doc_path = cmd.replace(".", "/") + lines.append(f"| [`{cmd}`]({doc_path}.md) | {purpose} | {use_case} |") + + return "\n".join(lines) + + +def config_example(command_path: str | None = None) -> str: + """Generate example TOML configuration for a command. + + Args: + command_path: Command path or None for defaults section + + Returns: + TOML configuration snippet + + """ + if command_path is None: + # Generate defaults section + return """[defaults] +# Provider defaults (can be overridden per command) +# llm_provider = "ollama" +# asr_provider = "wyoming" +# tts_provider = "wyoming" + +# API keys (or use environment variables) +# openai_api_key = "sk-..." +# gemini_api_key = "..." + +# Audio devices +# input_device_index = 1 +# output_device_index = 0""" + + options = _get_command_options(command_path) + if not options: + return f"# No configurable options for {command_path}" + + section = command_path.replace(".", "-") + lines = [f"[{section}]"] + + for opt in options: + # Skip process management and meta options + if opt["panel"] in ("Process Management Options",): + continue + + # Convert flag name to config key + key = opt["name"].lstrip("-").replace("-", "_").split("/")[0] + default = opt["default"] + help_text = opt["help"] + + # Format the value appropriately + if default == "-": + value = '""' if opt["type"] == "TEXT" else "null" + lines.append(f"# {key} = {value} # {help_text}") + elif opt["type"] == "TEXT": + lines.append(f'# {key} = "{default}" # {help_text}') + elif opt["type"] in ("INTEGER", "FLOAT") or opt["is_flag"]: + lines.append(f"# {key} = {default} # {help_text}") + else: + lines.append(f"# {key} = {default} # {help_text}") + + return "\n".join(lines) + + +def all_options_for_docs(command_path: str) -> str: + """Generate complete options documentation for a command page. + + This is the main function to use in docs/commands/*.md files. + It generates all options grouped by panel with proper formatting. + + Args: + command_path: Command path like "transcribe" or "memory.proxy" + + Returns: + Complete Markdown options section + + """ + return _options_by_panel( + command_path, + include_type=False, # Types are often obvious and clutter the table + include_default=True, + heading_level=3, + ) + + +if __name__ == "__main__": + # Demo: print options for transcribe command + print("=== Available Commands ===") + for cmd in _list_commands(): + print(f" {cmd}") + print() + + print("=== transcribe options by panel ===") + print(_options_by_panel("transcribe")) + + print("\n=== Environment Variables ===") + print(env_vars_table()) + + print("\n=== Provider Matrix ===") + print(provider_matrix()) diff --git a/agent_cli/opts.py b/agent_cli/opts.py index 71af47216..d0cca5633 100644 --- a/agent_cli/opts.py +++ b/agent_cli/opts.py @@ -49,48 +49,48 @@ def with_default(option: OptionInfo, default: str) -> OptionInfo: "gemma3:4b", "--llm-ollama-model", help="The Ollama model to use. Default is gemma3:4b.", - rich_help_panel="LLM Configuration: Ollama (local)", + rich_help_panel="LLM: Ollama", ) LLM_OLLAMA_HOST: str = typer.Option( "http://localhost:11434", "--llm-ollama-host", help="The Ollama server host. Default is http://localhost:11434.", - rich_help_panel="LLM Configuration: Ollama (local)", + rich_help_panel="LLM: Ollama", ) # OpenAI LLM_OPENAI_MODEL: str = typer.Option( DEFAULT_OPENAI_MODEL, "--llm-openai-model", help="The OpenAI model to use for LLM tasks.", - rich_help_panel="LLM Configuration: OpenAI", + rich_help_panel="LLM: OpenAI-compatible", ) OPENAI_API_KEY: str | None = typer.Option( None, "--openai-api-key", help="Your OpenAI API key. Can also be set with the OPENAI_API_KEY environment variable.", envvar="OPENAI_API_KEY", - rich_help_panel="LLM Configuration: OpenAI", + rich_help_panel="LLM: OpenAI-compatible", ) OPENAI_BASE_URL: str | None = typer.Option( None, "--openai-base-url", help="Custom base URL for OpenAI-compatible API (e.g., for llama-server: http://localhost:8080/v1).", envvar="OPENAI_BASE_URL", - rich_help_panel="LLM Configuration: OpenAI", + rich_help_panel="LLM: OpenAI-compatible", ) # Gemini LLM_GEMINI_MODEL: str = typer.Option( "gemini-2.5-flash", "--llm-gemini-model", help="The Gemini model to use for LLM tasks.", - rich_help_panel="LLM Configuration: Gemini", + rich_help_panel="LLM: Gemini", ) GEMINI_API_KEY: str | None = typer.Option( None, "--gemini-api-key", help="Your Gemini API key. Can also be set with the GEMINI_API_KEY environment variable.", envvar="GEMINI_API_KEY", - rich_help_panel="LLM Configuration: Gemini", + rich_help_panel="LLM: Gemini", ) EMBEDDING_MODEL: str = typer.Option( DEFAULT_OPENAI_EMBEDDING_MODEL, @@ -105,52 +105,52 @@ def with_default(option: OptionInfo, default: str) -> OptionInfo: None, "--input-device-index", help="Index of the audio input device to use.", - rich_help_panel="ASR (Audio) Configuration", + rich_help_panel="Audio Input", ) INPUT_DEVICE_NAME: str | None = typer.Option( None, "--input-device-name", help="Device name keywords for partial matching.", - rich_help_panel="ASR (Audio) Configuration", + rich_help_panel="Audio Input", ) LIST_DEVICES: bool = typer.Option( False, # noqa: FBT003 "--list-devices", help="List available audio input and output devices and exit.", is_eager=True, - rich_help_panel="ASR (Audio) Configuration", + rich_help_panel="Audio Input", ) # Wyoming (local service) ASR_WYOMING_IP: str = typer.Option( "localhost", "--asr-wyoming-ip", help="Wyoming ASR server IP address.", - rich_help_panel="ASR (Audio) Configuration: Wyoming (local)", + rich_help_panel="Audio Input: Wyoming", ) ASR_WYOMING_PORT: int = typer.Option( 10300, "--asr-wyoming-port", help="Wyoming ASR server port.", - rich_help_panel="ASR (Audio) Configuration: Wyoming (local)", + rich_help_panel="Audio Input: Wyoming", ) # OpenAI ASR_OPENAI_MODEL: str = typer.Option( "whisper-1", "--asr-openai-model", help="The OpenAI model to use for ASR (transcription).", - rich_help_panel="ASR (Audio) Configuration: OpenAI", + rich_help_panel="Audio Input: OpenAI-compatible", ) ASR_OPENAI_BASE_URL: str | None = typer.Option( None, "--asr-openai-base-url", help="Custom base URL for OpenAI-compatible ASR API (e.g., for custom Whisper server: http://localhost:9898).", - rich_help_panel="ASR (Audio) Configuration: OpenAI", + rich_help_panel="Audio Input: OpenAI-compatible", ) ASR_OPENAI_PROMPT: str | None = typer.Option( None, "--asr-openai-prompt", help="Custom prompt to guide transcription (optional).", - rich_help_panel="ASR (Audio) Configuration: OpenAI", + rich_help_panel="Audio Input: OpenAI-compatible", ) @@ -159,19 +159,19 @@ def with_default(option: OptionInfo, default: str) -> OptionInfo: "localhost", "--wake-server-ip", help="Wyoming wake word server IP address.", - rich_help_panel="Wake Word Options", + rich_help_panel="Wake Word", ) WAKE_SERVER_PORT: int = typer.Option( 10400, "--wake-server-port", help="Wyoming wake word server port.", - rich_help_panel="Wake Word Options", + rich_help_panel="Wake Word", ) WAKE_WORD: str = typer.Option( "ok_nabu", "--wake-word", help="Name of wake word to detect (e.g., 'ok_nabu', 'hey_jarvis').", - rich_help_panel="Wake Word Options", + rich_help_panel="Wake Word", ) @@ -181,75 +181,75 @@ def with_default(option: OptionInfo, default: str) -> OptionInfo: False, # noqa: FBT003 "--tts/--no-tts", help="Enable text-to-speech for responses.", - rich_help_panel="TTS (Text-to-Speech) Configuration", + rich_help_panel="Audio Output", ) TTS_SPEED: float = typer.Option( 1.0, "--tts-speed", help="Speech speed multiplier (1.0 = normal, 2.0 = twice as fast, 0.5 = half speed).", - rich_help_panel="TTS (Text-to-Speech) Configuration", + rich_help_panel="Audio Output", ) OUTPUT_DEVICE_INDEX: int | None = typer.Option( None, "--output-device-index", help="Index of the audio output device to use for TTS.", - rich_help_panel="TTS (Text-to-Speech) Configuration", + rich_help_panel="Audio Output", ) OUTPUT_DEVICE_NAME: str | None = typer.Option( None, "--output-device-name", help="Output device name keywords for partial matching.", - rich_help_panel="TTS (Text-to-Speech) Configuration", + rich_help_panel="Audio Output", ) # Wyoming (local service) TTS_WYOMING_IP: str = typer.Option( "localhost", "--tts-wyoming-ip", help="Wyoming TTS server IP address.", - rich_help_panel="TTS (Text-to-Speech) Configuration: Wyoming (local)", + rich_help_panel="Audio Output: Wyoming", ) TTS_WYOMING_PORT: int = typer.Option( 10200, "--tts-wyoming-port", help="Wyoming TTS server port.", - rich_help_panel="TTS (Text-to-Speech) Configuration: Wyoming (local)", + rich_help_panel="Audio Output: Wyoming", ) TTS_WYOMING_VOICE: str | None = typer.Option( None, "--tts-wyoming-voice", help="Voice name to use for Wyoming TTS (e.g., 'en_US-lessac-medium').", - rich_help_panel="TTS (Text-to-Speech) Configuration: Wyoming (local)", + rich_help_panel="Audio Output: Wyoming", ) TTS_WYOMING_LANGUAGE: str | None = typer.Option( None, "--tts-wyoming-language", help="Language for Wyoming TTS (e.g., 'en_US').", - rich_help_panel="TTS (Text-to-Speech) Configuration: Wyoming (local)", + rich_help_panel="Audio Output: Wyoming", ) TTS_WYOMING_SPEAKER: str | None = typer.Option( None, "--tts-wyoming-speaker", help="Speaker name for Wyoming TTS voice.", - rich_help_panel="TTS (Text-to-Speech) Configuration: Wyoming (local)", + rich_help_panel="Audio Output: Wyoming", ) # OpenAI TTS_OPENAI_MODEL: str = typer.Option( "tts-1", "--tts-openai-model", help="The OpenAI model to use for TTS.", - rich_help_panel="TTS (Text-to-Speech) Configuration: OpenAI", + rich_help_panel="Audio Output: OpenAI-compatible", ) TTS_OPENAI_VOICE: str = typer.Option( "alloy", "--tts-openai-voice", help="The voice to use for OpenAI TTS.", - rich_help_panel="TTS (Text-to-Speech) Configuration: OpenAI", + rich_help_panel="Audio Output: OpenAI-compatible", ) TTS_OPENAI_BASE_URL: str | None = typer.Option( None, "--tts-openai-base-url", help="Custom base URL for OpenAI-compatible TTS API (e.g., http://localhost:8000/v1 for a proxy).", - rich_help_panel="TTS (Text-to-Speech) Configuration: OpenAI", + rich_help_panel="Audio Output: OpenAI-compatible", ) @@ -258,19 +258,19 @@ def with_default(option: OptionInfo, default: str) -> OptionInfo: "kokoro", "--tts-kokoro-model", help="The Kokoro model to use for TTS.", - rich_help_panel="TTS (Text-to-Speech) Configuration: Kokoro", + rich_help_panel="Audio Output: Kokoro", ) TTS_KOKORO_VOICE: str = typer.Option( "af_sky", "--tts-kokoro-voice", help="The voice to use for Kokoro TTS.", - rich_help_panel="TTS (Text-to-Speech) Configuration: Kokoro", + rich_help_panel="Audio Output: Kokoro", ) TTS_KOKORO_HOST: str = typer.Option( "http://localhost:8880/v1", "--tts-kokoro-host", help="The base URL for the Kokoro API.", - rich_help_panel="TTS (Text-to-Speech) Configuration: Kokoro", + rich_help_panel="Audio Output: Kokoro", ) @@ -279,13 +279,13 @@ def with_default(option: OptionInfo, default: str) -> OptionInfo: False, # noqa: FBT003 "--stop", help="Stop any running background process.", - rich_help_panel="Process Management Options", + rich_help_panel="Process Management", ) STATUS: bool = typer.Option( False, # noqa: FBT003 "--status", help="Check if a background process is running.", - rich_help_panel="Process Management Options", + rich_help_panel="Process Management", ) TOGGLE: bool = typer.Option( False, # noqa: FBT003 @@ -293,7 +293,7 @@ def with_default(option: OptionInfo, default: str) -> OptionInfo: help="Toggle the background process on/off. " "If the process is running, it will be stopped. " "If the process is not running, it will be started.", - rich_help_panel="Process Management Options", + rich_help_panel="Process Management", ) # --- General Options --- diff --git a/docs/commands/assistant.md b/docs/commands/assistant.md index 115b51b5f..2e5f87718 100644 --- a/docs/commands/assistant.md +++ b/docs/commands/assistant.md @@ -41,124 +41,128 @@ agent-cli assistant --wake-server-ip 192.168.1.100 --wake-server-port 10400 ## Options -### Wake Word Configuration - -| Option | Description | Default | -|--------|-------------|---------| -| `--wake-word` | Wake word name (e.g., 'ok_nabu', 'hey_jarvis') | `ok_nabu` | -| `--wake-server-ip` | Wyoming wake word server IP | `localhost` | -| `--wake-server-port` | Wyoming wake word server port | `10400` | - + + + + + + ### Provider Selection -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-provider` | ASR provider: `wyoming`, `openai` | `wyoming` | -| `--llm-provider` | LLM provider: `ollama`, `openai`, `gemini` | `ollama` | -| `--tts-provider` | TTS provider: `wyoming`, `openai`, `kokoro` | `wyoming` | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-provider` | `wyoming` | The ASR provider to use ('wyoming', 'openai'). | +| `--llm-provider` | `ollama` | The LLM provider to use ('ollama', 'openai', 'gemini'). | +| `--tts-provider` | `wyoming` | The TTS provider to use ('wyoming', 'openai', 'kokoro'). | -### Audio Input +### Wake Word -| Option | Description | -|--------|-------------| -| `--input-device-index` | Index of audio input device | -| `--input-device-name` | Input device name keywords | -| `--list-devices` | List available devices | +| Option | Default | Description | +|--------|---------|-------------| +| `--wake-server-ip` | `localhost` | Wyoming wake word server IP address. | +| `--wake-server-port` | `10400` | Wyoming wake word server port. | +| `--wake-word` | `ok_nabu` | Name of wake word to detect (e.g., 'ok_nabu', 'hey_jarvis'). | -### ASR (Wyoming, local) +### Audio Input -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-wyoming-ip` | Wyoming ASR server IP | `localhost` | -| `--asr-wyoming-port` | Wyoming ASR server port | `10300` | +| Option | Default | Description | +|--------|---------|-------------| +| `--input-device-index` | - | Index of the audio input device to use. | +| `--input-device-name` | - | Device name keywords for partial matching. | +| `--list-devices` | `false` | List available audio input and output devices and exit. | -### ASR (OpenAI) +### Audio Input: Wyoming -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-openai-model` | OpenAI ASR model | `whisper-1` | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-wyoming-ip` | `localhost` | Wyoming ASR server IP address. | +| `--asr-wyoming-port` | `10300` | Wyoming ASR server port. | -### LLM (Ollama, local) +### Audio Input: OpenAI-compatible -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-ollama-model` | Ollama model to use | `gemma3:4b` | -| `--llm-ollama-host` | Ollama server URL | `http://localhost:11434` | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-openai-model` | `whisper-1` | The OpenAI model to use for ASR (transcription). | -### LLM (OpenAI) +### LLM: Ollama -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-openai-model` | OpenAI model to use | `gpt-5-mini` | -| `--openai-api-key` | OpenAI API key (or set `OPENAI_API_KEY`) | - | -| `--openai-base-url` | Custom OpenAI-compatible API URL (or set `OPENAI_BASE_URL`) | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-ollama-model` | `gemma3:4b` | The Ollama model to use. Default is gemma3:4b. | +| `--llm-ollama-host` | `http://localhost:11434` | The Ollama server host. Default is http://localhost:11434. | -### LLM (Gemini) +### LLM: OpenAI-compatible -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-gemini-model` | Gemini model to use | `gemini-2.5-flash` | -| `--gemini-api-key` | Gemini API key (or set `GEMINI_API_KEY`) | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-openai-model` | `gpt-5-mini` | The OpenAI model to use for LLM tasks. | +| `--openai-api-key` | - | Your OpenAI API key. Can also be set with the OPENAI_API_KEY environment variable. | +| `--openai-base-url` | - | Custom base URL for OpenAI-compatible API (e.g., for llama-server: http://localhost:8080/v1). | -### TTS Options (General) +### LLM: Gemini -| Option | Description | Default | -|--------|-------------|---------| -| `--tts` / `--no-tts` | Enable text-to-speech responses | `false` | -| `--tts-speed` | Speech speed multiplier | `1.0` | -| `--output-device-index` | Index of audio output device | - | -| `--output-device-name` | Output device name keywords | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-gemini-model` | `gemini-2.5-flash` | The Gemini model to use for LLM tasks. | +| `--gemini-api-key` | - | Your Gemini API key. Can also be set with the GEMINI_API_KEY environment variable. | -### TTS (Wyoming, local) +### Audio Output -| Option | Description | Default | -|--------|-------------|---------| -| `--tts-wyoming-ip` | Wyoming TTS server IP | `localhost` | -| `--tts-wyoming-port` | Wyoming TTS server port | `10200` | -| `--tts-wyoming-voice` | Voice name for Wyoming TTS | - | -| `--tts-wyoming-language` | Language for Wyoming TTS | - | -| `--tts-wyoming-speaker` | Speaker name for Wyoming TTS voice | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts/--no-tts` | `false` | Enable text-to-speech for responses. | +| `--output-device-index` | - | Index of the audio output device to use for TTS. | +| `--output-device-name` | - | Output device name keywords for partial matching. | +| `--tts-speed` | `1.0` | Speech speed multiplier (1.0 = normal, 2.0 = twice as fast, 0.5 = half speed). | -### TTS (OpenAI) +### Audio Output: Wyoming -| Option | Description | Default | -|--------|-------------|---------| -| `--tts-openai-model` | OpenAI TTS model | `tts-1` | -| `--tts-openai-voice` | OpenAI voice | `alloy` | -| `--tts-openai-base-url` | Custom OpenAI-compatible URL | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts-wyoming-ip` | `localhost` | Wyoming TTS server IP address. | +| `--tts-wyoming-port` | `10200` | Wyoming TTS server port. | +| `--tts-wyoming-voice` | - | Voice name to use for Wyoming TTS (e.g., 'en_US-lessac-medium'). | +| `--tts-wyoming-language` | - | Language for Wyoming TTS (e.g., 'en_US'). | +| `--tts-wyoming-speaker` | - | Speaker name for Wyoming TTS voice. | -### TTS (Kokoro) +### Audio Output: OpenAI-compatible -| Option | Description | Default | -|--------|-------------|---------| -| `--tts-kokoro-model` | Kokoro model | `kokoro` | -| `--tts-kokoro-voice` | Kokoro voice | `af_sky` | -| `--tts-kokoro-host` | Kokoro API URL | `http://localhost:8880/v1` | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts-openai-model` | `tts-1` | The OpenAI model to use for TTS. | +| `--tts-openai-voice` | `alloy` | The voice to use for OpenAI TTS. | +| `--tts-openai-base-url` | - | Custom base URL for OpenAI-compatible TTS API (e.g., http://localhost:8000/v1 for a proxy). | -### Output Options +### Audio Output: Kokoro -| Option | Description | Default | -|--------|-------------|---------| -| `--clipboard` / `--no-clipboard` | Copy result to clipboard | `true` | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts-kokoro-model` | `kokoro` | The Kokoro model to use for TTS. | +| `--tts-kokoro-voice` | `af_sky` | The voice to use for Kokoro TTS. | +| `--tts-kokoro-host` | `http://localhost:8880/v1` | The base URL for the Kokoro API. | ### Process Management -| Option | Description | -|--------|-------------| -| `--stop` | Stop running assistant | -| `--status` | Check if assistant is running | -| `--toggle` | Toggle assistant on/off | +| Option | Default | Description | +|--------|---------|-------------| +| `--stop` | `false` | Stop any running background process. | +| `--status` | `false` | Check if a background process is running. | +| `--toggle` | `false` | Toggle the background process on/off. If the process is running, it will be stopped. If the process is not running, it will be started. | ### General Options -| Option | Description | Default | -|--------|-------------|---------| -| `--save-file PATH` | Save TTS response audio to WAV file | - | -| `--log-level` | Set logging level | `WARNING` | -| `--log-file PATH` | Path to a file to write logs to | - | -| `--quiet`, `-q` | Suppress console output | `false` | -| `--config PATH` | Path to a TOML configuration file | - | -| `--print-args` | Print resolved arguments including config values | `false` | +| Option | Default | Description | +|--------|---------|-------------| +| `--save-file` | - | Save TTS response audio to WAV file. | +| `--clipboard/--no-clipboard` | `true` | Copy result to clipboard. | +| `--log-level` | `WARNING` | Set logging level. | +| `--log-file` | - | Path to a file to write logs to. | +| `--quiet` | `false` | Suppress console output from rich. | +| `--config` | - | Path to a TOML configuration file. | +| `--print-args` | `false` | Print the command line arguments, including variables taken from the configuration file. | + + + ## Available Wake Words diff --git a/docs/commands/autocorrect.md b/docs/commands/autocorrect.md index 5c1ba739f..95ccfa18f 100644 --- a/docs/commands/autocorrect.md +++ b/docs/commands/autocorrect.md @@ -34,43 +34,52 @@ agent-cli autocorrect "this text has an eror" ## Options + + + + + + ### Provider Selection -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-provider` | LLM provider: `ollama`, `openai`, `gemini` | `ollama` | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-provider` | `ollama` | The LLM provider to use ('ollama', 'openai', 'gemini'). | -### Ollama Configuration +### LLM: Ollama -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-ollama-model` | Ollama model to use | `gemma3:4b` | -| `--llm-ollama-host` | Ollama server URL | `http://localhost:11434` | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-ollama-model` | `gemma3:4b` | The Ollama model to use. Default is gemma3:4b. | +| `--llm-ollama-host` | `http://localhost:11434` | The Ollama server host. Default is http://localhost:11434. | -### OpenAI Configuration +### LLM: OpenAI-compatible -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-openai-model` | OpenAI model to use | `gpt-5-mini` | -| `--openai-api-key` | OpenAI API key (or set `OPENAI_API_KEY`) | - | -| `--openai-base-url` | Custom OpenAI-compatible API URL | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-openai-model` | `gpt-5-mini` | The OpenAI model to use for LLM tasks. | +| `--openai-api-key` | - | Your OpenAI API key. Can also be set with the OPENAI_API_KEY environment variable. | +| `--openai-base-url` | - | Custom base URL for OpenAI-compatible API (e.g., for llama-server: http://localhost:8080/v1). | -### Gemini Configuration +### LLM: Gemini -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-gemini-model` | Gemini model to use | `gemini-2.5-flash` | -| `--gemini-api-key` | Gemini API key (or set `GEMINI_API_KEY`) | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-gemini-model` | `gemini-2.5-flash` | The Gemini model to use for LLM tasks. | +| `--gemini-api-key` | - | Your Gemini API key. Can also be set with the GEMINI_API_KEY environment variable. | ### General Options -| Option | Description | Default | -|--------|-------------|---------| -| `--log-level` | Set logging level | `WARNING` | -| `--log-file PATH` | Path to a file to write logs to | - | -| `--quiet`, `-q` | Suppress console output | `false` | -| `--config PATH` | Path to a TOML configuration file | - | -| `--print-args` | Print resolved arguments including config values | `false` | +| Option | Default | Description | +|--------|---------|-------------| +| `--log-level` | `WARNING` | Set logging level. | +| `--log-file` | - | Path to a file to write logs to. | +| `--quiet` | `false` | Suppress console output from rich. | +| `--config` | - | Path to a TOML configuration file. | +| `--print-args` | `false` | Print the command line arguments, including variables taken from the configuration file. | + + + ## Workflow Integration diff --git a/docs/commands/chat.md b/docs/commands/chat.md index d7ff126b6..2eb2c64b8 100644 --- a/docs/commands/chat.md +++ b/docs/commands/chat.md @@ -43,119 +43,128 @@ agent-cli chat --last-n-messages 100 --history-dir ~/.my-chat-history ## Options + + + + + + ### Provider Selection -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-provider` | ASR provider: `wyoming`, `openai` | `wyoming` | -| `--llm-provider` | LLM provider: `ollama`, `openai`, `gemini` | `ollama` | -| `--tts-provider` | TTS provider: `wyoming`, `openai`, `kokoro` | `wyoming` | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-provider` | `wyoming` | The ASR provider to use ('wyoming', 'openai'). | +| `--llm-provider` | `ollama` | The LLM provider to use ('ollama', 'openai', 'gemini'). | +| `--tts-provider` | `wyoming` | The TTS provider to use ('wyoming', 'openai', 'kokoro'). | ### Audio Input -| Option | Description | -|--------|-------------| -| `--input-device-index` | Index of audio input device | -| `--input-device-name` | Input device name keywords | -| `--list-devices` | List available devices | +| Option | Default | Description | +|--------|---------|-------------| +| `--input-device-index` | - | Index of the audio input device to use. | +| `--input-device-name` | - | Device name keywords for partial matching. | +| `--list-devices` | `false` | List available audio input and output devices and exit. | -### ASR (Wyoming, local) +### Audio Input: Wyoming -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-wyoming-ip` | Wyoming ASR server IP | `localhost` | -| `--asr-wyoming-port` | Wyoming ASR server port | `10300` | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-wyoming-ip` | `localhost` | Wyoming ASR server IP address. | +| `--asr-wyoming-port` | `10300` | Wyoming ASR server port. | -### ASR (OpenAI) +### Audio Input: OpenAI-compatible -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-openai-model` | OpenAI ASR model | `whisper-1` | -| `--asr-openai-base-url` | Custom Whisper server URL | - | -| `--asr-openai-prompt` | Custom prompt to guide transcription | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-openai-model` | `whisper-1` | The OpenAI model to use for ASR (transcription). | +| `--asr-openai-base-url` | - | Custom base URL for OpenAI-compatible ASR API (e.g., for custom Whisper server: http://localhost:9898). | +| `--asr-openai-prompt` | - | Custom prompt to guide transcription (optional). | -### LLM (Ollama, local) +### LLM: Ollama -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-ollama-model` | Ollama model to use | `gemma3:4b` | -| `--llm-ollama-host` | Ollama server URL | `http://localhost:11434` | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-ollama-model` | `gemma3:4b` | The Ollama model to use. Default is gemma3:4b. | +| `--llm-ollama-host` | `http://localhost:11434` | The Ollama server host. Default is http://localhost:11434. | -### LLM (OpenAI) +### LLM: OpenAI-compatible -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-openai-model` | OpenAI model to use | `gpt-5-mini` | -| `--openai-api-key` | OpenAI API key (or set `OPENAI_API_KEY`) | - | -| `--openai-base-url` | Custom OpenAI-compatible API URL (or set `OPENAI_BASE_URL`) | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-openai-model` | `gpt-5-mini` | The OpenAI model to use for LLM tasks. | +| `--openai-api-key` | - | Your OpenAI API key. Can also be set with the OPENAI_API_KEY environment variable. | +| `--openai-base-url` | - | Custom base URL for OpenAI-compatible API (e.g., for llama-server: http://localhost:8080/v1). | -### LLM (Gemini) +### LLM: Gemini -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-gemini-model` | Gemini model to use | `gemini-2.5-flash` | -| `--gemini-api-key` | Gemini API key (or set `GEMINI_API_KEY`) | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-gemini-model` | `gemini-2.5-flash` | The Gemini model to use for LLM tasks. | +| `--gemini-api-key` | - | Your Gemini API key. Can also be set with the GEMINI_API_KEY environment variable. | -### TTS Options (General) +### Audio Output -| Option | Description | Default | -|--------|-------------|---------| -| `--tts` / `--no-tts` | Enable text-to-speech responses | `false` | -| `--tts-speed` | Speech speed multiplier | `1.0` | -| `--output-device-index` | Index of audio output device | - | -| `--output-device-name` | Output device name keywords | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts/--no-tts` | `false` | Enable text-to-speech for responses. | +| `--output-device-index` | - | Index of the audio output device to use for TTS. | +| `--output-device-name` | - | Output device name keywords for partial matching. | +| `--tts-speed` | `1.0` | Speech speed multiplier (1.0 = normal, 2.0 = twice as fast, 0.5 = half speed). | -### TTS (Wyoming, local) +### Audio Output: Wyoming -| Option | Description | Default | -|--------|-------------|---------| -| `--tts-wyoming-ip` | Wyoming TTS server IP | `localhost` | -| `--tts-wyoming-port` | Wyoming TTS server port | `10200` | -| `--tts-wyoming-voice` | Voice name for Wyoming TTS | - | -| `--tts-wyoming-language` | Language for Wyoming TTS | - | -| `--tts-wyoming-speaker` | Speaker name for Wyoming TTS voice | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts-wyoming-ip` | `localhost` | Wyoming TTS server IP address. | +| `--tts-wyoming-port` | `10200` | Wyoming TTS server port. | +| `--tts-wyoming-voice` | - | Voice name to use for Wyoming TTS (e.g., 'en_US-lessac-medium'). | +| `--tts-wyoming-language` | - | Language for Wyoming TTS (e.g., 'en_US'). | +| `--tts-wyoming-speaker` | - | Speaker name for Wyoming TTS voice. | -### TTS (OpenAI) +### Audio Output: OpenAI-compatible -| Option | Description | Default | -|--------|-------------|---------| -| `--tts-openai-model` | OpenAI TTS model | `tts-1` | -| `--tts-openai-voice` | OpenAI voice | `alloy` | -| `--tts-openai-base-url` | Custom OpenAI-compatible URL | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts-openai-model` | `tts-1` | The OpenAI model to use for TTS. | +| `--tts-openai-voice` | `alloy` | The voice to use for OpenAI TTS. | +| `--tts-openai-base-url` | - | Custom base URL for OpenAI-compatible TTS API (e.g., http://localhost:8000/v1 for a proxy). | -### TTS (Kokoro) +### Audio Output: Kokoro -| Option | Description | Default | -|--------|-------------|---------| -| `--tts-kokoro-model` | Kokoro model | `kokoro` | -| `--tts-kokoro-voice` | Kokoro voice | `af_sky` | -| `--tts-kokoro-host` | Kokoro API URL | `http://localhost:8880/v1` | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts-kokoro-model` | `kokoro` | The Kokoro model to use for TTS. | +| `--tts-kokoro-voice` | `af_sky` | The voice to use for Kokoro TTS. | +| `--tts-kokoro-host` | `http://localhost:8880/v1` | The base URL for the Kokoro API. | -### History Options +### Process Management -| Option | Description | Default | -|--------|-------------|---------| -| `--history-dir PATH` | Directory for conversation history | `~/.config/agent-cli/history` | -| `--last-n-messages N` | Number of messages to include (0 = disable) | `50` | +| Option | Default | Description | +|--------|---------|-------------| +| `--stop` | `false` | Stop any running background process. | +| `--status` | `false` | Check if a background process is running. | +| `--toggle` | `false` | Toggle the background process on/off. If the process is running, it will be stopped. If the process is not running, it will be started. | -### Process Management +### History Options -| Option | Description | -|--------|-------------| -| `--stop` | Stop running chat | -| `--status` | Check if chat is running | -| `--toggle` | Toggle chat on/off | +| Option | Default | Description | +|--------|---------|-------------| +| `--history-dir` | `~/.config/agent-cli/history` | Directory to store conversation history. | +| `--last-n-messages` | `50` | Number of messages to include in the conversation history. Set to 0 to disable history. | ### General Options -| Option | Description | Default | -|--------|-------------|---------| -| `--save-file PATH` | Save TTS audio to WAV file | - | -| `--log-level` | Set logging level | `WARNING` | -| `--log-file PATH` | Path to a file to write logs to | - | -| `--quiet`, `-q` | Suppress console output | `false` | -| `--config PATH` | Path to a TOML configuration file | - | -| `--print-args` | Print resolved arguments including config values | `false` | +| Option | Default | Description | +|--------|---------|-------------| +| `--save-file` | - | Save TTS response audio to WAV file. | +| `--log-level` | `WARNING` | Set logging level. | +| `--log-file` | - | Path to a file to write logs to. | +| `--quiet` | `false` | Suppress console output from rich. | +| `--config` | - | Path to a TOML configuration file. | +| `--print-args` | `false` | Print the command line arguments, including variables taken from the configuration file. | + + + ## Available Tools diff --git a/docs/commands/memory.md b/docs/commands/memory.md index a1544a526..5ff97a459 100644 --- a/docs/commands/memory.md +++ b/docs/commands/memory.md @@ -63,41 +63,55 @@ agent-cli chat --openai-base-url http://localhost:8100/v1 --llm-provider openai ### Options -#### Memory Configuration - -| Option | Description | Default | -|--------|-------------|---------| -| `--memory-path PATH` | Path to memory store | `./memory_db` | -| `--default-top-k N` | Memories to retrieve per query | `5` | -| `--max-entries N` | Max entries per conversation | `500` | -| `--mmr-lambda FLOAT` | MMR lambda (0-1): relevance vs diversity | `0.7` | -| `--recency-weight FLOAT` | Recency score weight (0-1) | `0.2` | -| `--score-threshold FLOAT` | Min semantic relevance threshold | `0.35` | -| `--summarization` / `--no-summarization` | Enable fact extraction & summaries | `true` | -| `--git-versioning` / `--no-git-versioning` | Enable git commits for changes | `true` | - -#### LLM Configuration - -| Option | Description | Default | -|--------|-------------|---------| -| `--openai-base-url` | OpenAI-compatible API URL | - | -| `--openai-api-key` | OpenAI API key | - | -| `--embedding-model` | Model for embeddings | `text-embedding-3-small` | - -#### Server Configuration - -| Option | Description | Default | -|--------|-------------|---------| -| `--host` | Host to bind to | `0.0.0.0` | -| `--port` | Port to bind to | `8100` | - -#### General Options - -| Option | Description | Default | -|--------|-------------|---------| -| `--log-level` | Logging level | `INFO` | -| `--config PATH` | Path to a TOML configuration file | - | -| `--print-args` | Print resolved arguments including config values | `false` | + + + + + + +### Memory Configuration + +| Option | Default | Description | +|--------|---------|-------------| +| `--memory-path` | `./memory_db` | Path to the memory store (files + derived vector index). | +| `--default-top-k` | `5` | Number of memory entries to retrieve per query. | +| `--max-entries` | `500` | Maximum stored memory entries per conversation (excluding summary). | +| `--mmr-lambda` | `0.7` | MMR lambda (0-1): higher favors relevance, lower favors diversity. | +| `--recency-weight` | `0.2` | Recency score weight (0.0-1.0). Controls freshness vs. relevance. Default 0.2 (20% recency, 80% semantic relevance). | +| `--score-threshold` | `0.35` | Minimum semantic relevance threshold (0.0-1.0). Memories below this score are discarded to reduce noise. | +| `--summarization/--no-summarization` | `true` | Enable automatic fact extraction and summaries. | +| `--git-versioning/--no-git-versioning` | `true` | Enable automatic git commit of memory changes. | + +### LLM: OpenAI-compatible + +| Option | Default | Description | +|--------|---------|-------------| +| `--openai-base-url` | - | Custom base URL for OpenAI-compatible API (e.g., for llama-server: http://localhost:8080/v1). | +| `--openai-api-key` | - | Your OpenAI API key. Can also be set with the OPENAI_API_KEY environment variable. | + +### LLM Configuration + +| Option | Default | Description | +|--------|---------|-------------| +| `--embedding-model` | `text-embedding-3-small` | Embedding model to use for vectorization. | + +### Server Configuration + +| Option | Default | Description | +|--------|---------|-------------| +| `--host` | `0.0.0.0` | Host/IP to bind API servers to. | +| `--port` | `8100` | Port to bind to | + +### General Options + +| Option | Default | Description | +|--------|---------|-------------| +| `--log-level` | `INFO` | Set logging level. | +| `--config` | - | Path to a TOML configuration file. | +| `--print-args` | `false` | Print the command line arguments, including variables taken from the configuration file. | + + + --- @@ -136,20 +150,31 @@ agent-cli memory add -c work "Project deadline is Friday" ### Options -| Option | Description | Default | -|--------|-------------|---------| -| `-f`, `--file PATH` | Read from file (use `-` for stdin) | - | -| `-c`, `--conversation-id` | Conversation ID to add memories to | `default` | -| `--memory-path PATH` | Path to memory store | `./memory_db` | -| `--git-versioning` / `--no-git-versioning` | Commit changes to git | `true` | + + + + + + +### Options + +| Option | Default | Description | +|--------|---------|-------------| +| `--file` | - | Read memories from file. Use '-' for stdin. Supports JSON array, JSON object with 'memories' key, or plain text (one per line). | +| `--conversation-id` | `default` | Conversation ID to add memories to. | +| `--memory-path` | `./memory_db` | Path to the memory store. | +| `--git-versioning/--no-git-versioning` | `true` | Commit changes to git. | ### General Options -| Option | Description | Default | -|--------|-------------|---------| -| `--quiet`, `-q` | Suppress console output | `false` | -| `--config PATH` | Path to a TOML configuration file | - | -| `--print-args` | Print resolved arguments including config values | `false` | +| Option | Default | Description | +|--------|---------|-------------| +| `--quiet` | `false` | Suppress console output from rich. | +| `--config` | - | Path to a TOML configuration file. | +| `--print-args` | `false` | Print the command line arguments, including variables taken from the configuration file. | + + + ### File Format diff --git a/docs/commands/rag-proxy.md b/docs/commands/rag-proxy.md index 52f59ec19..e452dc0b8 100644 --- a/docs/commands/rag-proxy.md +++ b/docs/commands/rag-proxy.md @@ -52,37 +52,51 @@ agent-cli chat --openai-base-url http://localhost:8000/v1 --llm-provider openai ## Options + + + + + + ### RAG Configuration -| Option | Description | Default | -|--------|-------------|---------| -| `--docs-folder PATH` | Folder to watch for documents | `./rag_docs` | -| `--chroma-path PATH` | ChromaDB persistence directory | `./rag_db` | -| `--limit N` | Number of chunks to retrieve per query | `3` | -| `--rag-tools` / `--no-rag-tools` | Allow agent to fetch full documents | `true` | +| Option | Default | Description | +|--------|---------|-------------| +| `--docs-folder` | `./rag_docs` | Folder to watch for documents | +| `--chroma-path` | `./rag_db` | Path to ChromaDB persistence directory | +| `--limit` | `3` | Number of document chunks to retrieve per query. | +| `--rag-tools/--no-rag-tools` | `true` | Allow agent to fetch full documents when snippets are insufficient. | + +### LLM: OpenAI-compatible + +| Option | Default | Description | +|--------|---------|-------------| +| `--openai-base-url` | - | Custom base URL for OpenAI-compatible API (e.g., for llama-server: http://localhost:8080/v1). | +| `--openai-api-key` | - | Your OpenAI API key. Can also be set with the OPENAI_API_KEY environment variable. | ### LLM Configuration -| Option | Description | -|--------|-------------| -| `--openai-base-url` | OpenAI-compatible API URL (e.g., Ollama) | -| `--openai-api-key` | OpenAI API key | -| `--embedding-model` | Model for embeddings | `text-embedding-3-small` | +| Option | Default | Description | +|--------|---------|-------------| +| `--embedding-model` | `text-embedding-3-small` | Embedding model to use for vectorization. | ### Server Configuration -| Option | Description | Default | -|--------|-------------|---------| -| `--host` | Host/IP to bind to | `0.0.0.0` | -| `--port` | Port to bind to | `8000` | +| Option | Default | Description | +|--------|---------|-------------| +| `--host` | `0.0.0.0` | Host/IP to bind API servers to. | +| `--port` | `8000` | Port to bind to | ### General Options -| Option | Description | Default | -|--------|-------------|---------| -| `--log-level` | Logging level | `INFO` | -| `--config PATH` | Path to a TOML configuration file | - | -| `--print-args` | Print resolved arguments including config values | `false` | +| Option | Default | Description | +|--------|---------|-------------| +| `--log-level` | `INFO` | Set logging level. | +| `--config` | - | Path to a TOML configuration file. | +| `--print-args` | `false` | Print the command line arguments, including variables taken from the configuration file. | + + + ## Supported Document Types diff --git a/docs/commands/server.md b/docs/commands/server.md index 4e6384990..9a50b39ac 100644 --- a/docs/commands/server.md +++ b/docs/commands/server.md @@ -35,13 +35,29 @@ agent-cli server --reload ## Options -| Option | Description | Default | -|--------|-------------|---------| -| `--host` | Host/IP to bind the server to | `0.0.0.0` | -| `--port` | Port to bind the server to | `61337` | -| `--reload` | Enable auto-reload for development | `false` | -| `--config` | Path to a TOML configuration file | - | -| `--print-args` | Print resolved arguments | - | + + + + + + +### Options + +| Option | Default | Description | +|--------|---------|-------------| +| `--host` | `0.0.0.0` | Host to bind the server to | +| `--port` | `61337` | Port to bind the server to | +| `--reload` | `false` | Enable auto-reload for development | + +### General Options + +| Option | Default | Description | +|--------|---------|-------------| +| `--config` | - | Path to a TOML configuration file. | +| `--print-args` | `false` | Print the command line arguments, including variables taken from the configuration file. | + + + ## Installation diff --git a/docs/commands/speak.md b/docs/commands/speak.md index 5c84fa619..0a3709896 100644 --- a/docs/commands/speak.md +++ b/docs/commands/speak.md @@ -38,65 +38,79 @@ agent-cli speak --list-devices ## Options + + + + + + ### Provider Selection -| Option | Description | Default | -|--------|-------------|---------| -| `--tts-provider` | TTS provider: `wyoming`, `openai`, `kokoro` | `wyoming` | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts-provider` | `wyoming` | The TTS provider to use ('wyoming', 'openai', 'kokoro'). | ### Audio Output -| Option | Description | -|--------|-------------| -| `--output-device-index` | Index of audio output device | -| `--output-device-name` | Device name keywords for matching | -| `--tts-speed` | Speech speed multiplier (1.0 = normal) | -| `--list-devices` | List available audio devices | +| Option | Default | Description | +|--------|---------|-------------| +| `--output-device-index` | - | Index of the audio output device to use for TTS. | +| `--output-device-name` | - | Output device name keywords for partial matching. | +| `--tts-speed` | `1.0` | Speech speed multiplier (1.0 = normal, 2.0 = twice as fast, 0.5 = half speed). | -### Wyoming (Local) Configuration +### Audio Output: Wyoming -| Option | Description | Default | -|--------|-------------|---------| -| `--tts-wyoming-ip` | Wyoming TTS server IP | `localhost` | -| `--tts-wyoming-port` | Wyoming TTS server port | `10200` | -| `--tts-wyoming-voice` | Voice name (e.g., 'en_US-lessac-medium') | - | -| `--tts-wyoming-language` | Language (e.g., 'en_US') | - | -| `--tts-wyoming-speaker` | Speaker name for multi-speaker voices | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts-wyoming-ip` | `localhost` | Wyoming TTS server IP address. | +| `--tts-wyoming-port` | `10200` | Wyoming TTS server port. | +| `--tts-wyoming-voice` | - | Voice name to use for Wyoming TTS (e.g., 'en_US-lessac-medium'). | +| `--tts-wyoming-language` | - | Language for Wyoming TTS (e.g., 'en_US'). | +| `--tts-wyoming-speaker` | - | Speaker name for Wyoming TTS voice. | -### OpenAI Configuration +### Audio Output: OpenAI-compatible -| Option | Description | Default | -|--------|-------------|---------| -| `--tts-openai-model` | OpenAI TTS model | `tts-1` | -| `--tts-openai-voice` | OpenAI voice | `alloy` | -| `--tts-openai-base-url` | Custom OpenAI-compatible URL | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts-openai-model` | `tts-1` | The OpenAI model to use for TTS. | +| `--tts-openai-voice` | `alloy` | The voice to use for OpenAI TTS. | +| `--tts-openai-base-url` | - | Custom base URL for OpenAI-compatible TTS API (e.g., http://localhost:8000/v1 for a proxy). | -### Kokoro Configuration +### Audio Output: Kokoro -| Option | Description | Default | -|--------|-------------|---------| -| `--tts-kokoro-model` | Kokoro model | `kokoro` | -| `--tts-kokoro-voice` | Kokoro voice | `af_sky` | -| `--tts-kokoro-host` | Kokoro API URL | `http://localhost:8880/v1` | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts-kokoro-model` | `kokoro` | The Kokoro model to use for TTS. | +| `--tts-kokoro-voice` | `af_sky` | The voice to use for Kokoro TTS. | +| `--tts-kokoro-host` | `http://localhost:8880/v1` | The base URL for the Kokoro API. | -### Process Management +### Audio Input -| Option | Description | -|--------|-------------| -| `--stop` | Stop running TTS process | -| `--status` | Check if TTS process is running | -| `--toggle` | Toggle TTS process on/off | +| Option | Default | Description | +|--------|---------|-------------| +| `--list-devices` | `false` | List available audio input and output devices and exit. | ### General Options -| Option | Description | Default | -|--------|-------------|---------| -| `--save-file PATH` | Save TTS response audio to WAV file | - | -| `--log-level` | Set logging level | `WARNING` | -| `--log-file PATH` | Path to a file to write logs to | - | -| `--quiet`, `-q` | Suppress console output | `false` | -| `--config PATH` | Path to a TOML configuration file | - | -| `--print-args` | Print resolved arguments including config values | `false` | +| Option | Default | Description | +|--------|---------|-------------| +| `--save-file` | - | Save TTS response audio to WAV file. | +| `--log-level` | `WARNING` | Set logging level. | +| `--log-file` | - | Path to a file to write logs to. | +| `--quiet` | `false` | Suppress console output from rich. | +| `--config` | - | Path to a TOML configuration file. | +| `--print-args` | `false` | Print the command line arguments, including variables taken from the configuration file. | + +### Process Management + +| Option | Default | Description | +|--------|---------|-------------| +| `--stop` | `false` | Stop any running background process. | +| `--status` | `false` | Check if a background process is running. | +| `--toggle` | `false` | Toggle the background process on/off. If the process is running, it will be stopped. If the process is not running, it will be started. | + + + ## Available Voices diff --git a/docs/commands/start-services.md b/docs/commands/start-services.md index fa8b9ff58..3016e16cc 100644 --- a/docs/commands/start-services.md +++ b/docs/commands/start-services.md @@ -25,10 +25,20 @@ Services run inside a Zellij session named `agent-cli`. ## Options -| Option | Description | Default | -|--------|-------------|---------| -| `--attach` / `--no-attach` | Attach to the Zellij session after starting | `true` | -| `--help`, `-h` | Show help for the command | - | + + + + + + +### Options + +| Option | Default | Description | +|--------|---------|-------------| +| `--attach/--no-attach` | `true` | Attach to Zellij session after starting | + + + ## Examples diff --git a/docs/commands/transcribe-daemon.md b/docs/commands/transcribe-daemon.md index 6969418e4..61fee5f21 100644 --- a/docs/commands/transcribe-daemon.md +++ b/docs/commands/transcribe-daemon.md @@ -52,98 +52,102 @@ agent-cli transcribe-daemon --silence-threshold 1.5 ## Options -### VAD Configuration - -| Option | Description | Default | -|--------|-------------|---------| -| `-r`, `--role` | Role name for logging (e.g., 'meeting', 'notes') | `user` | -| `-s`, `--silence-threshold` | Seconds of silence to end a segment | `1.0` | -| `-m`, `--min-segment` | Minimum speech duration in seconds | `0.25` | -| `--vad-threshold` | Speech detection threshold (0.0-1.0) | `0.3` | - -### Audio Storage - -| Option | Description | Default | -|--------|-------------|---------| -| `--save-audio` / `--no-save-audio` | Save audio segments as MP3 | `true` | -| `--audio-dir PATH` | Directory for MP3 files | `~/.config/agent-cli/audio` | -| `-t`, `--transcription-log PATH` | JSON Lines log file | `~/.config/agent-cli/transcriptions.jsonl` | -| `--clipboard` / `--no-clipboard` | Copy each transcription to clipboard | `false` | + + + + + + +### Options + +| Option | Default | Description | +|--------|---------|-------------| +| `--role` | `user` | Role name for logging (e.g., 'meeting', 'notes', 'user'). | +| `--silence-threshold` | `1.0` | Seconds of silence to end a speech segment. | +| `--min-segment` | `0.25` | Minimum speech duration in seconds to trigger a segment. | +| `--vad-threshold` | `0.3` | VAD speech detection threshold (0.0-1.0). Higher = more aggressive filtering. | +| `--save-audio/--no-save-audio` | `true` | Save audio segments as MP3 files. | +| `--audio-dir` | - | Directory for MP3 files. Default: ~/.config/agent-cli/audio | +| `--transcription-log` | - | JSON Lines log file path. Default: ~/.config/agent-cli/transcriptions.jsonl | +| `--clipboard/--no-clipboard` | `false` | Copy each transcription to clipboard. | ### Provider Selection -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-provider` | ASR provider: `wyoming`, `openai` | `wyoming` | -| `--llm-provider` | LLM provider: `ollama`, `openai`, `gemini` | `ollama` | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-provider` | `wyoming` | The ASR provider to use ('wyoming', 'openai'). | +| `--llm-provider` | `ollama` | The LLM provider to use ('ollama', 'openai', 'gemini'). | ### Audio Input -| Option | Description | -|--------|-------------| -| `--input-device-index` | Index of audio input device | -| `--input-device-name` | Input device name keywords | -| `--list-devices` | List available devices | +| Option | Default | Description | +|--------|---------|-------------| +| `--input-device-index` | - | Index of the audio input device to use. | +| `--input-device-name` | - | Device name keywords for partial matching. | +| `--list-devices` | `false` | List available audio input and output devices and exit. | -### ASR (Wyoming, local) +### Audio Input: Wyoming -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-wyoming-ip` | Wyoming ASR server IP | `localhost` | -| `--asr-wyoming-port` | Wyoming ASR server port | `10300` | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-wyoming-ip` | `localhost` | Wyoming ASR server IP address. | +| `--asr-wyoming-port` | `10300` | Wyoming ASR server port. | -### ASR (OpenAI) +### Audio Input: OpenAI-compatible -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-openai-model` | OpenAI ASR model | `whisper-1` | -| `--asr-openai-base-url` | Custom Whisper server URL | - | -| `--asr-openai-prompt` | Custom prompt to guide transcription | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-openai-model` | `whisper-1` | The OpenAI model to use for ASR (transcription). | +| `--asr-openai-base-url` | - | Custom base URL for OpenAI-compatible ASR API (e.g., for custom Whisper server: http://localhost:9898). | +| `--asr-openai-prompt` | - | Custom prompt to guide transcription (optional). | -### LLM (Ollama, local) +### LLM: Ollama -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-ollama-model` | Ollama model to use | `gemma3:4b` | -| `--llm-ollama-host` | Ollama server URL | `http://localhost:11434` | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-ollama-model` | `gemma3:4b` | The Ollama model to use. Default is gemma3:4b. | +| `--llm-ollama-host` | `http://localhost:11434` | The Ollama server host. Default is http://localhost:11434. | -### LLM (OpenAI) +### LLM: OpenAI-compatible -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-openai-model` | OpenAI model to use | `gpt-5-mini` | -| `--openai-api-key` | OpenAI API key (or set `OPENAI_API_KEY`) | - | -| `--openai-base-url` | Custom OpenAI-compatible API URL (or set `OPENAI_BASE_URL`) | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-openai-model` | `gpt-5-mini` | The OpenAI model to use for LLM tasks. | +| `--openai-api-key` | - | Your OpenAI API key. Can also be set with the OPENAI_API_KEY environment variable. | +| `--openai-base-url` | - | Custom base URL for OpenAI-compatible API (e.g., for llama-server: http://localhost:8080/v1). | -### LLM (Gemini) +### LLM: Gemini -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-gemini-model` | Gemini model to use | `gemini-2.5-flash` | -| `--gemini-api-key` | Gemini API key (or set `GEMINI_API_KEY`) | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-gemini-model` | `gemini-2.5-flash` | The Gemini model to use for LLM tasks. | +| `--gemini-api-key` | - | Your Gemini API key. Can also be set with the GEMINI_API_KEY environment variable. | -### LLM Cleanup +### LLM Configuration -| Option | Description | Default | -|--------|-------------|---------| -| `--llm` / `--no-llm` | Use LLM to process transcript | `false` | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm/--no-llm` | `false` | Use an LLM to process the transcript. | ### Process Management -| Option | Description | -|--------|-------------| -| `--stop` | Stop running daemon | -| `--status` | Check if daemon is running | +| Option | Default | Description | +|--------|---------|-------------| +| `--stop` | `false` | Stop any running background process. | +| `--status` | `false` | Check if a background process is running. | ### General Options -| Option | Description | Default | -|--------|-------------|---------| -| `--log-level` | Set logging level | `WARNING` | -| `--log-file PATH` | Path to a file to write logs to | - | -| `--quiet`, `-q` | Suppress console output | `false` | -| `--config PATH` | Path to a TOML configuration file | - | -| `--print-args` | Print resolved arguments including config values | `false` | +| Option | Default | Description | +|--------|---------|-------------| +| `--log-level` | `WARNING` | Set logging level. | +| `--log-file` | - | Path to a file to write logs to. | +| `--quiet` | `false` | Suppress console output from rich. | +| `--config` | - | Path to a TOML configuration file. | +| `--print-args` | `false` | Print the command line arguments, including variables taken from the configuration file. | + + + ## Output Files diff --git a/docs/commands/transcribe.md b/docs/commands/transcribe.md index 89dfec60b..c79f8aa74 100644 --- a/docs/commands/transcribe.md +++ b/docs/commands/transcribe.md @@ -43,92 +43,101 @@ agent-cli transcribe --last-recording 1 ## Options -### Audio Configuration - -| Option | Description | -|--------|-------------| -| `--input-device-index` | Index of the audio input device | -| `--input-device-name` | Device name keywords for partial matching | -| `--list-devices` | List available audio devices and exit | + + + + + + +### LLM Configuration + +| Option | Default | Description | +|--------|---------|-------------| +| `--extra-instructions` | - | Additional instructions for the LLM to process the transcription. | +| `--llm/--no-llm` | `false` | Use an LLM to process the transcript. | ### Audio Recovery -| Option | Description | Default | -|--------|-------------|---------| -| `--from-file PATH` | Transcribe from a saved WAV file | - | -| `--last-recording N` | Transcribe Nth most recent recording (1=latest) | `0` | -| `--save-recording` / `--no-save-recording` | Save audio for recovery | `true` | +| Option | Default | Description | +|--------|---------|-------------| +| `--from-file` | - | Transcribe audio from a saved WAV file instead of recording. | +| `--last-recording` | `0` | Transcribe a saved recording. Use 1 for most recent, 2 for second-to-last, etc. Use 0 to disable (default). | +| `--save-recording/--no-save-recording` | `true` | Save the audio recording to disk for recovery. | ### Provider Selection -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-provider` | ASR provider: `wyoming`, `openai` | `wyoming` | -| `--llm-provider` | LLM provider: `ollama`, `openai`, `gemini` | `ollama` | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-provider` | `wyoming` | The ASR provider to use ('wyoming', 'openai'). | +| `--llm-provider` | `ollama` | The LLM provider to use ('ollama', 'openai', 'gemini'). | -### Wyoming (Local) Configuration +### Audio Input -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-wyoming-ip` | Wyoming ASR server IP | `localhost` | -| `--asr-wyoming-port` | Wyoming ASR server port | `10300` | +| Option | Default | Description | +|--------|---------|-------------| +| `--input-device-index` | - | Index of the audio input device to use. | +| `--input-device-name` | - | Device name keywords for partial matching. | +| `--list-devices` | `false` | List available audio input and output devices and exit. | -### OpenAI ASR Configuration +### Audio Input: Wyoming -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-openai-model` | OpenAI ASR model | `whisper-1` | -| `--asr-openai-base-url` | Custom Whisper server URL | - | -| `--asr-openai-prompt` | Custom prompt to guide transcription | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-wyoming-ip` | `localhost` | Wyoming ASR server IP address. | +| `--asr-wyoming-port` | `10300` | Wyoming ASR server port. | -### LLM (Ollama, local) +### Audio Input: OpenAI-compatible -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-ollama-model` | Ollama model to use | `gemma3:4b` | -| `--llm-ollama-host` | Ollama server URL | `http://localhost:11434` | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-openai-model` | `whisper-1` | The OpenAI model to use for ASR (transcription). | +| `--asr-openai-base-url` | - | Custom base URL for OpenAI-compatible ASR API (e.g., for custom Whisper server: http://localhost:9898). | +| `--asr-openai-prompt` | - | Custom prompt to guide transcription (optional). | -### LLM (OpenAI) +### LLM: Ollama -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-openai-model` | OpenAI model to use | `gpt-5-mini` | -| `--openai-api-key` | OpenAI API key (or set `OPENAI_API_KEY`) | - | -| `--openai-base-url` | Custom OpenAI-compatible API URL (or set `OPENAI_BASE_URL`) | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-ollama-model` | `gemma3:4b` | The Ollama model to use. Default is gemma3:4b. | +| `--llm-ollama-host` | `http://localhost:11434` | The Ollama server host. Default is http://localhost:11434. | -### LLM (Gemini) +### LLM: OpenAI-compatible -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-gemini-model` | Gemini model to use | `gemini-2.5-flash` | -| `--gemini-api-key` | Gemini API key (or set `GEMINI_API_KEY`) | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-openai-model` | `gpt-5-mini` | The OpenAI model to use for LLM tasks. | +| `--openai-api-key` | - | Your OpenAI API key. Can also be set with the OPENAI_API_KEY environment variable. | +| `--openai-base-url` | - | Custom base URL for OpenAI-compatible API (e.g., for llama-server: http://localhost:8080/v1). | -### LLM Cleanup +### LLM: Gemini -| Option | Description | Default | -|--------|-------------|---------| -| `--llm` / `--no-llm` | Use LLM to process transcript | `false` | -| `--extra-instructions` | Additional LLM instructions | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-gemini-model` | `gemini-2.5-flash` | The Gemini model to use for LLM tasks. | +| `--gemini-api-key` | - | Your Gemini API key. Can also be set with the GEMINI_API_KEY environment variable. | ### Process Management -| Option | Description | -|--------|-------------| -| `--stop` | Stop running background process | -| `--status` | Check if background process is running | -| `--toggle` | Toggle background process on/off | +| Option | Default | Description | +|--------|---------|-------------| +| `--stop` | `false` | Stop any running background process. | +| `--status` | `false` | Check if a background process is running. | +| `--toggle` | `false` | Toggle the background process on/off. If the process is running, it will be stopped. If the process is not running, it will be started. | ### General Options -| Option | Description | Default | -|--------|-------------|---------| -| `--clipboard` / `--no-clipboard` | Copy result to clipboard | `true` | -| `--transcription-log PATH` | Log transcriptions with timestamps | - | -| `--log-level` | Set logging level | `WARNING` | -| `--log-file PATH` | Path to a file to write logs to | - | -| `--quiet`, `-q` | Suppress console output | `false` | -| `--config PATH` | Path to a TOML configuration file | - | -| `--print-args` | Print resolved arguments including config values | `false` | +| Option | Default | Description | +|--------|---------|-------------| +| `--clipboard/--no-clipboard` | `true` | Copy result to clipboard. | +| `--log-level` | `WARNING` | Set logging level. | +| `--log-file` | - | Path to a file to write logs to. | +| `--quiet` | `false` | Suppress console output from rich. | +| `--config` | - | Path to a TOML configuration file. | +| `--print-args` | `false` | Print the command line arguments, including variables taken from the configuration file. | +| `--transcription-log` | - | Path to log transcription results with timestamps, hostname, model, and raw output. | + + + ## Workflow Integration diff --git a/docs/commands/voice-edit.md b/docs/commands/voice-edit.md index 5adbb2ba0..a92cc6c2c 100644 --- a/docs/commands/voice-edit.md +++ b/docs/commands/voice-edit.md @@ -45,116 +45,120 @@ agent-cli voice-edit --stop ## Options + + + + + + ### Provider Selection -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-provider` | ASR provider: `wyoming`, `openai` | `wyoming` | -| `--llm-provider` | LLM provider: `ollama`, `openai`, `gemini` | `ollama` | -| `--tts-provider` | TTS provider: `wyoming`, `openai`, `kokoro` | `wyoming` | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-provider` | `wyoming` | The ASR provider to use ('wyoming', 'openai'). | +| `--llm-provider` | `ollama` | The LLM provider to use ('ollama', 'openai', 'gemini'). | +| `--tts-provider` | `wyoming` | The TTS provider to use ('wyoming', 'openai', 'kokoro'). | ### Audio Input -| Option | Description | -|--------|-------------| -| `--input-device-index` | Index of audio input device | -| `--input-device-name` | Input device name keywords | -| `--list-devices` | List available devices | +| Option | Default | Description | +|--------|---------|-------------| +| `--input-device-index` | - | Index of the audio input device to use. | +| `--input-device-name` | - | Device name keywords for partial matching. | +| `--list-devices` | `false` | List available audio input and output devices and exit. | -### ASR (Wyoming, local) +### Audio Input: Wyoming -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-wyoming-ip` | Wyoming ASR server IP | `localhost` | -| `--asr-wyoming-port` | Wyoming ASR server port | `10300` | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-wyoming-ip` | `localhost` | Wyoming ASR server IP address. | +| `--asr-wyoming-port` | `10300` | Wyoming ASR server port. | -### ASR (OpenAI) +### Audio Input: OpenAI-compatible -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-openai-model` | OpenAI ASR model | `whisper-1` | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-openai-model` | `whisper-1` | The OpenAI model to use for ASR (transcription). | -### LLM (Ollama, local) +### LLM: Ollama -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-ollama-model` | Ollama model to use | `gemma3:4b` | -| `--llm-ollama-host` | Ollama server URL | `http://localhost:11434` | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-ollama-model` | `gemma3:4b` | The Ollama model to use. Default is gemma3:4b. | +| `--llm-ollama-host` | `http://localhost:11434` | The Ollama server host. Default is http://localhost:11434. | -### LLM (OpenAI) +### LLM: OpenAI-compatible -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-openai-model` | OpenAI model to use | `gpt-5-mini` | -| `--openai-api-key` | OpenAI API key (or set `OPENAI_API_KEY`) | - | -| `--openai-base-url` | Custom OpenAI-compatible API URL (or set `OPENAI_BASE_URL`) | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-openai-model` | `gpt-5-mini` | The OpenAI model to use for LLM tasks. | +| `--openai-api-key` | - | Your OpenAI API key. Can also be set with the OPENAI_API_KEY environment variable. | +| `--openai-base-url` | - | Custom base URL for OpenAI-compatible API (e.g., for llama-server: http://localhost:8080/v1). | -### LLM (Gemini) +### LLM: Gemini -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-gemini-model` | Gemini model to use | `gemini-2.5-flash` | -| `--gemini-api-key` | Gemini API key (or set `GEMINI_API_KEY`) | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-gemini-model` | `gemini-2.5-flash` | The Gemini model to use for LLM tasks. | +| `--gemini-api-key` | - | Your Gemini API key. Can also be set with the GEMINI_API_KEY environment variable. | -### TTS Options (General) +### Audio Output -| Option | Description | Default | -|--------|-------------|---------| -| `--tts` / `--no-tts` | Enable text-to-speech response | `false` | -| `--tts-speed` | Speech speed multiplier | `1.0` | -| `--output-device-index` | Index of audio output device | - | -| `--output-device-name` | Output device name keywords | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts/--no-tts` | `false` | Enable text-to-speech for responses. | +| `--output-device-index` | - | Index of the audio output device to use for TTS. | +| `--output-device-name` | - | Output device name keywords for partial matching. | +| `--tts-speed` | `1.0` | Speech speed multiplier (1.0 = normal, 2.0 = twice as fast, 0.5 = half speed). | -### TTS (Wyoming, local) +### Audio Output: Wyoming -| Option | Description | Default | -|--------|-------------|---------| -| `--tts-wyoming-ip` | Wyoming TTS server IP | `localhost` | -| `--tts-wyoming-port` | Wyoming TTS server port | `10200` | -| `--tts-wyoming-voice` | Voice name for Wyoming TTS | - | -| `--tts-wyoming-language` | Language for Wyoming TTS | - | -| `--tts-wyoming-speaker` | Speaker name for Wyoming TTS voice | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts-wyoming-ip` | `localhost` | Wyoming TTS server IP address. | +| `--tts-wyoming-port` | `10200` | Wyoming TTS server port. | +| `--tts-wyoming-voice` | - | Voice name to use for Wyoming TTS (e.g., 'en_US-lessac-medium'). | +| `--tts-wyoming-language` | - | Language for Wyoming TTS (e.g., 'en_US'). | +| `--tts-wyoming-speaker` | - | Speaker name for Wyoming TTS voice. | -### TTS (OpenAI) +### Audio Output: OpenAI-compatible -| Option | Description | Default | -|--------|-------------|---------| -| `--tts-openai-model` | OpenAI TTS model | `tts-1` | -| `--tts-openai-voice` | OpenAI voice | `alloy` | -| `--tts-openai-base-url` | Custom OpenAI-compatible URL | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts-openai-model` | `tts-1` | The OpenAI model to use for TTS. | +| `--tts-openai-voice` | `alloy` | The voice to use for OpenAI TTS. | +| `--tts-openai-base-url` | - | Custom base URL for OpenAI-compatible TTS API (e.g., http://localhost:8000/v1 for a proxy). | -### TTS (Kokoro) +### Audio Output: Kokoro -| Option | Description | Default | -|--------|-------------|---------| -| `--tts-kokoro-model` | Kokoro model | `kokoro` | -| `--tts-kokoro-voice` | Kokoro voice | `af_sky` | -| `--tts-kokoro-host` | Kokoro API URL | `http://localhost:8880/v1` | - -### Output Options - -| Option | Description | Default | -|--------|-------------|---------| -| `--clipboard` / `--no-clipboard` | Copy result to clipboard | `true` | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts-kokoro-model` | `kokoro` | The Kokoro model to use for TTS. | +| `--tts-kokoro-voice` | `af_sky` | The voice to use for Kokoro TTS. | +| `--tts-kokoro-host` | `http://localhost:8880/v1` | The base URL for the Kokoro API. | ### Process Management -| Option | Description | -|--------|-------------| -| `--stop` | Stop running background process | -| `--status` | Check if process is running | -| `--toggle` | Toggle process on/off | +| Option | Default | Description | +|--------|---------|-------------| +| `--stop` | `false` | Stop any running background process. | +| `--status` | `false` | Check if a background process is running. | +| `--toggle` | `false` | Toggle the background process on/off. If the process is running, it will be stopped. If the process is not running, it will be started. | ### General Options -| Option | Description | Default | -|--------|-------------|---------| -| `--save-file PATH` | Save TTS response audio to WAV file | - | -| `--log-level` | Set logging level | `WARNING` | -| `--log-file PATH` | Path to a file to write logs to | - | -| `--quiet`, `-q` | Suppress console output | `false` | -| `--config PATH` | Path to a TOML configuration file | - | -| `--print-args` | Print resolved arguments including config values | `false` | +| Option | Default | Description | +|--------|---------|-------------| +| `--save-file` | - | Save TTS response audio to WAV file. | +| `--clipboard/--no-clipboard` | `true` | Copy result to clipboard. | +| `--log-level` | `WARNING` | Set logging level. | +| `--log-file` | - | Path to a file to write logs to. | +| `--quiet` | `false` | Suppress console output from rich. | +| `--config` | - | Path to a TOML configuration file. | +| `--print-args` | `false` | Print the command line arguments, including variables taken from the configuration file. | + + + ## Hotkey Integration diff --git a/docs/update_docs.py b/docs/update_docs.py new file mode 100755 index 000000000..b29772a53 --- /dev/null +++ b/docs/update_docs.py @@ -0,0 +1,70 @@ +#!/usr/bin/env python3 +"""Update all markdown files that use markdown-code-runner for auto-generation. + +Run from repo root: python docs/update_docs.py +""" + +from __future__ import annotations + +import subprocess +import sys +from pathlib import Path + +from rich.console import Console + +console = Console() + + +def find_markdown_files_with_code_blocks(docs_dir: Path) -> list[Path]: + """Find all markdown files containing markdown-code-runner markers.""" + files_with_code = [] + for md_file in docs_dir.rglob("*.md"): + content = md_file.read_text() + # Match both CODE:START and CODE:BASH:START patterns + if "" in content or "" in content: + files_with_code.append(md_file) + return sorted(files_with_code) + + +def run_markdown_code_runner(files: list[Path], repo_root: Path) -> bool: + """Run markdown-code-runner on all files. Returns True if all succeeded.""" + if not files: + console.print("No files with CODE:START markers found.") + return True + + console.print(f"Found {len(files)} file(s) with auto-generated content:") + for f in files: + console.print(f" - {f.relative_to(repo_root)}") + console.print() + + all_success = True + for file in files: + rel_path = file.relative_to(repo_root) + console.print(f"Updating {rel_path}...", end=" ") + result = subprocess.run( + ["markdown-code-runner", str(file)], # noqa: S607 + check=False, + capture_output=True, + text=True, + ) + if result.returncode == 0: + console.print("[green]✓[/green]") + else: + console.print("[red]✗[/red]") + console.print(f" [red]Error:[/red] {result.stderr}") + all_success = False + + return all_success + + +def main() -> int: + """Main entry point.""" + repo_root = Path(__file__).parent.parent + + files = find_markdown_files_with_code_blocks(repo_root) + success = run_markdown_code_runner(files, repo_root) + return 0 if success else 1 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tests/test_docs_gen.py b/tests/test_docs_gen.py new file mode 100644 index 000000000..addea298e --- /dev/null +++ b/tests/test_docs_gen.py @@ -0,0 +1,286 @@ +"""Tests for the docs_gen module.""" + +from __future__ import annotations + +from agent_cli.docs_gen import ( + _format_default, + _get_command_options, + _list_commands, + _options_by_panel, + _options_table, + all_options_for_docs, + commands_table, + config_example, + env_vars_table, + provider_matrix, +) + +# --- Tests for _format_default --- + + +def test_format_default_none_returns_dash() -> None: + """Test that None returns a dash.""" + assert _format_default(None) == "-" + + +def test_format_default_bool_true() -> None: + """Test that True returns lowercase 'true'.""" + assert _format_default(True) == "true" + + +def test_format_default_bool_false() -> None: + """Test that False returns lowercase 'false'.""" + assert _format_default(False) == "false" + + +def test_format_default_empty_string() -> None: + """Test that empty string returns quoted empty string.""" + assert _format_default("") == '""' + + +def test_format_default_string_value() -> None: + """Test that string values are returned as-is.""" + assert _format_default("hello") == "hello" + + +def test_format_default_integer_value() -> None: + """Test that integer values are converted to string.""" + assert _format_default(42) == "42" + + +# --- Tests for _get_command_options --- + + +def test_get_command_options_transcribe() -> None: + """Test that transcribe command options are extracted.""" + options = _get_command_options("transcribe") + assert len(options) > 0 + for opt in options: + assert "name" in opt + assert "type" in opt + assert "default" in opt + assert "help" in opt + assert "panel" in opt + + +def test_get_command_options_nonexistent() -> None: + """Test that nonexistent command returns empty list.""" + options = _get_command_options("nonexistent") + assert options == [] + + +def test_get_command_options_subcommand() -> None: + """Test that subcommand options are extracted.""" + options = _get_command_options("memory.proxy") + assert len(options) > 0 + + +# --- Tests for _options_table --- + + +def test_options_table_generates_markdown() -> None: + """Test that options_table generates valid markdown table.""" + table = _options_table("transcribe") + assert "|" in table + assert "Option" in table + assert "Description" in table + + +def test_options_table_filter_by_panel() -> None: + """Test that panel filtering works.""" + table = _options_table("transcribe", panel="LLM Configuration") + assert "--llm" in table + assert "--asr-wyoming-ip" not in table + + +def test_options_table_nonexistent_panel() -> None: + """Test that nonexistent panel returns appropriate message.""" + table = _options_table("transcribe", panel="Nonexistent Panel") + assert "No options found" in table + + +def test_options_table_include_type_false() -> None: + """Test that include_type=False excludes Type column.""" + table = _options_table("transcribe", include_type=False) + lines = table.split("\n") + header = lines[0] + assert "Option" in header + assert "Default" in header + assert "Description" in header + + +# --- Tests for _options_by_panel --- + + +def test_options_by_panel_groups() -> None: + """Test that options are grouped by panel with headers.""" + result = _options_by_panel("transcribe") + assert "### " in result or "## " in result + + +def test_options_by_panel_heading_level() -> None: + """Test that heading level parameter works.""" + result = _options_by_panel("transcribe", heading_level=2) + assert "## " in result + + +def test_options_by_panel_nonexistent_command() -> None: + """Test that nonexistent command returns appropriate message.""" + result = _options_by_panel("nonexistent") + assert "No options found" in result + + +# --- Tests for _list_commands --- + + +def test_list_commands_returns_list() -> None: + """Test that list_commands returns a list.""" + commands = _list_commands() + assert isinstance(commands, list) + assert len(commands) > 0 + + +def test_list_commands_includes_known() -> None: + """Test that known commands are in the list.""" + commands = _list_commands() + assert "transcribe" in commands + assert "speak" in commands + + +def test_list_commands_includes_subcommands() -> None: + """Test that subcommands are included.""" + commands = _list_commands() + assert any("memory" in cmd for cmd in commands) + + +def test_list_commands_sorted() -> None: + """Test that commands are sorted alphabetically.""" + commands = _list_commands() + assert commands == sorted(commands) + + +# --- Tests for all_options_for_docs --- + + +def test_all_options_for_docs_complete() -> None: + """Test that all_options_for_docs generates complete documentation.""" + result = all_options_for_docs("transcribe") + assert len(result) > 100 + assert "###" in result + assert "|" in result + + +def test_all_options_for_docs_includes_panels() -> None: + """Test that expected panels are included.""" + result = all_options_for_docs("transcribe") + assert "LLM Configuration" in result + assert "Audio Input" in result + assert "General Options" in result + + +def test_all_options_for_docs_nonexistent() -> None: + """Test that nonexistent command returns appropriate message.""" + result = all_options_for_docs("nonexistent") + assert "No options found" in result + + +# --- Tests for env_vars_table --- + + +def test_env_vars_table_generates() -> None: + """Test that env_vars_table generates valid table.""" + table = env_vars_table() + assert "|" in table + assert "Variable" in table + assert "Description" in table + + +def test_env_vars_table_includes_known() -> None: + """Test that known env vars are included.""" + table = env_vars_table() + assert "OPENAI_API_KEY" in table + assert "GEMINI_API_KEY" in table + + +# --- Tests for provider_matrix --- + + +def test_provider_matrix_generates() -> None: + """Test that provider_matrix generates valid table.""" + table = provider_matrix() + assert "|" in table + assert "Capability" in table + + +def test_provider_matrix_includes_providers() -> None: + """Test that known providers are included.""" + table = provider_matrix() + assert "ollama" in table + assert "openai" in table + assert "wyoming" in table + + +# --- Tests for commands_table --- + + +def test_commands_table_generates() -> None: + """Test that commands_table generates valid table.""" + table = commands_table() + assert "|" in table + assert "Command" in table + assert "Purpose" in table + + +def test_commands_table_includes_known() -> None: + """Test that known commands are included.""" + table = commands_table() + assert "transcribe" in table + assert "speak" in table + + +def test_commands_table_filter_by_category() -> None: + """Test that category filtering works.""" + table = commands_table(category="voice") + assert "transcribe" in table + assert "speak" in table + assert "install-services" not in table + + +def test_commands_table_nonexistent_category() -> None: + """Test that nonexistent category returns appropriate message.""" + table = commands_table(category="nonexistent") + assert "No commands found" in table + + +def test_commands_table_generates_links() -> None: + """Test that commands_table generates markdown links.""" + table = commands_table() + assert ".md)" in table + + +# --- Tests for config_example --- + + +def test_config_example_defaults() -> None: + """Test that config_example generates defaults section.""" + config = config_example() + assert "[defaults]" in config + assert "llm_provider" in config + + +def test_config_example_command() -> None: + """Test that config_example generates command section.""" + config = config_example("transcribe") + assert "[transcribe]" in config + + +def test_config_example_nonexistent() -> None: + """Test that nonexistent command returns appropriate message.""" + config = config_example("nonexistent") + assert "No configurable options" in config + + +def test_config_example_subcommand_section() -> None: + """Test that subcommand dots are replaced with dashes in section name.""" + config = config_example("memory.proxy") + assert "[memory-proxy]" in config diff --git a/zensical.toml b/zensical.toml index d11e87f2c..106faea7a 100644 --- a/zensical.toml +++ b/zensical.toml @@ -75,7 +75,6 @@ features = [ "navigation.instant", "navigation.instant.prefetch", "navigation.path", - "navigation.sections", "navigation.top", "navigation.tracking", "search.highlight",