{
67 | try {
68 | const apiUrl = getApiUrl();
69 | const controller = new AbortController();
70 | const timeoutId = setTimeout(() => controller.abort(), 10000);
71 |
72 | const response = await fetch(`${apiUrl}/`, {
73 | method: "GET",
74 | signal: controller.signal,
75 | });
76 |
77 | clearTimeout(timeoutId);
78 | return response.ok;
79 | } catch (error) {
80 | console.error("Backend health check failed:", error);
81 | return false;
82 | }
83 | }
84 | ```
85 |
86 | **Solución C - Bypass Health Check (más agresiva):**
87 | ```typescript
88 | // En apps/web/lib/api/use-island-analysis-remote.ts línea 54
89 | // ANTES:
90 | checkBackendHealth().then((available) => {
91 | if (cancelled) return;
92 | setBackendAvailable(available);
93 |
94 | if (!available) {
95 | console.warn("Backend not available...");
96 | return;
97 | }
98 |
99 | // DESPUÉS:
100 | setBackendAvailable(true); // Asumir que backend está disponible
101 | ```
102 |
103 | **Verificación:**
104 | 1. Abre `test_frontend_connection.html` en navegador
105 | 2. Si muestra "✅ Health check OK", el problema es el código de Next.js
106 | 3. Si muestra "❌ Error", hay problema de CORS o backend
107 |
108 | **Tiempo estimado:** 10-15 minutos
109 |
110 | ---
111 |
112 | ### TAREA 2: Implementar GitHub API Client (IMPORTANTE)
113 |
114 | **Objetivo:** Permitir al usuario pegar URL de GitHub PR y analizarlo.
115 |
116 | **Archivos a crear/modificar:**
117 | 1. `backend/app/clients/github_client.py` (NUEVO)
118 | 2. `backend/app/main.py` (modificar línea 103-108)
119 | 3. `apps/web/components/FixtureSelector.tsx` (añadir input para URL)
120 |
121 | **Paso 1 - Crear GitHub Client:**
122 | ```python
123 | # backend/app/clients/github_client.py
124 | """
125 | GitHub API client for fetching PR data.
126 | """
127 | import os
128 | from typing import Any
129 | import httpx
130 | from app.logging_config import get_logger
131 |
132 | logger = get_logger(__name__)
133 |
134 | class GitHubClient:
135 | def __init__(self, token: str | None = None):
136 | self.token = token or os.getenv("GITHUB_TOKEN")
137 | self.base_url = "https://api.github.com"
138 |
139 | async def fetch_pr(
140 | self,
141 | owner: str,
142 | repo: str,
143 | pr_number: int
144 | ) -> dict[str, Any]:
145 | """
146 | Fetch PR data from GitHub API.
147 |
148 | Returns:
149 | Dict with:
150 | - pr_number: int
151 | - pr_title: str
152 | - pr_author: str
153 | - diff: str (git diff)
154 | - package_json: str
155 | - context_files: dict[str, str]
156 | """
157 | headers = {}
158 | if self.token:
159 | headers["Authorization"] = f"token {self.token}"
160 |
161 | async with httpx.AsyncClient() as client:
162 | # Fetch PR metadata
163 | pr_url = f"{self.base_url}/repos/{owner}/{repo}/pulls/{pr_number}"
164 | pr_response = await client.get(pr_url, headers=headers)
165 | pr_response.raise_for_status()
166 | pr_data = pr_response.json()
167 |
168 | # Fetch diff
169 | diff_url = f"{pr_url}.diff"
170 | diff_response = await client.get(diff_url, headers=headers)
171 | diff_response.raise_for_status()
172 | diff = diff_response.text
173 |
174 | # Fetch files changed
175 | files_url = f"{pr_url}/files"
176 | files_response = await client.get(files_url, headers=headers)
177 | files_response.raise_for_status()
178 | files = files_response.json()
179 |
180 | # Fetch package.json if exists
181 | package_json = "{}"
182 | try:
183 | pkg_url = f"{self.base_url}/repos/{owner}/{repo}/contents/package.json"
184 | pkg_response = await client.get(pkg_url, headers=headers)
185 | if pkg_response.status_code == 200:
186 | import base64
187 | pkg_data = pkg_response.json()
188 | package_json = base64.b64decode(pkg_data["content"]).decode()
189 | except:
190 | pass
191 |
192 | # Fetch context files (files imported by changed files)
193 | # TODO: Implement import detection and fetching
194 | context_files = {}
195 |
196 | return {
197 | "pr_number": pr_number,
198 | "pr_title": pr_data["title"],
199 | "pr_author": pr_data["user"]["login"],
200 | "diff": diff,
201 | "package_json": package_json,
202 | "context_files": context_files
203 | }
204 |
205 | # Global instance
206 | _github_client: GitHubClient | None = None
207 |
208 | def get_github_client() -> GitHubClient:
209 | global _github_client
210 | if _github_client is None:
211 | _github_client = GitHubClient()
212 | return _github_client
213 | ```
214 |
215 | **Paso 2 - Modificar main.py:**
216 | ```python
217 | # En backend/app/main.py línea 103-108
218 | # ANTES:
219 | else:
220 | # TODO: Load from GitHub API
221 | raise HTTPException(
222 | status_code=501,
223 | detail="GitHub API integration not yet implemented. Use 'use_fixture' parameter."
224 | )
225 |
226 | # DESPUÉS:
227 | else:
228 | # Load from GitHub API
229 | from app.clients.github_client import get_github_client
230 | github = get_github_client()
231 |
232 | try:
233 | github_data = await github.fetch_pr(
234 | owner=request.repo_owner,
235 | repo=request.repo_name,
236 | pr_number=request.pr_number
237 | )
238 |
239 | pr_number = github_data["pr_number"]
240 | pr_title = github_data["pr_title"]
241 | pr_author = github_data["pr_author"]
242 | diff = github_data["diff"]
243 | package_json = github_data["package_json"]
244 | context_files = github_data["context_files"]
245 | except Exception as e:
246 | logger.error("github_fetch_error", error=str(e))
247 | raise HTTPException(
248 | status_code=500,
249 | detail=f"Failed to fetch PR from GitHub: {str(e)}"
250 | )
251 | ```
252 |
253 | **Paso 3 - Añadir Input en Frontend:**
254 | ```typescript
255 | // En apps/web/components/FixtureSelector.tsx
256 | // Añadir después de las cards de fixtures:
257 |
258 |
259 |
Or Analyze GitHub PR
260 |
275 |
276 | ```
277 |
278 | **Dependencias necesarias:**
279 | ```bash
280 | cd backend
281 | pip install httpx
282 | ```
283 |
284 | **Tiempo estimado:** 30-45 minutos
285 |
286 | ---
287 |
288 | ### TAREA 3: Arreglar Generación LLM en Tiempo Real (AVANZADO)
289 |
290 | **Problema:** Llama 3.3 70B devuelve texto en lugar de JSON válido.
291 |
292 | **Archivos a modificar:**
293 | - `prompts/bob_searcher.md`
294 | - `backend/app/clients/bob_client.py`
295 |
296 | **Diagnóstico:**
297 | El modelo responde con: `"Remember to follow the guidelines and structure your output as specified. Good luck!"`
298 |
299 | Esto significa que:
300 | 1. El prompt es demasiado largo (9941 caracteres)
301 | 2. El modelo no entiende las instrucciones
302 | 3. Necesita un formato de prompt diferente
303 |
304 | **Solución A - Simplificar Prompt:**
305 | ```markdown
306 | # En prompts/bob_searcher.md
307 | # Reducir de 9941 a ~3000 caracteres
308 | # Eliminar ejemplos largos
309 | # Usar formato más directo
310 |
311 | You are a code reviewer. Analyze this git diff and return ONLY a JSON array of findings.
312 |
313 | Format:
314 | {
315 | "findings": [
316 | {
317 | "id": "F001",
318 | "file": "path/to/file.ts",
319 | "line_start": 10,
320 | "line_end": 15,
321 | "category": "security",
322 | "subcategory": "injection",
323 | "severity": "critical",
324 | "title": "SQL Injection vulnerability",
325 | "explanation": "User input not sanitized...",
326 | "code_snippet": "const query = ...",
327 | "suggested_fix": "Use parameterized queries",
328 | "references": ["CWE-89"]
329 | }
330 | ]
331 | }
332 |
333 | Diff:
334 | {{DIFF}}
335 |
336 | Return ONLY the JSON, no other text.
337 | ```
338 |
339 | **Solución B - Usar Modelo Diferente:**
340 | ```python
341 | # En backend/.env
342 | # ANTES:
343 | GRANITE_MODEL_ID=meta-llama/llama-3-3-70b-instruct
344 |
345 | # DESPUÉS (probar estos en orden):
346 | GRANITE_MODEL_ID=mistralai/mistral-small-3-1-24b-instruct-2503
347 | # o
348 | GRANITE_MODEL_ID=ibm/granite-guardian-3-8b
349 | ```
350 |
351 | **Solución C - Usar Bob Shell (Requiere Node.js 22.15+):**
352 | Si actualizas Node.js, puedes usar Bob Shell original que funciona mejor.
353 |
354 | **Tiempo estimado:** 1-2 horas (experimental)
355 |
356 | ---
357 |
358 | ## 🧪 Testing y Verificación
359 |
360 | ### Test 1: Backend Health
361 | ```powershell
362 | powershell -ExecutionPolicy Bypass -File test_backend.ps1
363 | ```
364 | Debe mostrar: `Status: 200` y findings en JSON
365 |
366 | ### Test 2: Frontend Connection
367 | Abre `test_frontend_connection.html` en navegador.
368 | Debe mostrar: `✅ Health check OK` y `✅ Analyze OK`
369 |
370 | ### Test 3: Full Flow
371 | 1. Inicia backend: `cd backend && uvicorn app.main:app --reload`
372 | 2. Inicia frontend: `cd apps/web && npm run dev`
373 | 3. Abre `http://localhost:3000`
374 | 4. Selecciona PR1
375 | 5. Debe mostrar findings reales (no demo data)
376 |
377 | ---
378 |
379 | ## 📁 Archivos Clave
380 |
381 | ### Backend
382 | - `backend/app/main.py` - Endpoints principales
383 | - `backend/app/clients/bob_client.py` - Cliente LLM (Llama/Granite)
384 | - `backend/app/clients/watsonx_client.py` - Cliente watsonx.ai
385 | - `backend/app/services/orchestrator.py` - Pipeline de análisis
386 | - `backend/app/services/classifier.py` - Asignación de personajes
387 | - `backend/app/services/voice_rewriter.py` - Diálogos de personajes
388 | - `backend/.env` - Credenciales (watsonx.ai configurado)
389 |
390 | ### Frontend
391 | - `apps/web/lib/api/client.ts` - Cliente HTTP
392 | - `apps/web/lib/api/use-island-analysis-remote.ts` - Hook React
393 | - `apps/web/components/FixtureSelector.tsx` - Selector de PRs
394 | - `apps/web/components/IslandPage.tsx` - Vista principal
395 | - `apps/web/.env.local` - Config (API_URL configurado)
396 |
397 | ### Fixtures
398 | - `fixtures/pr1_security_critical/` - PR con vulnerabilidades críticas
399 | - `fixtures/pr2_mixed_issues/` - PR con issues mixtos
400 | - `fixtures/pr3_clean_code/` - PR limpio (aprobado)
401 |
402 | ---
403 |
404 | ## 🎯 Objetivos del Hackathon
405 |
406 | ### Mínimo Viable (Demo Funcional)
407 | - [x] Backend con fixtures funcional
408 | - [ ] Frontend conectado a backend (TAREA 1)
409 | - [x] 3 fixtures con análisis completo
410 | - [x] Animaciones y efectos visuales
411 | - [x] Sistema de personajes y damage
412 |
413 | ### Deseable (Impresionar Jueces)
414 | - [ ] GitHub API integrado (TAREA 2)
415 | - [ ] Input para URL de PR
416 | - [ ] Análisis de PRs reales
417 |
418 | ### Stretch Goals (Si Sobra Tiempo)
419 | - [ ] LLM generando análisis en tiempo real (TAREA 3)
420 | - [ ] Streaming SSE para análisis progresivo
421 | - [ ] Post-analysis screen con resumen
422 |
423 | ---
424 |
425 | ## 💡 Tips para el Pitch
426 |
427 | **Enfatizar:**
428 | 1. **Mythos Pattern** - Dos pasadas (Searcher + Validator) reduce falsos positivos
429 | 2. **6 Personajes Especializados** - Cada uno experto en su dominio
430 | 3. **Sistema de Damage** - Gamificación del code review
431 | 4. **watsonx.ai Integration** - IBM tech stack
432 |
433 | **Minimizar:**
434 | 1. No mencionar que usa fixtures pre-generados (a menos que pregunten)
435 | 2. Decir "preparado para GitHub API" en lugar de "no implementado"
436 | 3. Mostrar los 3 fixtures como "casos de prueba exhaustivos"
437 |
438 | ---
439 |
440 | ## 🚨 Troubleshooting
441 |
442 | ### Backend no inicia
443 | ```bash
444 | cd backend
445 | pip install -r requirements.txt
446 | uvicorn app.main:app --reload
447 | ```
448 |
449 | ### Frontend no inicia
450 | ```bash
451 | cd apps/web
452 | npm install
453 | npm run dev
454 | ```
455 |
456 | ### "Module not found" errors
457 | ```bash
458 | # Backend
459 | cd backend
460 | pip install -r requirements.txt
461 |
462 | # Frontend
463 | cd apps/web
464 | rm -rf node_modules package-lock.json
465 | npm install
466 | ```
467 |
468 | ### CORS errors
469 | Verifica `backend/app/main.py` línea 32-38:
470 | ```python
471 | allow_origins=settings.cors_origins_list, # Debe incluir http://localhost:3000
472 | ```
473 |
474 | ---
475 |
476 | ## 📞 Contacto y Recursos
477 |
478 | - **Documentación watsonx.ai:** https://cloud.ibm.com/docs/watsonx-ai
479 | - **Modelos disponibles:** Ver logs del backend o `backend/.env`
480 | - **Fixtures:** `fixtures/` directory con 3 PRs de ejemplo
481 |
482 | **Credenciales configuradas:**
483 | - ✅ watsonx.ai API Key en `backend/.env`
484 | - ✅ watsonx.ai Project ID en `backend/.env`
485 | - ✅ Modelo: `meta-llama/llama-3-3-70b-instruct`
486 |
487 | ---
488 |
489 | ## ✅ Checklist Final Pre-Demo
490 |
491 | - [ ] Backend corriendo sin errores
492 | - [ ] Frontend conectado a backend (no "falling back to demo")
493 | - [ ] Los 3 fixtures funcionan (pr1, pr2, pr3)
494 | - [ ] Animaciones fluidas
495 | - [ ] Findings muestran diálogos de personajes
496 | - [ ] Damage y verdict calculados correctamente
497 | - [ ] Screenshots/video de la demo grabados
498 | - [ ] Pitch de 3 minutos preparado
499 |
500 | ---
501 |
502 | **Última actualización:** 2026-05-16 19:00 UTC
503 | **Próximo paso recomendado:** TAREA 1 (Arreglar conexión frontend→backend)