Sales Coach

Copiloto de ventas en tiempo real para Windows, macOS y Ubuntu. Transcribe por separado lo que dice el vendedor (tu microfono) y lo que dice el cliente (el audio de la llamada), y aplica una metodologia de venta (MEDDPICC o GBS) para sugerir, en cada momento, UNA sola siguiente mejor pregunta.

Todo el procesamiento de audio ocurre en tu equipo: la transcripcion corre local con faster-whisper y las reglas de coaching tambien. El audio nunca sale de la maquina.

Estado: version de prueba 0.1.0. Funciona de punta a punta y esta verificada con llamadas reales, pero es la primera version empaquetada. Si algo falla, el detalle util esta en Troubleshooting.

Contenido

• Instalacion en Windows
• Instalacion en macOS
• Uso
• Metodologias disponibles
• Coach con IA (opcional)
• Privacidad y datos
• Como funciona por dentro
• Desarrollo
• Empaquetar el instalador
• Limitaciones conocidas
• Troubleshooting

Instalacion en Windows

La forma corta, sin instalar Python ni nada mas:

1. Descarga SalesCoach-0.1.0-win64-setup.exe de la ultima release.
2. Ejecutalo. Se instala solo para tu usuario, en %LOCALAPPDATA%\Programs\Sales Coach, sin pedir permisos de administrador.
3. Abrelo desde el menu inicio como "Sales Coach".

Requisitos: Windows 10 o 11 de 64 bits, un microfono y una salida de audio activa. Nada mas: el ejecutable trae Python, Qt y el motor de transcripcion adentro.

La primera vez que inicies una sesion, la app descarga el modelo de transcripcion elegido desde Hugging Face (base, el default, pesa unos 74 MB). Eso pasa una sola vez y necesita conexion; despues la transcripcion funciona sin internet.

Windows SmartScreen puede advertir que el instalador es de un editor desconocido, porque el ejecutable no esta firmado con un certificado de codigo. Es esperable en esta version de prueba: "Mas informacion", "Ejecutar de todas formas".

Para desinstalar: Configuracion, Aplicaciones, Sales Coach, Desinstalar. Tus sesiones guardadas no se borran, quedan en %LOCALAPPDATA%\Sales Coach.

Instalacion en macOS

No hay un .app publicado todavia: PyInstaller no cruza plataformas, asi que el paquete de macOS se arma en un Mac. Desde la raiz del proyecto:

./packaging/construir-macos.sh

Deja dist/SalesCoach-0.1.0-macos-<arquitectura>.zip listo para enviar.

Antes de usarlo hay un paso que no se puede saltar: macOS no tiene loopback, no existe forma de capturar lo que suena en una salida sin un dispositivo de audio virtual. Hay que instalar BlackHole y crear un dispositivo de salida multiple. El procedimiento completo, junto con los permisos de microfono y como abrir una app sin firmar, esta en docs/macOS.md.

En Ubuntu no hay instalador; se corre desde el codigo, ver Desarrollo.

Uso

1. Abre Sales Coach.
2. Selecciona tu microfono (canal SELLER) y la salida de audio donde escuchas la llamada (canal CLIENT). El combo "Audio de llamada" lista salidas, no microfonos: de ahi se captura lo que suena.
3. Elige el modelo Whisper (base es un buen punto de partida).
4. Pulsa "INICIAR COACH".
5. Abre tu videollamada (Meet, Teams, Zoom) y habla normalmente.
6. Observa la transcripcion, el estado de la metodologia, la siguiente pregunta sugerida, el talk ratio en vivo y la checklist de preguntas: va agregando cada pregunta que el coach te sugiere, en orden, y marca con una palomita las categorias que el cliente ya cubrio.
7. Activa "Modo compacto" y "Always on Top" para dejar la ventana al lado de la videollamada. La checklist sigue visible en modo compacto, justo para eso.
8. Pulsa "FINALIZAR SESION" para ver el resumen y guardarla.

Antes de una llamada real: verifica que los dos canales estan separados

