agent-cli 0.97.2__tar.gz → 0.98.0__tar.gz

{agent_cli-0.97.2 → agent_cli-0.98.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-cli
-Version: 0.97.2
+Version: 0.98.0
 Summary: A suite of AI-powered command-line tools for text correction, audio transcription, and voice assistance.
 Project-URL: Homepage, https://github.com/basnijholt/agent-cli
 Author-email: Bas Nijholt <bas@nijho.lt>

{agent_cli-0.97.2 → agent_cli-0.98.0}/agent_cli/install/service_config.py

@@ -10,6 +10,8 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING, NamedTuple
 
+from agent_cli.core.deps import _uv_tool_extra_args
+
 if TYPE_CHECKING:
     from collections.abc import Callable
 
@@ -35,6 +37,12 @@ class ServiceConfig:
 
 # TTS services that are mutually exclusive (same ports)
 TTS_SERVICES = ("tts-kokoro", "tts-piper")
+_WHISPER_BACKEND_EXTRAS = {
+    "faster-whisper",
+    "mlx-whisper",
+    "whisper-transformers",
+    "nemo-whisper",
+}
 
 
 def detect_preferred_tts() -> str:
@@ -127,14 +135,20 @@ def build_service_command(
 ) -> list[str]:
     """Build the command args for running a service via uv tool run."""
     extra = (service.macos_extra or service.extra) if use_macos_extra else service.extra
+    extra = _service_extra_for_command(service, extra, extra_command_args)
+    extras = _split_extras(extra)
     package_source = os.environ.get("AGENTCLI_PACKAGE_SOURCE", "agent-cli")
 
     args = [str(uv_path), "tool", "run"]
 
     # Add python version constraint (skip on macOS when using macos_extra,
     # since macos_extra typically avoids deps that lack py3.14 wheels)
-    if service.python_version and not (use_macos_extra and service.macos_extra):
+    uses_macos_extra_without_python_pin = (
+        use_macos_extra and service.macos_extra and "nemo-whisper" not in extras
+    )
+    if service.python_version and not uses_macos_extra_without_python_pin:
         args.extend(["--python", service.python_version])
+    args.extend(_uv_tool_extra_args(extras))
 
     # Build the command: either custom command path or default "server <name>"
     cmd_path = service.command or ["server", service.name]
@@ -152,6 +166,45 @@ def build_service_command(
     return args
 
 
+def _service_extra_for_command(
+    service: ServiceConfig,
+    extra: str,
+    extra_command_args: list[str] | None,
+) -> str:
+    """Adjust service extras when custom daemon args select a specific backend."""
+    if service.name != "whisper" or not _uses_nemo_backend(extra_command_args):
+        return extra
+
+    parts = _split_extras(extra)
+    result: list[str] = []
+    inserted = False
+    for part in parts:
+        if part in _WHISPER_BACKEND_EXTRAS:
+            if not inserted:
+                result.append("nemo-whisper")
+                inserted = True
+            continue
+        result.append(part)
+
+    if not inserted:
+        result.append("nemo-whisper")
+    return ",".join(result)
+
+
+def _split_extras(extra: str) -> list[str]:
+    return [part.strip() for part in extra.split(",") if part.strip()]
+
+
+def _uses_nemo_backend(extra_command_args: list[str] | None) -> bool:
+    args = extra_command_args or []
+    for index, arg in enumerate(args):
+        if arg in {"--backend", "-b"} and index + 1 < len(args):
+            return args[index + 1] == "nemo"
+        if arg in {"--backend=nemo", "-b=nemo"}:
+            return True
+    return False
+
+
 def find_uv(extra_paths: list[Path] | None = None) -> Path | None:
     """Find uv executable, preferring system paths over virtualenv."""
     explicit_uv = os.environ.get("AGENTCLI_UV_PATH")

{agent_cli-0.97.2 → agent_cli-0.98.0}/agent_cli/server/whisper/backends/nemo.py

@@ -240,6 +240,7 @@ def _ensure_validation_ds_config(model: Any) -> None:
         return
 
     if validation_ds is None:
+        # TODO(NVIDIA-NeMo/NeMo#15752): Drop after NeMo release.  # noqa: FIX002
         _set_config_value(config, "validation_ds", {})
 
 

{agent_cli-0.97.2 → agent_cli-0.98.0}/docs/commands/install-extras.md

@@ -83,3 +83,16 @@ agent-cli install-extras rag memory vad
 # Install all extras
 agent-cli install-extras --all
 ```
+
+## NeMo / Parakeet
+
+Use the runtime installer for NVIDIA NeMo support:
+
+```bash
+agent-cli install-extras nemo-whisper wyoming
+agent-cli server whisper --backend nemo
+```
+
+This matters on Python 3.14. Plain `pip install "agent-cli[nemo-whisper]"` uses
+the published extra metadata, while `agent-cli install-extras nemo-whisper` can
+apply agent-cli's temporary uv override for the pinned NeMo Git build.

{agent_cli-0.97.2 → agent_cli-0.98.0}/docs/commands/server/index.md

@@ -57,7 +57,7 @@ While Faster Whisper, Piper, and Kokoro are all available as standalone servers,
 
 2. **TTL-based memory management** - Like [LlamaSwap](https://github.com/mostlygeek/llama-swap), models load on-demand and automatically unload after idle periods. Run voice services 24/7 without permanently consuming RAM/VRAM - memory is freed when you're not actively using speech features.
 
-3. **Multi-platform acceleration** - Whisper automatically uses the optimal backend: [MLX Whisper](https://github.com/ml-explore/mlx-examples/tree/main/whisper) on Apple Silicon for native Metal acceleration, [Faster Whisper](https://github.com/SYSTRAN/faster-whisper) on Linux/CUDA for GPU acceleration.
+3. **Multi-platform acceleration** - Whisper automatically uses the optimal backend: [MLX Whisper](https://github.com/ml-explore/mlx-examples/tree/main/whisper) on Apple Silicon for native Metal acceleration, [Faster Whisper](https://github.com/SYSTRAN/faster-whisper) on Linux/CUDA for GPU acceleration, and [NVIDIA NeMo](https://github.com/NVIDIA/NeMo) for Parakeet models.
 
 4. **Unified configuration** - Consistent CLI interface, environment variables, and Docker setup across all services.
 

{agent_cli-0.97.2 → agent_cli-0.98.0}/docs/commands/server/whisper.md

@@ -34,6 +34,12 @@ Run a local ASR server with automatic backend selection based on your platform:
 >   --default-language en
 > ```
 >
+> NVIDIA Parakeet via NeMo:
+> ```bash
+> agent-cli install-extras nemo-whisper wyoming
+> agent-cli server whisper --backend nemo
+> ```
+>
 > Use it with any OpenAI-compatible client, or configure agent-cli to use it - see [Configuration](../../configuration.md#using-local-whisper-server).
 
 ## Features
@@ -74,6 +80,12 @@ agent-cli server whisper --device cpu
 agent-cli server whisper --model large-v3 --download-only
 
 # Run NVIDIA Parakeet via NeMo
+agent-cli server whisper --backend nemo
+
+# Keep Parakeet loaded after first request (avoids repeated load cost)
+agent-cli server whisper --backend nemo --ttl 0
+
+# Run a specific Parakeet model instead of the NeMo default
 agent-cli server whisper --backend nemo --model parakeet-tdt-0.6b-v3
 
 # Preload model at startup and wait until ready
@@ -287,15 +299,62 @@ Notes for Cohere Transcribe:
 
 ### NVIDIA NeMo (Parakeet)
 
-For NeMo models like `nvidia/parakeet-tdt-0.6b-v3`:
+The NeMo backend runs NVIDIA Parakeet models behind the same OpenAI-compatible
+HTTP API and Wyoming protocol as the other Whisper backends. With `--backend
+nemo`, the default model is `parakeet-unified-en-0.6b`.
+
+Install the runtime dependencies:
 
 ```bash
-pip install "agent-cli[nemo-whisper,wyoming]"
-agent-cli server whisper --backend nemo --model parakeet-tdt-0.6b-v3
+agent-cli install-extras nemo-whisper wyoming
+```
+
+Start the server:
+
+```bash
+agent-cli server whisper --backend nemo
 ```
 
-NeMo models are currently transcription-only in this server. Requests to
-`/v1/audio/translations` return `400` for `--backend nemo`.
+Use it from agent-cli through either protocol:
+
+```bash
+# OpenAI-compatible HTTP API
+ag transcribe \
+  --asr-provider openai \
+  --asr-openai-base-url http://localhost:10301/v1
+
+# Wyoming protocol
+ag transcribe \
+  --asr-provider wyoming \
+  --asr-wyoming-ip localhost \
+  --asr-wyoming-port 10300
+```
+
+Run it as a daemon with persistent arguments:
+
+```bash
+agent-cli daemon install whisper -y -- \
+  --backend nemo \
+  --model parakeet-unified-en-0.6b \
+  --ttl 0
+```
+
+Notes for NeMo/Parakeet:
+
+- `--backend nemo` defaults to `parakeet-unified-en-0.6b`.
+- `--backend auto` switches to NeMo when any requested model name is a Parakeet model.
+- NeMo uses CUDA when available and CPU otherwise; it does not use MLX/MPS on Apple Silicon.
+- First request can be slow because the model loads lazily. Use `--preload` to load at startup, or `--ttl 0` to keep it loaded after the first request.
+- REST uploads can be WAV, MP3, M4A, FLAC, OGG, AAC, or WebM when `ffmpeg` is available.
+- NeMo models are currently transcription-only in this server. Requests to `/v1/audio/translations` return `400`.
+- Segment formats (`verbose_json`, `srt`, `vtt`) require timestamp output from the selected NeMo model.
+
+Python 3.14 note:
+
+On Python 3.14, the plain published extra path does not apply agent-cli's NeMo
+override. The `agent-cli install-extras nemo-whisper` path is uv-aware and can
+apply agent-cli's temporary pinned NeMo Git install plus override file. Prefer it
+over plain `pip install "agent-cli[nemo-whisper]"` on Python 3.14.
 
 ### Docker
 

{agent_cli-0.97.2 → agent_cli-0.98.0}/docs/configuration.md

@@ -241,6 +241,7 @@ Add to your config file so all commands use your local server:
 ```toml
 [defaults]
 asr_provider = "wyoming"
+asr_wyoming_ip = "localhost"
 asr_wyoming_port = 10300
 ```
 
@@ -260,6 +261,37 @@ Now just run `agent-cli transcribe` - it automatically uses your local server.
 > **OpenAI SDK users:** The server also exposes an OpenAI-compatible API on port 10301.
 > See [server whisper docs](commands/server/whisper.md) for all options.
 
+### NVIDIA Parakeet via NeMo
+
+Start a Parakeet server:
+
+```bash
+agent-cli install-extras nemo-whisper wyoming
+agent-cli server whisper --backend nemo --ttl 0
+```
+
+`--backend nemo` defaults to `parakeet-unified-en-0.6b`. `--ttl 0` keeps the
+model loaded after the first request, which is useful because NeMo model loading
+is expensive.
+
+Use it from agent-cli through Wyoming:
+
+```toml
+[defaults]
+asr_provider = "wyoming"
+asr_wyoming_ip = "localhost"
+asr_wyoming_port = 10300
+```
+
+Or through the OpenAI-compatible HTTP API:
+
+```toml
+[defaults]
+asr_provider = "openai"
+asr_openai_base_url = "http://localhost:10301/v1"
+asr_openai_model = "whisper-1"
+```
+
 ## Audio Device Configuration
 
 ```toml

{agent_cli-0.97.2 → agent_cli-0.98.0}/macos/AgentCLI/Sources/AgentCLI/AgentCommand.swift

@@ -15,6 +15,7 @@ struct AgentCommand {
     let title: String
     let arguments: [String]
     let appliesTranscriptionExtraInstructions: Bool
+    let appliesTranscriptionDaemonSettings: Bool
     let forceBootstrap: Bool
     let bootstrapRequirement: AgentBootstrapRequirement
     let showsRecordingIndicator: Bool
@@ -27,6 +28,7 @@ struct AgentCommand {
         title: String,
         arguments: [String],
         appliesTranscriptionExtraInstructions: Bool = false,
+        appliesTranscriptionDaemonSettings: Bool = false,
         forceBootstrap: Bool = false,
         bootstrapRequirement: AgentBootstrapRequirement = .cliRuntime,
         showsRecordingIndicator: Bool = false,
@@ -38,6 +40,7 @@ struct AgentCommand {
         self.title = title
         self.arguments = arguments
         self.appliesTranscriptionExtraInstructions = appliesTranscriptionExtraInstructions
+        self.appliesTranscriptionDaemonSettings = appliesTranscriptionDaemonSettings
         self.forceBootstrap = forceBootstrap
         self.bootstrapRequirement = bootstrapRequirement
         self.showsRecordingIndicator = showsRecordingIndicator
@@ -46,7 +49,14 @@ struct AgentCommand {
         self.finishNotificationTitle = finishNotificationTitle
     }
 
-    func resolvedArguments(extraInstructions: String?) -> [String] {
+    func resolvedArguments(
+        extraInstructions: String?,
+        transcriptionDaemonArguments: [String]? = nil
+    ) -> [String] {
+        if appliesTranscriptionDaemonSettings {
+            return transcriptionDaemonArguments ?? arguments
+        }
+
         guard appliesTranscriptionExtraInstructions else { return arguments }
 
         let trimmedInstructions = extraInstructions?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
@@ -110,7 +120,8 @@ struct AgentCommand {
     static let installVoiceService = AgentCommand(
         identifier: "install-voice-service",
         title: "Install Voice Service",
-        arguments: ["daemon", "install", "whisper", "-y"]
+        arguments: ["daemon", "install", "whisper", "-y"],
+        appliesTranscriptionDaemonSettings: true
     )
 
     static let installOrUpdateCLI = AgentCommand(

{agent_cli-0.97.2 → agent_cli-0.98.0}/macos/AgentCLI/Sources/AgentCLI/AgentCommandRunner.swift

@@ -207,7 +207,13 @@ final class AgentCommandRunner: ObservableObject {
 
         let bootstrap = self.bootstrap
         let reportBootstrapPhase = makeBootstrapProgressReporter()
-        let commandArguments = command.resolvedArguments(extraInstructions: TranscriptionSettings.extraInstructions)
+        let transcriptionDaemonArguments = AgentRuntime.shared.usesUserInstalledAgentCLI
+            ? nil
+            : TranscriptionSettings.whisperDaemonInstallArguments()
+        let commandArguments = command.resolvedArguments(
+            extraInstructions: TranscriptionSettings.extraInstructions,
+            transcriptionDaemonArguments: transcriptionDaemonArguments
+        )
         DispatchQueue.global(qos: .userInitiated).async {
             let bootstrapResult = bootstrap(command.bootstrapRequirement, command.forceBootstrap, reportBootstrapPhase)
             guard bootstrapResult.exitCode == 0 else {

{agent_cli-0.97.2 → agent_cli-0.98.0}/macos/AgentCLI/Sources/AgentCLI/AgentRuntime.swift

@@ -338,7 +338,10 @@ struct AgentRuntime {
 
     private func installWhisperDaemon(progress: AgentBootstrapProgress) -> CommandResult {
         progress(.installingVoiceService)
-        let result = runAgentCLI(arguments: ["daemon", "ensure", "whisper", "--quiet"])
+        let arguments = runtimeMode == .bundled
+            ? TranscriptionSettings.whisperDaemonInstallArguments(userDefaults: userDefaults)
+            : ["daemon", "ensure", "whisper", "--quiet"]
+        let result = runAgentCLI(arguments: arguments)
         guard result.exitCode == 0 else {
             return result
         }
@@ -354,7 +357,13 @@ struct AgentRuntime {
 
     private var whisperDaemonMarkerContents: String {
         let modeName = runtimeMode == .userInstalled ? "user-installed" : "bundled"
-        return "runtimeMode=\(modeName)\npackageSource=\(agentCLIPackageSource)\n"
+        var contents = "runtimeMode=\(modeName)\npackageSource=\(agentCLIPackageSource)\n"
+        if runtimeMode == .bundled {
+            let backend = TranscriptionSettings.selectedBackend(userDefaults: userDefaults)
+            contents += "transcriptionBackend=\(backend.rawValue)\n"
+            contents += "transcriptionModel=\(TranscriptionSettings.selectedModelName(userDefaults: userDefaults))\n"
+        }
+        return contents
     }
 
     private func warmUpWhisperModel() -> CommandResult {

{agent_cli-0.97.2 → agent_cli-0.98.0}/macos/AgentCLI/Sources/AgentCLI/Shortcuts.swift

@@ -281,10 +281,18 @@ struct SettingsView: View {
     private var useUserInstalledAgentCLI = false
     @AppStorage(RecordingSoundSettings.enabledKey)
     private var recordingSoundsEnabled = false
+    @AppStorage(TranscriptionSettings.transcriptionBackendKey)
+    private var transcriptionBackend = TranscriptionBackend.whisper.rawValue
+    @AppStorage(TranscriptionSettings.transcriptionModelKey)
+    private var transcriptionModel = TranscriptionBackend.whisper.defaultModelName
     @AppStorage(TranscriptionSettings.transcriptionExtraInstructionsKey)
     private var transcriptionExtraInstructions = ""
     @State private var shortcutRevision = 0
 
+    private var selectedTranscriptionBackend: TranscriptionBackend {
+        TranscriptionBackend(rawValue: transcriptionBackend) ?? .whisper
+    }
+
     var body: some View {
         Form {
             Section {
@@ -311,6 +319,32 @@ struct SettingsView: View {
                 Text("Runs the agent-cli found on PATH with your normal config instead of the app's private bundled-uv runtime. Recording sounds use Frog when recording starts and Purr when recording ends.")
             }
 
+            Section {
+                Picker("Backend", selection: $transcriptionBackend) {
+                    ForEach(TranscriptionBackend.allCases) { backend in
+                        Text(backend.title).tag(backend.rawValue)
+                    }
+                }
+                .pickerStyle(.menu)
+                .disabled(useUserInstalledAgentCLI)
+
+                Picker("Model", selection: $transcriptionModel) {
+                    ForEach(selectedTranscriptionBackend.modelOptions) { model in
+                        Text(model.title).tag(model.id)
+                    }
+                }
+                .pickerStyle(.menu)
+                .disabled(useUserInstalledAgentCLI)
+            } header: {
+                Text("Voice Service")
+            } footer: {
+                Text(
+                    useUserInstalledAgentCLI
+                        ? "Disabled while User-Installed agent-cli is active."
+                        : "Changing these settings restarts the bundled voice service on next transcription."
+                )
+            }
+
             Section {
                 TextEditor(text: $transcriptionExtraInstructions)
                     .font(.body)
@@ -378,10 +412,20 @@ struct SettingsView: View {
         }
         .formStyle(.grouped)
         .padding()
+        .onChange(of: transcriptionBackend) { _ in
+            normalizeTranscriptionModel()
+        }
         .onAppear {
             loginItemController.refresh()
+            normalizeTranscriptionModel()
         }
     }
+
+    private func normalizeTranscriptionModel() {
+        let backend = selectedTranscriptionBackend
+        guard backend.modelOption(named: transcriptionModel) == nil else { return }
+        transcriptionModel = backend.defaultModelName
+    }
 }
 
 struct ShortcutRecorderRow: View {

agent_cli-0.98.0/macos/AgentCLI/Sources/AgentCLI/TranscriptionSettings.swift

@@ -0,0 +1,94 @@
+import Foundation
+
+struct TranscriptionModelOption: Identifiable, Equatable {
+    let id: String
+    let title: String
+}
+
+enum TranscriptionBackend: String, CaseIterable, Identifiable {
+    case whisper
+    case nemo
+
+    var id: String {
+        rawValue
+    }
+
+    var title: String {
+        switch self {
+        case .whisper:
+            return "Whisper"
+        case .nemo:
+            return "NeMo"
+        }
+    }
+
+    var cliBackend: String {
+        switch self {
+        case .whisper:
+            return "auto"
+        case .nemo:
+            return "nemo"
+        }
+    }
+
+    var defaultModelName: String {
+        modelOptions[0].id
+    }
+
+    var modelOptions: [TranscriptionModelOption] {
+        switch self {
+        case .whisper:
+            return [
+                TranscriptionModelOption(id: "large-v3", title: "Large v3"),
+                TranscriptionModelOption(id: "large-v3-turbo", title: "Turbo"),
+                TranscriptionModelOption(id: "small", title: "Small"),
+            ]
+        case .nemo:
+            return [
+                TranscriptionModelOption(id: "parakeet-unified-en-0.6b", title: "Parakeet Unified 0.6B"),
+                TranscriptionModelOption(id: "parakeet-tdt-0.6b-v3", title: "Parakeet TDT 0.6B v3"),
+                TranscriptionModelOption(id: "parakeet-tdt_ctc-110m", title: "Parakeet TDT CTC 110M"),
+            ]
+        }
+    }
+
+    func modelOption(named modelName: String) -> TranscriptionModelOption? {
+        modelOptions.first { $0.id == modelName }
+    }
+}
+
+enum TranscriptionSettings {
+    static let transcriptionExtraInstructionsKey = "transcriptionExtraInstructions"
+    static let transcriptionBackendKey = "transcriptionBackend"
+    static let transcriptionModelKey = "transcriptionModel"
+
+    static var extraInstructions: String {
+        UserDefaults.standard.string(forKey: transcriptionExtraInstructionsKey) ?? ""
+    }
+
+    static func selectedBackend(userDefaults: UserDefaults = .standard) -> TranscriptionBackend {
+        let rawValue = userDefaults.string(forKey: transcriptionBackendKey) ?? TranscriptionBackend.whisper.rawValue
+        return TranscriptionBackend(rawValue: rawValue) ?? .whisper
+    }
+
+    static func selectedModelName(userDefaults: UserDefaults = .standard) -> String {
+        let backend = selectedBackend(userDefaults: userDefaults)
+        let storedModelName = userDefaults.string(forKey: transcriptionModelKey) ?? ""
+        return backend.modelOption(named: storedModelName)?.id ?? backend.defaultModelName
+    }
+
+    static func whisperDaemonInstallArguments(userDefaults: UserDefaults = .standard) -> [String] {
+        let backend = selectedBackend(userDefaults: userDefaults)
+        return [
+            "daemon",
+            "install",
+            "whisper",
+            "-y",
+            "--",
+            "--backend",
+            backend.cliBackend,
+            "--model",
+            selectedModelName(userDefaults: userDefaults),
+        ]
+    }
+}