Q1 Documentacion

Documentacion tecnica completa para Q1, el subsistema de overlay de escritorio con IA.

Inicio rapido

Q1 es un overlay de escritorio impulsado por IA que se integra directamente en tu flujo de trabajo. Funciona como una capa transparente siempre disponible, con memoria persistente, busqueda semantica, comandos de voz y soporte multi-proveedor de modelos de lenguaje. Instalalo y empeza a usarlo en menos de un minuto.

bash

curl -fsSL https://q1.dev/install.sh | bash
q1 setup          # Configuracion interactiva
q1 config --key ANTHROPIC_API_KEY=sk-...
q1 start           # Lanzar el overlay
q1 status          # Verificar que todo funcione

Nota

Despues del primer inicio, Q1 te guiara por una configuracion de personalidad (SOUL.md) para adaptar su comportamiento a tus preferencias.

Requisitos del sistema

Componente	Minimo	Recomendado
Sistema operativo	Windows 10, Ubuntu 22.04, macOS 12	Windows 11, Ubuntu 24.04, macOS 14
RAM	8 GB	16 GB (para LLM local)
Almacenamiento	2 GB	2 GB + espacio para modelos
Python	3.11+	3.12+
GPU	No requerida	NVIDIA (CUDA) para inferencia local

Instalacion (Linux)

Descargar e instalar

El script de instalacion detecta tu distribucion, instala las dependencias necesarias y configura Q1 en ~/.q1.

bash

curl -fsSL https://q1.dev/install.sh | bash

Configuracion inicial

Ejecuta el asistente de setup para configurar tus API keys y preferencias.

bash

q1 setup

Iniciar Q1

bash

q1 start

Dependencias

En distribuciones basadas en Debian/Ubuntu, el instalador configura automaticamente libayatana-appindicator3 y libnotify para la integracion con el system tray.

Instalacion (Windows)

Descargar e instalar

Abri PowerShell como administrador y ejecuta:

powershell

irm https://q1.dev/install.ps1 | iex

Configurar e iniciar

powershell

q1 setup
q1 start

Importante

Windows Defender puede solicitar permisos la primera vez. Q1 necesita acceso a la red para comunicarse con los proveedores de LLM y al overlay de pantalla para la interfaz transparente.

Instalacion (macOS)

Instalar con Homebrew

bash

brew tap q1-dev/tap
brew install q1

Configurar e iniciar

bash

q1 setup
q1 start

Nota

En macOS, se necesitan permisos de Accesibilidad y Grabacion de Pantalla en Preferencias del Sistema para que el overlay funcione correctamente.

Configuracion

Toda la configuracion de Q1 se almacena en ~/.q1/config.yaml. Este archivo se crea automaticamente durante q1 setup, pero se puede editar manualmente.

yaml

# ~/.q1/config.yaml

# --- Proveedor principal ---
provider: anthropic          # anthropic | openai | google | openrouter | ollama
model: claude-sonnet-4-20250514

# --- API Keys ---
keys:
  anthropic: sk-ant-...
  openai: sk-...
  google: AIza...
  openrouter: sk-or-...
  elevenlabs: xi-...

# --- Modelo local (opcional) ---
local:
  enabled: false
  provider: ollama
  model: llama3.1:8b
  endpoint: http://localhost:11434

# --- Voz ---
voice:
  enabled: true
  stt_provider: elevenlabs     # elevenlabs | whisper | google
  tts_provider: elevenlabs
  tts_voice: Pau
  tts_stability: 0.85
  tts_style: 0.3
  activation: "hey q1"         # Frase de activacion

# --- Memoria ---
memory:
  api_port: 7777
  auto_embed: true
  embedding_model: gemini-embedding-001
  max_context_memories: 10

# --- Overlay ---
overlay:
  opacity: 0.92
  position: bottom-right       # top-left | top-right | bottom-left | bottom-right
  width: 420
  theme: dark
  hotkey: "Ctrl+Shift+Q"       # Atajo para mostrar/ocultar

Configurar API keys

Se pueden configurar las keys individualmente desde la terminal:

bash

q1 config --key ANTHROPIC_API_KEY=sk-ant-...
q1 config --key OPENAI_API_KEY=sk-...
q1 config --key GEMINI_API_KEY=AIza...
q1 config --key OPENROUTER_API_KEY=sk-or-...
q1 config --key ELEVENLABS_API_KEY=xi-...

Seleccion de modelo

Q1 soporta multiples proveedores en simultaneo. El router de LLM selecciona el mejor modelo segun la tarea, o podes forzar uno especifico:

bash

# Usar un modelo especifico para la sesion
q1 start --model claude-sonnet-4-20250514

# Usar modelo local
q1 start --model ollama:llama3.1:8b

# Listar modelos disponibles
q1 models list

SOUL.md -- Personalidad