Usa el boton "Verificar niveles de audio (debug)" de la pantalla inicial: habla por tu microfono, deberia moverse solo la barra SELLER; reproduce cualquier audio en la salida elegida, por ejemplo un video en el navegador, deberia moverse solo la barra CLIENT.

Como ensayo completo, pon un video hablado en la misma salida que usaras en la llamada e inicia una sesion: deberias ver segmentos SELLER y CLIENT apareciendo por separado en la transcripcion.

Metodologias disponibles

• MEDDPICC: metodologia B2B estandar (Metrics, Economic Buyer, Decision Criteria, Decision Process, Paper Process, Identify Pain, Champion, Competition).
• GBS (Goals, Barriers, Solutions): metodologia propia de GB Advisors, pensada para su rol de advisor e implementador tecnologico. Sus 9 categorias son Goal y Metrica de exito (Goals); Dolor, Barrera tecnica y Barrera organizacional (Barriers); y Encaje de solucion, Decisor, Competencia y Siguiente paso (Solutions). "Encaje de solucion" se detecta contra el portafolio de GB Advisors: ITSM/ITOM (ServiceNow, Freshservice, HaloITSM), CMDB (Device42), Customer Service (Freshdesk, HaloCRM), Work Management (monday.com), IT Operations (NinjaOne), CRM (Vtiger), Automatizacion (Make), Employee Experience (Humand) y Cybersecurity (BeyondTrust).

Se elige en el combo "Metodologia" de la pantalla inicial. Implementacion: methodologies/meddpicc.py y methodologies/gbs.py, ambas sobre la interfaz Methodology de methodologies/base.py; las reglas locales de sugerencia viven en coach/rules.py (MEDDPICC) y coach/gbs_rules.py (GBS).

Coach con IA (opcional, Claude CLI)

Si el comando claude esta instalado y autenticado, Sales Coach lo usa automaticamente como fuente adicional de sugerencias, ademas de las reglas locales, que siempre estan activas. La vista en vivo lo indica con "Coach IA: activo (Claude CLI)".

• Las llamadas tienen debounce, por defecto 8 segundos, configurable en sales_coach/config.py::COACH_DEBOUNCE_SECONDS: no se dispara una llamada por cada micro-fragmento del cliente.
• Cada llamada usa tu sesion de Claude Code ya autenticada, no una API key aparte: el consumo cuenta contra tus limites de uso normales.
• Se ejecuta con --restricted (sin herramientas de ejecucion de comandos) y --strict-mcp-config (sin conectarse a servidores MCP del sistema): el analisis es texto de la conversacion a texto de sugerencia, nunca puede ejecutar nada.
• Nunca bloquea la interfaz: corre en un hilo de fondo con timeout.

En Windows el CLI se busca en el PATH y tambien en las rutas de instalacion habituales (winget, npm, instalador nativo), porque un proceso que heredo un PATH anterior a la instalacion no lo encuentra de otra forma.

Modo sin Claude

Si claude no esta instalado, no esta autenticado o falla, Sales Coach sigue funcionando con transcripcion, metodologia y reglas locales, sin interrumpirse. El indicador muestra "Coach IA: desconectado (usando solo reglas locales)".

Privacidad y datos

• No se guarda el audio de la llamada. Se procesa en memoria por fragmentos y se descarta apenas se transcribe.
• La transcripcion, el estado de la metodologia y las preguntas sugeridas se guardan en SQLite, en %LOCALAPPDATA%\Sales Coach\data\sales_coach.db si usaste el instalador, o en data/sales_coach.db dentro del proyecto si corres desde el codigo. Nunca salen de tu equipo.
• El audio nunca se envia a Claude. Cuando el coach IA esta activo solo viaja texto: la transcripcion reciente y el estado de la metodologia.
• Grabar una llamada, aunque sea para transcribirla localmente, puede requerir avisar a la otra parte segun la jurisdiccion y la politica de tu empresa. La herramienta no pide ese consentimiento por ti.

Como funciona por dentro

Separacion SELLER / CLIENT

