If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/argmaxinc/argmax-oss-swift shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1w ago
• 29+ active contributors
• Distributed ownership (top contributor 41% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live argmaxinc/argmax-oss-swift repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/argmaxinc/argmax-oss-swift.

What it runs against: a local clone of argmaxinc/argmax-oss-swift — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in argmaxinc/argmax-oss-swift | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 38 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of argmaxinc/argmax-oss-swift. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/argmaxinc/argmax-oss-swift.git
#   cd argmax-oss-swift
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of argmaxinc/argmax-oss-swift and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "argmaxinc/argmax-oss-swift(\\.git)?\\b" \\
  && ok "origin remote is argmaxinc/argmax-oss-swift" \\
  || miss "origin remote is not argmaxinc/argmax-oss-swift (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f ".swiftpm/configuration/Package.resolved" \\
  && ok ".swiftpm/configuration/Package.resolved" \\
  || miss "missing critical file: .swiftpm/configuration/Package.resolved"
test -f "Examples/TTS/TTSKitExample/TTSKitExample/ContentView.swift" \\
  && ok "Examples/TTS/TTSKitExample/TTSKitExample/ContentView.swift" \\
  || miss "missing critical file: Examples/TTS/TTSKitExample/TTSKitExample/ContentView.swift"
test -f "Examples/ServeCLIClient/Swift/Sources/WhisperKitSwiftClient/CLI.swift" \\
  && ok "Examples/ServeCLIClient/Swift/Sources/WhisperKitSwiftClient/CLI.swift" \\
  || miss "missing critical file: Examples/ServeCLIClient/Swift/Sources/WhisperKitSwiftClient/CLI.swift"
test -f ".github/workflows/release-tests.yml" \\
  && ok ".github/workflows/release-tests.yml" \\
  || miss "missing critical file: .github/workflows/release-tests.yml"
test -f "Examples/TTS/TTSKitExample/TTSKitExample/ModelManagementView.swift" \\
  && ok "Examples/TTS/TTSKitExample/TTSKitExample/ModelManagementView.swift" \\
  || miss "missing critical file: Examples/TTS/TTSKitExample/TTSKitExample/ModelManagementView.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 38 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~8d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/argmaxinc/argmax-oss-swift"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Argmax Open-Source SDK is a Swift package providing on-device speech AI inference for Apple Silicon Macs and iOS devices. It bundles WhisperKit (OpenAI Whisper speech-to-text), SpeakerKit (Pyannote speaker diarization), and TTSKit (Qwen-TTS text-to-speech) as ready-to-use Core ML models optimized for local inference without cloud dependencies. Monorepo structured as Swift Package Manager project (Package.swift at root): core libraries are compiled into the main package with Examples/ subdirectories (WhisperKit, TTSKit, SpeakerKit clients) providing reference implementations. CI workflows in .github/workflows/ orchestrate testing and distribution via Homebrew, SPM, and Expo updates.

Apple app developers (iOS/macOS) and ML engineers who need production-ready, privacy-preserving speech recognition, speaker diarization, and text-to-speech capabilities running entirely on-device on Apple Silicon without external API calls.

Production-ready with active maintenance: CI/CD pipelines in place (.github/workflows with release-tests.yml, unit-tests.yml, development-tests.yml), Swift Package Index visibility, and Homebrew distribution. The repo shows consistent updates (SwiftPM configuration is versioned in .swiftpm/Package.resolved) and 1.5M+ lines of Swift code indicate substantial maturity.

Low risk for core functionality but dependency on Apple Silicon-specific Core ML optimizations creates platform brittleness—changes to Xcode or Core ML toolchain could require rapid patching. Single-organization maintenance (Argmax Inc.) means roadmap depends on their commercial Pro SDK strategy rather than community-driven development. Lack of visible GitHub issue/PR data in provided structure makes open backlog unclear.

Active release cycle: multiple GitHub Actions workflows indicate ongoing testing (release-tests.yml, unit-tests.yml, development-tests.yml) and distribution automation (homebrew-update.yml, expo-update.yml). Example clients in Examples/ServeCLIClient show recent focus on HTTP client generation (updateClient.sh suggests OpenAPI/Swagger tooling integration for gRPC/REST APIs).

Clone and integrate via Swift Package Manager: git clone https://github.com/argmaxinc/argmax-oss-swift.git && cd argmax-oss-swift. For package consumers, add to Package.swift dependencies: .package(url: "https://github.com/argmaxinc/argmax-oss-swift", from: "0.x.0"). Or install via Homebrew: brew install argmax-oss-swift (requires macOS with Apple Silicon, Xcode 15+).

Daily commands: Clone repo, then in Swift project: swift build to compile, or swift test to run unit tests. For example clients: cd Examples/TTS/TTSKitExample && xcodebuild -scheme TTSKitExample for TTS demo app, or cd Examples/ServeCLIClient/Swift && swift run for CLI client. For Python examples: cd Examples/ServeCLIClient/Python && pip install -r requirements.txt && python test_transcribe.py.

• .swiftpm/configuration/Package.resolved — Swift Package Manager dependency lock file that pins all transitive dependencies for reproducible builds across the SDK
• Examples/TTS/TTSKitExample/TTSKitExample/ContentView.swift — Primary SwiftUI entry point demonstrating the core Text-to-Speech workflow and model integration patterns
• Examples/ServeCLIClient/Swift/Sources/WhisperKitSwiftClient/CLI.swift — CLI client showing how to integrate the speech recognition service API and handle async speech processing
• .github/workflows/release-tests.yml — CI/CD pipeline defining the test, build, and release process that validates the SDK across Apple Silicon targets
• Examples/TTS/TTSKitExample/TTSKitExample/ModelManagementView.swift — Core UI pattern for on-device model management, download, and lifecycle—essential for understanding the framework's model loading strategy
• Examples/ServeCLIClient/Swift/Package.swift — Swift package manifest defining dependencies and module structure for the client SDK

• ModelManagementView (SwiftUI, URLSession, Foundation File I/O) — Orchestrates model discovery, download, validation, and caching to the Documents directory
  • Failure mode: Network timeout → user must retry; corrupted model file → re-download required
• TTS — undefined

Add a New TTS Generation Parameter to the UI

1. Define the new parameter as a @State property in GenerationSettingsView.swift with a default value (Examples/TTS/TTSKitExample/TTSKitExample/GenerationSettingsView.swift)
2. Add a Form Section with a Picker or Slider control to let users adjust the parameter (Examples/TTS/TTSKitExample/TTSKitExample/GenerationSettingsView.swift)
3. Pass the parameter as an argument when calling the TTS generation API in ContentView.swift (Examples/TTS/TTSKitExample/TTSKitExample/ContentView.swift)

Add a New REST API Endpoint to the CLI Client

1. Update the OpenAPI service spec that generates the client types (external schema, regenerated via updateClient.sh) (Examples/ServeCLIClient/Swift/Sources/WhisperKitSwiftClient/Generated/Types.swift)
2. Run updateClient.sh to regenerate the Generated/Client.swift and Generated/Types.swift files (Examples/ServeCLIClient/Swift/updateClient.sh)
3. Add a new command handler in CLI.swift that instantiates the client and calls the new endpoint (Examples/ServeCLIClient/Swift/Sources/WhisperKitSwiftClient/CLI.swift)

Add Support for a New Compute Unit Strategy

1. Add the new compute unit option to the enum selector in ComputeUnitsView.swift (Examples/TTS/TTSKitExample/TTSKitExample/ComputeUnitsView.swift)
2. Update GenerationSettingsView.swift to conditionally show compute unit-specific configuration options (Examples/TTS/TTSKitExample/TTSKitExample/GenerationSettingsView.swift)
3. Pass the selected compute unit to the model loader in ContentView.swift when initializing the TTS pipeline (Examples/TTS/TTSKitExample/TTSKitExample/ContentView.swift)

• Swift + SwiftUI — Native performance on Apple Silicon; direct access to Metal, BNNS, and Core Audio APIs for on-device inference
• Swift Package Manager — Lightweight dependency management and ease of distribution for a single-platform SDK
• Metal Performance Shaders (MPS) / BNNS — Accelerated neural network inference on Apple Neural Engine and GPU; critical for real-time speech processing
• OpenAPI + Code Generation — Maintains API contract consistency between CLI and server; auto-generates type-safe client code

• On-device inference rather than cloud API

  • Why: User privacy and offline-first capability
  • Consequence: Higher device memory/storage footprint; model sizes and compute latency vary by hardware generation

• SwiftUI for example app instead of UIKit

  • Why: Modern, declarative UI with state management; iOS 15+ minimum reduces fragmentation
  • Consequence: Not compatible with older iOS versions; bindings and view hierarchy can become complex at scale

• Separate CLI client from core framework

  • Why: Decouples service integration from UI; allows Python/curl clients to coexist
  • Consequence: Requires maintaining multiple client implementations; potential for API drift

• Does not provide real-time streaming speech-to-text (buffered/batch transcription only)
• Does not offer cloud model hosting or remote inference
• Not cross-platform (macOS/iOS only; no Linux, Windows, or web support)
• Does not include built-in authentication or licensing enforcement beyond local validation

Core ML model download: WhisperKit/SpeakerKit/TTSKit require downloading large quantized .mlpackage models on first use (network + disk I/O can be slow; models are cached). Platform lock-in: Only runs on Apple Silicon (arm64) and macOS 13.5+ / iOS 16.4+; x86-64 Mac or Linux users cannot run it locally. Xcode version requirement: Likely requires Xcode 15+; older versions may fail Core ML model compilation. Model licensing: Models (Whisper from OpenAI, Pyannote, Qwen-TTS) have separate licenses; check Examples/ README files for attribution. No official API docs visible: README snippet shows SDK exists but actual API documentation likely lives in Wiki or external docs site (implied by 'app.argmaxinc.com/docs' references).

• Core ML Model Quantization — WhisperKit/SpeakerKit/TTSKit use quantized .mlpackage models (likely int8 or float16) to fit large Transformer models on-device with manageable memory/latency; understanding quantization tradeoffs (accuracy vs speed) is essential for model performance tuning.
• Neural Engine & ANE (Apple Neural Engine) — On Apple Silicon, Core ML offloads optimized ops (matrix multiply, convolution) to ANE co-processor for 5-10x speedup vs CPU; model architecture design (layer fusion, activation quantization) must account for ANE constraints.
• Encoder-Decoder Transformer Architecture — WhisperKit implements Whisper's encoder (audio → features) + decoder (features → tokens) pattern; understanding attention mechanisms, positional encoding, and token generation strategies is critical for extending speech-to-text.
• Speaker Diarization & Speaker Embeddings — SpeakerKit uses speaker embeddings (PLDA or similarity-based clustering) to segment audio by speaker; key for multi-speaker transcription and understanding speaker turn boundaries.
• Mel-Spectrogram & Speech Feature Extraction — WhisperKit and TTSKit both work with mel-scaled frequency spectrograms as intermediate audio representation; understanding STFT, mel-filtering, and log-compression is essential for audio preprocessing and debugging model inputs.
• gRPC Code Generation & Protocol Buffers — Examples/ServeCLIClient/Swift/updateClient.sh auto-generates Client.swift and Types.swift from .proto definitions; understanding protobuf serialization and gRPC streaming is needed for server integration or modifying client APIs.
• Swift Package Manager (SPM) & Package Resolution — .swiftpm/configuration/Package.resolved pins dependency versions; understanding SPM dependency graphs, binary targets, and resource bundles (for .mlpackage Core ML models) is essential for debugging build failures and contributing to dependency updates.

• openai/whisper — Original Whisper speech-to-text model that WhisperKit wraps as optimized Core ML package; reference implementation for audio transcription.
• apple/ml-ane-transformers — Apple's reference implementations for running Transformers on Neural Engine; architectural patterns for on-device inference optimization relevant to WhisperKit encoder-decoder design.
• pyannote/pyannote-audio — Upstream speaker diarization model that SpeakerKit is based on; needed to understand speaker embedding extraction and segmentation logic.
• QwenLM/Qwen-TTS — Source TTS model family that TTSKit packages; reference for understanding text encoding, duration prediction, and mel-spectrogram generation pipeline.
• argmaxinc/argmax-pro-sdk — Commercial Pro SDK companion offering advanced features (real-time transcription, custom vocabulary, non-native app support); defines boundary between open-source and proprietary capabilities.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for TTS example app (TTSKitExample)

The TTSKitExample directory contains a complete iOS app with multiple view controllers (ContentView, DetailView, ModelManagementView, GenerationSettingsView, ComputeUnitsView) but there's no corresponding test suite. The repo has unit-tests.yml and development-tests.yml workflows but no tests specifically validating the TTS UI components, audio generation pipeline, or model management logic. Adding XCTest-based integration tests would catch regressions in the user-facing TTS functionality.

• [ ] Create Examples/TTS/TTSKitExample/TTSKitExampleTests/ directory with XCTest target
• [ ] Add tests for ModelManagementView state management (model downloading, deletion, caching)
• [ ] Add tests for audio generation pipeline in ContentView (parameter validation, output verification)
• [ ] Add tests to verify ComputeUnitsView correctly switches between CPU/GPU/Neural Engine
• [ ] Integrate new test target into the Xcode project and add to unit-tests.yml workflow

Add end-to-end tests for ServeCLIClient examples across languages

The Examples/ServeCLIClient directory contains Python, Swift, and curl client implementations that test transcription and translation endpoints, but there's no unified CI workflow validating all three clients work correctly. The repo has separate development-tests.yml and release-tests.yml but neither runs the ServeCLIClient examples. This gap means breaking changes to the server API could ship undetected.

• [ ] Create Examples/ServeCLIClient/test-integration.yml GitHub Actions workflow
• [ ] Add Python test orchestration: validate test_transcribe.py and test_translate.py run successfully
• [ ] Add Swift client tests: build and run the CLI example against test audio files
• [ ] Add curl client validation: run transcribe.sh and translate.sh scripts with sample inputs
• [ ] Add workflow condition to run on release-tests.yml or manually on server API changes

Create platform-specific CI workflow for macOS and iOS simulator tests

The repo targets Apple Silicon with on-device Speech AI, but the existing workflows (unit-tests.yml, development-tests.yml, release-tests.yml) don't clearly specify which platforms are tested. With TTS and transcription examples for both iOS (TTSKitExample) and potential macOS usage, there should be explicit workflows validating both architectures. Currently missing: iOS simulator tests for the example apps and macOS-specific performance validation.

• [ ] Create .github/workflows/ios-simulator-tests.yml to test TTSKitExample on iOS simulators (iPhone, iPad)
• [ ] Add device matrix for multiple iOS versions (minimum supported + latest)
• [ ] Add build validation step for Apple Silicon (arm64) native compilation
• [ ] Create .github/workflows/macos-tests.yml for macOS-specific tests (if applicable to library)
• [ ] Document platform support matrix in CONTRIBUTING.md referencing the new workflows

• Add Python bindings for SpeakerKit: Examples/ServeCLIClient/Python/ has test_transcribe.py and test_translate.py for WhisperKit but no speaker diarization examples—create test_speaker_diarization.py following the existing pattern in whisperkit_client.py.
• Write unit tests for TTSKitExample AudioMetadata.swift: No test files visible for Examples/TTS/TTSKitExample/TTSKitExample/AudioMetadata.swift; add Tests/TTSKitExampleTests/AudioMetadataTests.swift covering metadata parsing and validation.
• Document model download caching behavior: Add section to README or CONTRIBUTING.md explaining where Core ML models are cached (likely ~/Library/Caches or .documents folder), how to clear cache, and expected first-run download times for each model (Whisper, Pyannote, Qwen-TTS).

The argmax-oss-swift repository demonstrates a generally secure structure with appropriate separation of concerns and use of package managers. However, there are several areas for improvement: (1) Shell scripts in examples lack visible input validation safeguards; (2) Dependency management could benefit from automated security scanning in CI/CD pipelines; (3) Xcode project files need review to prevent accidental secret exposure; (4) The repository would benefit from a formal security policy and vulnerability disclosure guidelines. The codebase appears to be a legitimate speech AI library without obvious hardcoded secrets or critical misconfigurations, but security automation and dependency auditing should be strengthened.

• Medium · Shell Scripts Without Input Validation — Examples/ServeCLIClient/Curl/*.sh. The repository contains shell scripts (test.sh, transcribe.sh, translate.sh) in Examples/ServeCLIClient/Curl that may execute user-provided input without proper validation. These scripts could be vulnerable to command injection attacks if they accept and pass unsanitized user input to shell commands. Fix: Review all shell scripts for proper input validation and sanitization. Use parameterized/quoted arguments when passing user input to commands. Consider adding input validation functions and using shellcheck for linting.
• Medium · Python Dependencies Management — Examples/ServeCLIClient/Python/uv.lock, Examples/ServeCLIClient/Python/pyproject.toml. The Python example client (Examples/ServeCLIClient/Python) uses a uv.lock file for dependency management. Without visibility into the specific dependencies and their versions, there's a risk of using outdated or vulnerable packages. The pyproject.toml configuration is not shown in detail. Fix: Regularly audit Python dependencies using tools like pip-audit or safety. Implement automated dependency scanning in CI/CD pipelines. Pin dependency versions with hash verification and update dependencies regularly.
• Low · Missing Security Configuration Files — Repository root. No evidence of security configuration files such as SECURITY.md, security policy in workflows, or vulnerability disclosure guidelines. This could delay security issue reporting and remediation. Fix: Create a SECURITY.md file with responsible disclosure guidelines. Implement automated security scanning in GitHub Actions workflows (SAST, dependency scanning, SBOM generation).
• Low · XCode Project Configuration Exposure — Examples/TTS/TTSKitExample/TTSKitExample.xcodeproj/project.pbxproj, Examples/TTS/TTSKitExample/Debug.xcconfig. Xcode project files (.pbxproj, .xcconfig) are checked into version control. These files may contain hardcoded build settings, API keys, or certificates if not properly configured. Fix: Audit Xcode project files to ensure no secrets are hardcoded in build configurations. Use environment variables and build phases to inject sensitive configuration. Consider using .gitignore to exclude files with local overrides containing secrets.
• Low · Incomplete Dependency Visibility — Examples/ServeCLIClient/Swift/Package.resolved, .swiftpm/configuration/Package.resolved. The Package.resolved and Package.swift files are mentioned but their content is not provided. Cannot fully assess Swift Package Manager dependencies for known vulnerabilities. Fix: Regularly audit Swift package dependencies using swift package resolve and check for security advisories. Implement dependency scanning in CI/CD. Review Package.resolved for any suspicious or unmaintained packages.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.