Hoodini es el nombre de la app. Equipo: (nombre por definir) · Track: Physical World · Descargar el APK. Antes se llamaba «Capo AR»: el repositorio, el paquete Android (
com.capoar.app), el slug, el esquemacapoary los módulos conservan ese nombre técnico; los textos que ve el usuario dicen «Hoodini».
Documento de contexto para el equipo y para sus agentes de IA. Léelo completo antes de tocar código. Estado (21-11-2026): MVP inicial (hackathon). El resumen para el mentor está en
docs/brief.md. Qué falta y quién toma qué: el plan por fases está endocs/plan.md.
- App (
app/, Expo + React Native + expo-router): menú principal, aviso obligatorio y selección de vehículo (8 modelos).- Escáner: en el teléfono detecta el contorno del vano del motor, con sus esquinas y un modo debug (CLIPSeg con decodificador propio). Ver
herramientas/vano-motor/. El contorno queda anclado al auto con ARCore: se reconoce una vez y queda fijo al mover el teléfono, con un botón Recalibrar.- Piezas en AR: sobre el vano anclado se proyectan las piezas del auto elegido (
app/src/engine-maps/). Falta calibrarlas en el auto real (#17).- Chat «Preguntar al manual» (
api/+ pantallaask): responde con citas a partir de la tabla de fusibles y de las fichas de las piezas del vano, y abre la cámara en la pieza que toca revisar. Ver la sección «Chat».- PWA (
web/): usa el detector anterior (CLIP ViT-B/32,herramientas/detector-capo/).Compilar el APK (en el servidor del equipo):
scripts/compilar-apk.sh→dist/capo-ar.apk(la primera vez arma el modelo del vano: ~1 GB de entorno Python en~/.cachey ~600 MB de pesos). Requisitos y protecciones de memoria, en el propio script. Subeversionyandroid.versionCodeenapp/app.jsonantes de cada APK nuevo.
The installable PWA ports the menu and open-hood detector from native revision
317e8367. Select Escanear capó, enable the camera and aim at an open
engine bay. Frames stay on the device. A module worker runs the pinned
quantized CLIP image encoder with ONNX Runtime Web, using the native prompt
vectors, smoothing and thresholds. At build time, the patch-convolution weights
and zero point both shift by 128 to use the unsigned WASM kernel while
preserving each centered weight. The score indicates an open hood. Individual
part identification and AR anchoring are future features.
From a checkout containing the root docker-compose.yml, start the PWA on the
existing home proxy network with one command:
docker compose upCompose builds the image on first use. The build installs its own dependencies
and packages the model and the web runtime. Traefik routes requests for
ph26.berguecio.cl to port 8080 in the container.
For a local preview without Traefik:
docker build -t capo-ar .
docker run --rm -p 127.0.0.1:8080:8080 capo-arOpen http://localhost:8080. Phones require HTTPS for camera access.
The first visit downloads the app, model (about 89 MB) and WASM runtime.
Once the service worker finishes caching, scanning works offline. The image
also serves the map viewer if its files are present in the checkout.
This project uses the same hackathon repository for the PWA and its Compose
configuration. Pull requests and pushes to main verify the image on
GitHub-hosted runners. Compose carries this repository's numeric ID and uses
CAPO_AR_DOMAIN for the hostname. The default is ph26.berguecio.cl.
The starter's private-runner release jobs stay disabled in this public
repository. Production runner eligibility and the initial installation are
deferred to issue #2.
Una app Android que, al apuntar la cámara al capó (o al tablero) de tu auto, muestra en Realidad Aumentada dónde están y cómo se revisan las cosas básicas (caja de fusibles, depósito del limpiaparabrisas, varilla del aceite, refrigerante, filtro de aire, ampolletas) y responde en lenguaje natural «¿cómo cambio este fusible?», siempre citando el manual del auto.
Es una guía, no un mecánico. Ver sección 9 (aviso obligatorio).
- Tema elegido: Physical World — tomar inputs del mundo real (aquí: la cámara del teléfono apuntando a un auto real) y crear algo útil con ellos.
- Existe también un track de Hardware. La idea actual es 100 % software; no bloquea una extensión de hardware más adelante (p. ej. una sonda de fusibles con ESP32), pero no es parte del MVP.
Mucha gente no se atreve a hacer revisiones básicas de su auto, o ni siquiera sabe dónde están las cosas. Datos encontrados (encuestas mayormente de Reino Unido, de aseguradoras/empresas de asistencia, autodeclaradas; úsalas como indicio, no como verdad absoluta):
- 63 % no sabía revisar el nivel de aceite; 1 de cada 5 no identificaba la varilla; 29 % no sabía rellenar el depósito del limpiaparabrisas — Fleet News, Shropshire Star.
- 6 de cada 10 no podían cambiar una ampolleta de faro — PR Newswire.
- Razones para no hacerlo: miedo a dañar algo (≈29 %) y no saber cómo (≈22 %) — Motor1. Por eso la guía paso a paso con AR ataca el miedo a equivocarse.
Dolor concreto de partida: «No puedo prender una luz de mi auto» → ¿ampolleta o fusible? ¿dónde está? ¿cuál compro? ¿cómo la cambio?
- Ya existen apps de IA que identifican piezas con la cámara (PartsIQ, Part Identifier Plus, ScanPart, CarSight — listados de App Store, sin reseñas independientes que hayamos visto).
- Las guías AR de fabricantes (Hyundai/Genesis Virtual Guide, Ask Mercedes, Ford) son por marca y modelos concretos, con poco contenido AR.
- Nuestro diferencial: (1) la información anclada en AR sobre tu propio auto, no solo texto; (2) guía por modelo y año; (3) toda respuesta con fuente citada del manual.
- No encontramos una app multimarca que haga exactamente esto, pero no está demostrado que no exista. No lo afirmen en la presentación como hecho.
Usuario objetivo: conductor básico. (Mecánicos = futuro, ver sección 10.)
| # | Feature | Qué debe hacer |
|---|---|---|
| F1 | Mapa 3D simple de elementos del capó | Modelos 3D sencillos (cajas, cilindros, flechas) de: caja de fusibles, depósito limpiaparabrisas («el sapito» en Chile), varilla del aceite, depósito de refrigerante, caja del filtro de aire. Ubicados según fotos y diagramas del manual. No es un modelo CAD del auto completo. |
| F2 | AR sobre el capó real | Al apuntar la cámara, esos elementos aparecen superpuestos en su sitio, con etiqueta. |
| F3 | Pregunta en lenguaje natural | «¿Cómo cambio un fusible?» → respuesta paso a paso con cita (manual, sección, página) y la AR resalta la pieza relevante. |
| F4 | Luces del tablero | Apuntar al tablero con una luz encendida → nombre del indicador + qué significa + qué hacer, según el manual del auto. |
| F5 | Ampolleta | «Se quemó una luz» → qué ampolleta lleva (según manual) y cómo cambiarla. |
Fuera del MVP: modo mecánico, más de 2 autos, tienda/compra de repuestos, OBD2, iOS, hardware, cualquier dato con licencia de pago.
- Auto de pruebas físico (obligatorio): Subaru Outback 2016, motor 3.6 (EZ36, versión «3.6R»). Es el único auto al que el equipo tiene acceso físico hoy. Todo lo de AR se prueba aquí.
- Segundo auto (pendiente de decidir): la idea original era un auto «muy genérico» con información pública abundante, p. ej. Toyota Corolla. Sin acceso físico a un Corolla, solo podríamos cubrir la parte de datos/manual/chat (F3, F4, F5), no la parte de AR. Decisión abierta: conseguir acceso a un segundo auto (de un integrante o conocido) o dejar el MVP con un auto y mostrar el segundo solo en la capa de datos.
- Hoy: la app trae mapas de 8 modelos (
app/src/vehicles.ts), trazados sobre fotos de referencia. Solo el Outback se puede probar en un auto real.
| Auto | Fuente | Notas / cautelas |
|---|---|---|
| Subaru Outback 2016 | Copias del manual de dueño: ManualMachine, Scribd, ManualsFile (3.6R Limited, 566 págs.) | Son copias de terceros; no encontramos el PDF oficial de Subaru. Contrastar contra el manual físico de la guantera del auto. |
| Subaru Outback 2016 | Diagrama de fusibles: autogenius.info | Tercero. No se confirmó si el 3.6R usa el mismo layout que el 2.5i. Verificar contra el auto real. |
| Toyota Corolla | Manuales oficiales en PDF: toyota.ca, assets.sia.toyota.com | Cada manual trae «Indicators and warning lights». Hay que fijar el año exacto (cambia de generación). |
| Cualquiera | Decodificar VIN → marca/modelo/año: NHTSA vPIC | Gratis; no trae fusibles ni piezas. |
| Cualquiera | Diagramas de fusibles por modelo vía API de terceros (parse.bot / StartMyCar) | Revisar términos, precio y cobertura antes de depender de ella. |
Datos que NO tenemos y no debemos inventar: modelos 3D/CAD del fabricante, datos de taller (ALLDATA, Mitchell, HaynesPro — de pago), y tabla pública de ampolletas por API (Sylvania/Philips/Bulbs.com tienen buscadores web pero sin API pública; raspar sus datos probablemente viola sus términos). Para las ampolletas del MVP: leerlas del manual del auto y/o armar la tabla a mano para el Outback.
Decidido: la plataforma (Android), la AR (ARCore nativo) y el asistente (
api/). Lo demás sigue siendo propuesta.
- Plataforma: Android (decidido; más fácil generar APK y todo el equipo usa Android).
- Capa de datos (offline, preprocesada): manuales en PDF → texto troceado con metadatos
{auto, año, motor, fuente, página, sección}. Cada fragmento guarda su procedencia. - Asistente (F3/F5): recuperación de pasajes del manual + LLM que responde solo con lo recuperado. Si el manual no lo dice, responde «no lo encuentro en el manual». Proyectos de referencia: Toyota/Lexus RAG, AutoMate. Ninguno muestra citas: la cita (página/sección) hay que construirla nosotros.
Hoy es el servidor
api/, que llama a Claude por la API de Anthropic. Consulta la tabla de fusibles (api/src/data/fuses/<auto>.json, de terceros y por verificar), las fichas de las piezas y el manual del propietario conbuscar_manualyleer_manual(el PDF y su índice no van al repo: verdocs/specs/manual/). - Luces del tablero (F4): clasificador de imagen o modelo de visión; datasets abiertos pequeños en Roboflow (p. ej. Dashboard icons, 18 clases) — licencias sin verificar. Significado y acción salen del manual.
- Modelos 3D (F1): cada pieza es un volumen simple, extruido desde un contorno trazado sobre una foto de referencia del vano (
app/src/engine-maps/catalog.ts). No es una malla del auto. - AR (F2): ARCore 1.57 en un módulo nativo propio en Kotlin (
app/modules/capo-ar/), dentro de la app Expo.
Es la parte más incierta. Evidencia disponible:
- Vuforia Model Targets rastrea por forma pero requiere un modelo CAD o escaneo 3D del objeto.
- El rastreo de objetos de ARKit exige escaneo previo (iOS, no aplica). Un foro antiguo y anecdótico dice que ARCore no tiene rastreo de objetos 3D nativo.
- No encontramos evidencia de rastreo sin marcadores de un capó sin modelo previo.
Plan de mitigación (idea nuestra, aún NO probada): anclaje asistido por el usuario. El usuario toca 2–3 puntos de referencia fijos del capó (p. ej. centro de la batería, una esquina del motor); la app coloca el modelo respecto a ellos y lo sostiene con el seguimiento de movimiento (SLAM) de ARCore. Mejora posible después: reconocimiento automático. Probar esto antes que cualquier otra cosa.
Lo que se hizo: al final el anclaje es automático. Un modelo propio detecta el vano del motor y la profundidad de ARCore lo fija en el espacio (herramientas/vano-motor/). Falta validarlo en el Outback (#17).
- Prueba de anclaje AR — cubo/flechas sobre el capó del Outback con puntos de referencia. Si falla, decidir rumbo aquí. (Bloqueante del resto de AR.) Estado: el anclaje automático está hecho; falta probarlo en el Outback (#17).
- Capa de datos y asistente con citas — manual del Outback → fragmentos con procedencia → preguntas en lenguaje natural. (Independiente de AR; paralelizable desde el día 1.) Estado: el chat funciona con la tabla de fusibles; falta indexar el manual.
- Fotos y medidas del capó del Outback + modelos 3D simples de las 5 piezas ubicados según fotos/manual. Estado: hasta 9 piezas por auto, trazadas sobre fotos de referencia; faltan las medidas en el auto.
- Luces del tablero — fotos propias del tablero del Outback + clasificador/modelo; significado desde el manual. Estado: sin empezar.
- Integración — la pregunta del usuario dispara la guía y la AR resalta la pieza. Estado: el chat abre la cámara en la pieza (fase 2 del chat); falta probarlo en el teléfono.
- Aviso obligatorio en la app (visible en primer uso y accesible siempre): «Esta app es una guía informativa. No reemplaza el manual del propietario ni a un mecánico. Confirma siempre con el manual de tu vehículo antes de actuar.» Ya validado con el equipo.
- Toda respuesta muestra su fuente (documento, sección, página). Sin fuente → no se afirma.
- No inventar datos de autos. Si no hay dato público verificable, la app dice «no disponible». Nunca rellenar de memoria el tipo de ampolleta, refrigerante, amperaje de fusible, etc.
- No afirmar ausencias de peligro (p. ej. «aquí no hay cableado de alto voltaje»). La app muestra lo que el manual dice, no lo que no hay.
- Variante exacta importa: año + motor. El 3.6R no es el 2.5i; un diagrama del 2.5i no se asume válido para el 3.6R sin verificarlo en el auto.
- Fuentes de terceros (copias de manuales, sitios de fusibles) se marcan como tales y se contrastan con el auto/manual físico.
- Licencias: revisar licencia de cada dataset/modelo/manual antes de redistribuirlo. Los manuales se citan y enlazan; no redistribuir PDFs en el repositorio sin confirmar que se puede.
- Privacidad: no subir fotos de personas, patentes ni datos personales a servicios externos.
- No usar la identidad personal de integrantes (nombres, correos) en el repositorio público ni en requests a servicios externos.
El APK conversa con el servidor api/, que corre las herramientas y llama al modelo por la API de Anthropic (Claude Sonnet 5.5 por defecto). La key vive solo en el servidor.
- Servidor: el servicio
apideldocker-compose.ymlnecesitaANTHROPIC_API_KEYen el entorno del host. En local:cd api && npm ci && ANTHROPIC_API_KEY=… npm start(puerto 8787). El historial de conversaciones se guarda en SQLite en la ruta deHISTORIAL_DB; sin esa variable, las rutas del historial responden 503. En esa misma base, cada turno del chat queda enturns(modelo, esfuerzo, versión del prompt, pregunta, respuesta, tokens y resultado) y cada herramienta que corre, entool_runs, para analizar las conversaciones; esos logs se leen conGET /api/logs/turnsyGET /api/logs/turns/:id, conAuthorization: Bearery elLOGS_TOKENdel servidor (sin esa variable, esas rutas no existen). El modelo ve como contexto los últimos 30 mensajes. Tests:cd api && npm test. El dictado por voz necesita ademásELEVENLABS_API_KEYen el entorno del host (key con permiso de Speech to Text). El modo vivo del escáner usa la misma key para transcribir en tiempo real: la app pide un token de un solo uso aPOST /api/transcribe/tokeny manda el audio directo al WebSocket de ElevenLabs. La voz del asistente (GET /api/speak, Text to Speech con la misma key) está detrás del ajuste «Leer respuestas en el modo vivo (experimental)», apagado por defecto; verdocs/specs/voz-asistente/. - APK: crea
app/.env.localconEXPO_PUBLIC_API_URL=https://ph26.berguecio.cl(no se commitea) y recompila. Tiene que ser HTTPS: el APK release bloquea HTTP en claro. Tests:cd app && npx tsx --test src/chat/*.test.ts.
- Modo mecánico: contenido avanzado (rutas de correa, mangueras, torques). Requiere datos de taller con licencia (ALLDATA, Mitchell, HaynesPro); dejar la arquitectura de datos abierta a esa capa.
- Más autos, con comunidad aportando fotos y marcas.
- Hardware (track aparte): sonda de fusibles con ESP32 que reporta al teléfono. Idea sin investigar.
- Si el anclaje automático (vano + profundidad de ARCore) es estable en un capó real (reflejos, suciedad, luz) y qué tan cerca de su lugar real quedan las piezas.
- Cobertura real de los manuales del Outback 2016 3.6R: diagrama del capó, tabla de ampolletas, fusibles, luces del tablero. (Las copias de terceros existen; falta revisarlas página por página.)
- Licencias de los datasets de Roboflow y de uso de los manuales.
- Precisión del reconocimiento por cámara para las piezas del capó (no hay benchmark público; hay que medir con fotos propias).
- Si ya existe una app multimarca equivalente que no hayamos encontrado.
- El sapito: depósito del líquido limpiaparabrisas (Chile).
- Varilla / medidor de aceite: dipstick.
- AR: Realidad Aumentada.
- RAG: respuesta generada a partir de pasajes recuperados de documentos propios (aquí, los manuales).
- EZ36 / 3.6R: motor boxer de 6 cilindros 3.6 L del Outback de la época.
Each push to main builds the ARM64 APK, checks its Android package, update
code and hackathon signing certificate, then publishes the verified APK and
its SHA-256 checksum in a public Release tagged with the source commit.
Only the publication job can write releases. Pull requests build and verify
the package without publishing. Failed builds leave the previous APK available.
Download capo-ar.apk from the repository's latest Release. Keep that latest
designation for Android builds so the stable download link works. Android's
update code increases with the first-parent history of main. The Expo template
signing key preserves compatibility with hackathon installations and is publicly
known. Obtain the app from the project's official download link.