No hay diarizacion: no se intenta adivinar quien habla por la voz. Se usa el origen fisico del audio, que es exacto por construccion.

• SELLER se captura de tu microfono.
• CLIENT se captura de la salida de audio que elijas, donde escuchas la videollamada.

Capturar "lo que suena en una salida" se resuelve distinto en cada sistema, y esa es la unica parte que cambia entre plataformas:

	Windows	macOS	Ubuntu
Enumeracion	WASAPI via PyAudioWPatch	CoreAudio via sounddevice	pw-dump + wpctl
Captura	Stream WASAPI en modo callback	Stream CoreAudio en modo callback	pw-record por canal
Audio del cliente	Dispositivo de loopback que Windows expone por cada salida	No hay loopback: un dispositivo virtual (BlackHole) al que se enruta la llamada	El sink elegido: pw-record --target <sink> entrega su monitor
Formato	48 kHz estereo nativo, se mezcla a mono y se remuestrea a 16 kHz	Igual que Windows, mismo audio/resample.py	Se pide 16 kHz mono directo

macOS es el unico de los tres donde el usuario tiene que instalar algo aparte, y no es un capricho del proyecto: Apple no deja que una app grabe la salida de otra sin una extension de driver. Ver docs/macOS.md.

Los tres backends implementan el mismo contrato (audio/base.py) y entregan audio identico hacia arriba: mono s16le a 16 kHz, en trozos de 100 ms. El resto de la aplicacion no sabe en que sistema corre.

Regla critica de diseño

Lo que dice el SELLER nunca se usa como evidencia de un hecho del cliente. El estado de la metodologia solo se actualiza con segmentos etiquetados CLIENT. Esta forzado en methodologies/meddpicc.py::Meddpicc.update() y en methodologies/gbs.py::Gbs.update(), y cubierto por tests en ambos casos.

Estructura

sales-coach/
├── main.py                        Punto de entrada (arranca la GUI)
├── sales_coach/
│   ├── config.py                  Rutas, defaults, logging
│   ├── audio/
│   │   ├── base.py                Contratos comunes (AudioDevice, ChannelCapture)
│   │   ├── wasapi.py              Backend Windows: WASAPI + loopback de la salida
│   │   ├── coreaudio.py           Backend macOS: CoreAudio + dispositivo virtual
│   │   ├── pipewire.py            Backend Linux: pw-dump/wpctl + pw-record
│   │   ├── resample.py            Mezcla a mono y remuestreo (Windows y macOS)
│   │   ├── devices.py             Enumeracion de dispositivos (elige backend)
│   │   ├── audio_manager.py       Captura de los dos canales (elige backend)
│   │   ├── seller_capture.py      Wrapper: canal SELLER (microfono)
│   │   └── client_capture.py      Wrapper: canal CLIENT (salida de la llamada)
│   ├── transcription/
│   │   ├── whisper_engine.py      Wrapper de faster-whisper
│   │   ├── transcript_buffer.py   Buffering + deteccion de silencio
│   │   └── live_transcriber.py    audio -> buffer -> Whisper -> TranscriptSegment
│   ├── conversation/
│   │   ├── models.py              Speaker, TranscriptSegment
│   │   └── session.py             SalesSession (transcripcion, talk ratio, etc.)
│   ├── methodologies/
│   │   ├── base.py                Interfaz Methodology + CategoryState/Status
│   │   ├── meddpicc.py            Implementacion de MEDDPICC
│   │   ├── gbs.py                 Implementacion de GBS
│   │   └── registry.py            Registro central de metodologias
│   ├── coach/
│   │   ├── rules.py               Reglas locales de MEDDPICC
│   │   ├── gbs_rules.py           Reglas locales de GBS
│   │   ├── engine.py              Una sola pregunta + IA opcional con debounce
│   │   ├── claude_provider.py     CoachProvider (interfaz) + ClaudeCLIProvider
│   │   ├── continuity.py          Continuidad entre reuniones del mismo cliente
│   │   ├── scoring.py             Puntaje de la sesion
│   │   └── transcript_parser.py   Parser de transcripciones pegadas
│   ├── storage/
│   │   └── database.py            Persistencia SQLite de SalesSession
│   ├── ui/
│   │   ├── main_window.py         Pantalla inicial (seleccion de audio/modelo)
│   │   ├── live_view.py           Vista en vivo (transcripcion + estado + coach)
│   │   ├── debug_levels.py        Debug de niveles SELLER/CLIENT
│   │   ├── session_history.py     Historial de reuniones guardadas
│   │   ├── session_summary.py     Resumen al finalizar la sesion
│   │   ├── transcript_analyzer.py Analisis de una transcripcion pegada
│   │   └── theme.py               Identidad visual (QSS + fuente Inter)
│   └── assets/                    Icono, logo y fuentes Inter
├── packaging/                     Recetas del ejecutable y del instalador
├── tests/
└── docs/