El archivo ~/.q1/SOUL.md define la personalidad, el tono y el comportamiento de Q1. Es un documento Markdown que el sistema carga al inicio de cada sesion como contexto base. Esto permite que Q1 se adapte completamente a tu estilo.

Como funciona

Al ejecutar q1 setup por primera vez, Q1 te hace una serie de preguntas para construir tu SOUL.md:

Como queres que te hable? (formal, informal, tecnico)
En que idioma preferis interactuar?
Que nombre queres darle al asistente?
Cuales son tus areas de trabajo principales?
Hay algo que quieras que siempre tenga en cuenta?

Ejemplo de SOUL.md

markdown

# SOUL.md — Personalidad de Q1

## Identidad
- Nombre: Friday
- Idioma principal: Espanol rioplatense
- Tono: Informal, directo, tecnico cuando corresponde

## Comportamiento
- Respuestas concisas, sin rodeos
- Usar "vos" en lugar de "tu"
- No usar emojis excepto si el usuario lo pide
- Ante dudas, preguntar antes de asumir

## Contexto del usuario
- Area: Desarrollo de software, IA, DevOps
- Horario habitual: 9:00 a 1:00 (UTC-3)
- Preferencia: Codigo antes que explicaciones largas

## Directivas permanentes
- Siempre priorizar la privacidad del usuario
- No enviar datos a servicios externos sin confirmacion
- Mantener logs locales de todas las interacciones

MEMORY.md -- Recuerdos

Q1 tiene un sistema de memoria persistente que almacena informacion relevante entre sesiones. El archivo ~/.q1/MEMORY.md actua como indice legible de las memorias almacenadas en la base de datos.

Estructura

Las memorias se organizan por tipo:

Tipo	Proposito	Ejemplo
`user`	Datos y preferencias del usuario	Horarios, contactos, intereses
`project`	Informacion sobre proyectos activos	Stack de un proyecto, decisiones de diseno
`feedback`	Correcciones y preferencias del usuario	"Prefiero respuestas cortas"
`reference`	Informacion general de referencia	Documentacion, comandos utiles

Auto-gestion

Q1 gestiona las memorias automaticamente durante las conversaciones. Cuando detecta informacion relevante (una preferencia, una correccion, datos de un proyecto), la almacena sin intervencion del usuario. Tambien se pueden gestionar manualmente:

bash

# Listar todas las memorias
q1 memory list

# Buscar memorias por tema
q1 memory search "deploy process"

# Agregar una memoria manual
q1 memory add --type project --name "api-v2" --content "Usando FastAPI + SQLAlchemy"

# Eliminar una memoria
q1 memory delete <id>

Sistema RAG

Q1 implementa Retrieval-Augmented Generation para enriquecer las respuestas con contexto relevante de tus conversaciones, archivos y memorias anteriores.

Componentes

Vector DB: SQLite con extension de vectores, almacena embeddings localmente
Modelo de embeddings: Gemini Embedding 001 (768 dimensiones)
Busqueda semantica: Similitud coseno sobre los embeddings almacenados
Busqueda hibrida: Combina busqueda semantica con FTS5 (full-text search) para mejores resultados
Auto-embedding: Las conversaciones se embeben automaticamente al finalizar cada sesion

Flujo de consulta

text

Mensaje del usuario
      |
      v
[Generar embedding] ──> Gemini Embedding 001
      |
      v
[Busqueda hibrida] ──> SQLite Vec + FTS5
      |
      v
[Top-K resultados] ──> Reranking por relevancia
      |
      v
[Inyectar contexto] ──> Prompt enriquecido ──> LLM

Configuracion del RAG

yaml

# En ~/.q1/config.yaml
rag:
  enabled: true
  top_k: 5                     # Cantidad de resultados a recuperar
  min_similarity: 0.72         # Umbral minimo de similitud
  hybrid_weight: 0.7           # Peso semantico vs texto (0.0 = solo texto, 1.0 = solo semantico)
  auto_index_conversations: true
  auto_index_files: false      # Indexar archivos del directorio de trabajo

APIs y Providers

Q1 soporta multiples proveedores de modelos de lenguaje y servicios auxiliares. El LLM Router distribuye las solicitudes segun la configuracion y disponibilidad.

Provider	Modelos destacados	Uso	Variable
Anthropic	Claude Opus 4, Claude Sonnet 4	Chat principal, razonamiento	`ANTHROPIC_API_KEY`
OpenAI	GPT-4o, o1, o3	Chat, analisis	`OPENAI_API_KEY`
Google	Gemini 2.5 Pro/Flash	Chat, embeddings	`GEMINI_API_KEY`
OpenRouter	349+ modelos	Fallback, modelos alternativos	`OPENROUTER_API_KEY`
ElevenLabs	Turbo v2.5	TTS, STT, efectos de sonido	`ELEVENLABS_API_KEY`
Ollama	Llama 3.1, Mistral, Phi-3	Inferencia local, sin costo	N/A (local)

Comandos de voz

