FluidAudio: Instructions file for Codex

FluidAudio - Agent Development Guide

Build & Test Commands

swift build                                    # Build project
swift build -c release                        # Release build
swift test                                     # Run all tests
swift test --filter CITests                   # Run single test class
swift test --filter CITests.testPackageImports # Run single test method
swift format --in-place --recursive --configuration .swift-format Sources/ Tests/

Architecture

• FluidAudio/: Main library (ASR/, Diarizer/, VAD/, Shared/ modules)
• FluidAudioCLI/: CLI tool with benchmarking and processing commands
• Tests/FluidAudioTests/: Comprehensive test suite
• Models: Auto-downloaded from HuggingFace with CoreML compilation
• Processing Pipeline: Audio → VAD → Diarization → ASR → Timestamped transcripts

Critical Rules

• NEVER use @unchecked Sendable - implement proper thread safety with actors/MainActor
• NEVER create dummy/mock models or synthetic audio data - use real models only
• NEVER create simplified versions - implement full solutions or consult first
• NEVER run git push unless explicitly requested by user
• Add unit tests when writing new code

Code Style (swift-format config)

• Line length: 120 chars, 4-space indentation
• Import order: Alphabetical preferred (import CoreML, import Foundation, import OSLog), but OrderedImports rule is disabled due to Swift 6.1 (GitHub Actions CI) vs 6.3 (local) formatter incompatibility
• Naming: lowerCamelCase for variables/functions, UpperCamelCase for types
• Error handling: Use proper Swift error handling, no force unwrapping in production
• Documentation: Triple-slash comments (///) for public APIs
• Thread safety: Use actors, @MainActor, or proper locking - never @unchecked Sendable
• Control flow: Prefer flattened if statements with early returns/continues over nested if statements. Use guard statements and inverted conditions to exit early. Nested if statements should be absolutely avoided.