Identidad visual

La interfaz usa la paleta de marca de GB Advisors: magenta #EA018B como color primario, tinta #12112C como texto, tipografia Inter, botones tipo pildora y tarjetas redondeadas. Todo vive en sales_coach/ui/theme.py, una sola hoja de estilos Qt, para poder ajustarlo sin tocar cada ventana.

Desarrollo

Requisitos en Windows (10 u 11): Python 3.11 o superior. La captura usa WASAPI, que es parte del sistema; el paquete PyAudioWPatch expone los dispositivos de loopback y se instala con las dependencias.

Requisitos en macOS (11 o superior): Python 3.11 o superior y las Command Line Tools de Xcode. La captura usa CoreAudio via sounddevice, que se instala con las dependencias, mas un dispositivo de audio virtual para el canal del cliente (ver docs/macOS.md).

Requisitos en Ubuntu (presentes en 26.04 con PipeWire activo): pw-record, pw-cat, pw-dump, wpctl. Verificalos con wpctl status.

Entorno y dependencias, en Windows:

git clone https://github.com/irqv85/sales-coach.git
cd sales-coach
python -m venv .venv
.venv\Scripts\python -m pip install -e ".[dev]"

o en macOS y Ubuntu:

git clone https://github.com/irqv85/sales-coach.git
cd sales-coach
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Ejecucion. En Windows, doble clic en Sales Coach.bat (sin consola) o .\run.bat desde una terminal si quieres ver las trazas. En macOS y Ubuntu, ./run.sh. Dentro del .venv, en cualquiera de los tres, python main.py.

Para crear un acceso directo en el escritorio apuntando al codigo, en vez de instalar la app: powershell -ExecutionPolicy Bypass -File .\Instalar-AccesoDirecto.ps1 en Windows, ./install_launcher.sh en Ubuntu.

Tests:

pytest

Son 94 casos y corren en cualquiera de los tres sistemas: mockean subprocess, PipeWire, WASAPI, CoreAudio, Whisper y el CLI de Claude, asi que no necesitan audio real ni conexion. Los tests de los backends de Windows y macOS tambien pasan en Linux, y al reves: cada backend importa su biblioteca nativa de forma perezosa justo para eso.

Empaquetar el instalador

PyInstaller no cruza plataformas: cada sistema se empaqueta en una maquina de ese sistema. En macOS todo el proceso esta en un solo script, ./packaging/construir-macos.sh, documentado en docs/macOS.md. Lo que sigue es Windows.

Hacen falta PyInstaller e Inno Setup 6:

.venv\Scripts\python -m pip install -e ".[packaging]"
winget install JRSoftware.InnoSetup

El instalador se arma en dos pasos, ambos desde la raiz del proyecto y en Windows:

.venv\Scripts\pyinstaller packaging\SalesCoach.spec --noconfirm
& "$env:LOCALAPPDATA\Programs\Inno Setup 6\ISCC.exe" packaging\installer.iss