Q1 soporta interaccion por voz bidireccional: reconocimiento de voz (STT) para recibir comandos y sintesis de voz (TTS) para responder.

Como funciona

Activacion: Decir la frase configurada (por defecto: "hey q1") activa el modo escucha
STT: El audio se envia a ElevenLabs (o Whisper) para transcripcion
Procesamiento: El texto transcripto se procesa como cualquier otro mensaje
TTS: La respuesta se sintetiza con ElevenLabs y se reproduce por los parlantes

Configuracion de voz

yaml

voice:
  enabled: true
  stt_provider: elevenlabs
  tts_provider: elevenlabs
  tts_voice: Pau               # Voz a usar (ver catalogo de ElevenLabs)
  tts_stability: 0.85          # Estabilidad (0.0 - 1.0)
  tts_similarity: 0.75         # Similitud con voz original
  tts_style: 0.3               # Expresividad (0.0 - 1.0)
  activation: "hey q1"
  silence_timeout: 2000        # ms de silencio antes de cortar grabacion
  audio_device: default        # Dispositivo de audio (default = sistema)

Comandos integrados

Comando	Accion
`"hey q1"`	Activar modo escucha
`"para" / "stop"`	Detener la reproduccion de voz actual
`"silencio" / "mute"`	Desactivar respuestas de voz temporalmente
`"lee esto"`	Leer en voz alta el contenido de pantalla seleccionado
`"dictar"`	Modo dictado: transcribir continuamente a texto

Arquitectura

Q1 usa una arquitectura modular donde cada componente se comunica mediante APIs internas. El shell grafico es intercambiable (Electron o Neutralino) y el core funciona independientemente como servicio.

Referencia API

La Memory API se expone en http://127.0.0.1:7777 y gestiona memorias, entidades y conversaciones. Todos los endpoints aceptan y devuelven JSON.

Health y estado

Metodo	Endpoint	Descripcion
`GET`	`/health`	Verificar estado del servicio

Memorias

Metodo	Endpoint	Descripcion	Parametros
`GET`	`/memory/list`	Listar todas las memorias	--
`POST`	`/memory`	Crear una memoria	`name, type, content, description`
`GET`	`/memory/recall`	Recuperar memorias por tema	`?topic=...`
`GET`	`/memory/search`	Buscar memorias por texto	`?q=...`
`DELETE`	`/memory/:id`	Eliminar una memoria	`:id`

Entidades

Metodo	Endpoint	Descripcion	Parametros
`POST`	`/entity`	Crear una entidad	`name, type, details`
`GET`	`/entity/search`	Buscar entidades	`?q=...`

Conversaciones

Metodo	Endpoint	Descripcion	Parametros
`POST`	`/conversation/log`	Registrar un mensaje	`role, content, channel`

Ejemplo de uso

bash

# Crear una memoria
curl -s -X POST http://127.0.0.1:7777/memory \
  -H "Content-Type: application/json" \
  -d '{"name":"deploy-flow","type":"project","content":"Deploy via GitHub Actions + Railway","description":"Proceso de deploy del proyecto principal"}'

# Buscar memorias
curl -s 'http://127.0.0.1:7777/memory/recall?topic=deploy'

# Registrar conversacion
curl -s -X POST http://127.0.0.1:7777/conversation/log \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg role "user" --arg content "como hago el deploy?" --arg channel "terminal" \
  '{role: $role, content: $content, channel: $channel}')"

Solucion de problemas

Q1 no inicia

Verificar que Python 3.11+ esta instalado y en el PATH:

bash

python3 --version
q1 doctor          # Diagnostico completo

Error de API key

Si ves errores de autenticacion, verificar que las keys esten configuradas:

bash

q1 config --list   # Ver configuracion actual
q1 config --key ANTHROPIC_API_KEY=sk-ant-...

Overlay no se muestra

En Linux, verificar que el compositor soporta transparencia. En macOS, asegurar que los permisos de Accesibilidad estan habilitados. En Windows, verificar que la aceleracion de hardware esta activa.

bash

# Linux: verificar compositor
echo $XDG_SESSION_TYPE    # Deberia ser wayland o x11

# Reiniciar el overlay
q1 restart --overlay

Memory API no responde

Verificar que el servicio de memoria esta corriendo en el puerto 7777:

bash

curl -s http://127.0.0.1:7777/health
q1 service restart memory

Voz no funciona

Verificar que ElevenLabs API key esta configurada y que el microfono tiene permisos:

bash

# Verificar key
q1 config --list | grep elevenlabs

# Test de microfono
q1 voice test

# Ver logs de voz
q1 logs --filter voice

Ver logs completos

Para diagnosticar cualquier problema, los logs detallados estan disponibles:

bash

q1 logs                    # Ultimas 50 lineas
q1 logs --follow           # Tiempo real
q1 logs --filter memory    # Filtrar por componente
q1 logs --level error      # Solo errores