El primero deja el ejecutable y sus dependencias en dist\Sales Coach\ (unos 350 MB: Qt, ctranslate2, onnxruntime y PyAV pesan). El segundo comprime esa carpeta en dist\installer\SalesCoach-<version>-win64-setup.exe (unos 94 MB) con desinstalador y accesos directos.

Se empaqueta en modo carpeta y no en un solo archivo a proposito: un --onefile de ese tamaño tendria que descomprimirse en %TEMP% en cada arranque, sumando medio minuto antes de que aparezca la ventana.

Para comprobar que el bundle quedo completo, packaging/smoke_test.py se compila igual pero en modo consola y verifica lo que la interfaz no puede contestar sola: que carguen las DLLs de ctranslate2, onnxruntime y PortAudio dentro del ejecutable.

.venv\Scripts\pyinstaller packaging\smoke_test.spec --noconfirm
.\dist\smoke_test\smoke_test.exe

Limitaciones conocidas

• Fuga acustica entre canales: si usas microfono y altavoces cercanos, o un headset con el microfono pegado al auricular, tu microfono capta lo que dice el cliente y ese audio queda etiquetado como SELLER, porque el etiquetado es por canal de captura, no por contenido. No rompe la regla critica (SELLER nunca es evidencia de un hecho del cliente), pero duplica contenido en la transcripcion. Mitigacion: audifonos con el microfono alejado del auricular, o menos volumen si usas altavoces.
• La extraccion por reglas locales usa palabras clave y regex, no comprension semantica. El coach con Claude complementa eso, pero el modo local por si solo puede pasar por alto formulaciones no anticipadas.
• La precision de Whisper no es forense: prioriza baja latencia y uso razonable de CPU. Sirve para coaching comercial, no para actas legales. Si necesitas mas precision, sube el modelo de base a small en el selector de la pantalla inicial.
• Si una llamada al coach IA falla o hace timeout, el indicador muestra "Coach IA: sin respuesta, reintentando automaticamente" y el siguiente segmento del cliente vuelve a intentarlo solo. Las reglas locales siguen trabajando mientras tanto.
• No hay deduplicacion de eco todavia. La arquitectura esta preparada para agregarla sin romper la separacion de canales.
• El ejecutable no esta firmado, asi que SmartScreen advierte en la primera ejecucion.

Troubleshooting en Windows

• "Windows no expone ningun dispositivo de loopback": no hay una salida de audio activa. Conecta o habilita audifonos o altavoces en Configuracion, Sistema, Sonido, y vuelve a abrir Sales Coach: los combos se llenan al arrancar.
• No se oye al cliente en la transcripcion: el canal CLIENT captura la salida que elegiste, no lo que sea que suene. Si la videollamada esta reproduciendo en otro dispositivo, elige ese mismo en "Audio de llamada" o cambia la salida de la app de videollamada.
• El microfono no aparece: Windows bloquea el acceso por aplicacion en Configuracion, Privacidad y seguridad, Microfono. Debe estar permitido para aplicaciones de escritorio.
• "Falta el paquete PyAudioWPatch": solo pasa corriendo desde el codigo, con el .venv incompleto. Corre .venv\Scripts\python -m pip install -r requirements.txt.

Troubleshooting en Ubuntu (PipeWire)

• wpctl status no muestra tu microfono o tu salida: revisa que el dispositivo este conectado y no silenciado (wpctl set-mute <id> 0).
• pw-record o pw-cat no encontrados: instala pipewire-bin o el equivalente de tu distribucion.
• No se detectan dispositivos: corre pw-dump | head para confirmar que PipeWire responde; si falla, reinicia el servicio con systemctl --user restart pipewire pipewire-pulse wireplumber.
• pactl no existe: es normal en Ubuntu 26.04 y esta app no lo necesita.

Licencia

Codigo y marca de GB Advisors, Inc. Todos los derechos reservados. Este repositorio es publico para consulta y para distribuir el instalador; no se otorga licencia de uso, copia o redistribucion del codigo.

La tipografia Inter incluida en sales_coach/assets/fonts/ es de Rasmus Andersson y se distribuye bajo SIL Open Font License 1.1.