stars-explorer

# Stars Explorer — Pipeline de Aprendizaje Automático ## Resumen Pipeline recurrente que explora las ~100+ stars de GitHub de David (Ntizar), analiza los repos más interesantes, extrae patrones arquitectónicos y crea skills automáticamente en el sistema Mastermind/Hermes. **Objetivo:** Cada noche, el sistema aprende de los repos que David le gusta, ampliando la base de conocimiento de skills de forma autónoma. ## Arquitectura ``` Cron (nocturno 03:00 UTC) ↓ Script explorar-stars.py (batch de 3 repos) ↓ Fetch GitHub API → README + tree + key files ↓ Análisis: tech stack, patterns, skill angles ↓ Actualiza stars-registry.json ↓ Agent processa el output del script ↓ Para cada repo: decide si merece skill ↓ Crea skill con skill_manage si es relevante ↓ Actualiza registry (category, skill_created) ↓ Re-indexa ChromaDB (si hubo cambios) ↓ Guarda resumen en notes/ si hubo hallazgos significativos ``` ## Componentes ### Script principal - **Ruta:** `/hermes-home/scripts/explorar-stars.py` - **Wrapper:** `bash /hermes-home/scripts/run-stars-explorer.sh` (carga entorno automáticamente) - **Dependencias:** Solo stdlib (urllib, json, base64) — NO necesita pip install - **Entorno:** Wrapper carga variables de entorno del sistema automáticamente ### Registry - **Ruta:** `/hermes-home/data/stars-registry.json` - **Contenido:** Repo → fecha explorada, category, skill_created, skill_angles ### Skill de referencia - **chromadb-skills-vector-search** — Para re-indexar después de crear skills ## Uso del Script Usar SIEMPRE el wrapper que carga el entorno automáticamente: ```bash # Status del registry bash /hermes-home/scripts/run-stars-explorer.sh --status # Batch de 3 repos (default) — solo repos >100 stars con topics bash /hermes-home/scripts/run-stars-explorer.sh # Batch grande bash /hermes-home/scripts/run-stars-explorer.sh --batch 5 # Todos los pendientes (SIN FILTRO — explora todos) bash /hermes-home/scripts/run-stars-explorer.sh --all # Modo JSON (para agent consumption) bash /hermes-home/scripts/run-stars-explorer.sh --batch 2 --json # Incluir propios repos de David bash /hermes-home/scripts/run-stars-explorer.sh --include-own # Forzar re-proceso de un repo bash /hermes-home/scripts/run-stars-explorer.sh --reprocess owner/repo # Modo LOOP DE APRENDIZAJE — modo completo: explora → aprende → mejora → implementa bash /hermes-home/scripts/run-stars-explorer.sh --learning-loop ``` ## Flujo del Agent (en el cron) Al recibir el output del script, el agent debe: 1. **Leer cada repo analizado** del JSON 2. **Evaluar si merece skill** basándose en: - ¿Tiene patrones reutilizables? (architecture, pipeline, performance) - ¿Es relevante para los proyectos de David? (3D, CV, geospatial, CRM, transit) - ¿Aporta conocimiento que NO tenemos ya? - ¿Tiene enough profundidad para justificar un skill? 3. **Crear skill** con `skill_manage(action='create')` si: - El repo tiene patrones claros y reutilizables - El skill serait útil en futuras tareas - No duplica un skill existente (check ChromaDB primero) 4. **Marcar en registry** como `skill_created: true` + categoría 5. **Re-indexar ChromaDB** al final si se crearon skills ### Criterios de Creación de Skill **Crear skill si:** - Repo tiene patrones arquitectónicos reutilizables (3+ patterns detectados) - Tech stack relevante para proyectos existentes de David - El README describe approach único o innovador - Tiene +1000 stars (indica calidad/comunidad) - El repo es de David (siempre crear, es su conocimiento) **NO crear skill si:** - Solo tiene README genérico sin patrones concretos - Es un "awesome list" o curated list sin código - Ya existe un skill cubriendo lo mismo - El repo está archivado o sin maintenimiento - Es demasiado simple (<100 stars, sin code patterns) **Categorías para el registry:** - `core` — Skills que son parte fundamental del sistema - `domain` — Conocimiento de dominio específico (CV, GIS, transit) - `pattern` — Patrones arquitectónicos reutilizables - `tool` — Herramientas y librerías concretas - `reference` — Referencia/inspiración (no skill directo) - `skip` — Decidido no procesar (awesome list, etc.) ## Datos del Script Output Cada repo analizado incluye: ```json { "full_name": "owner/repo", "description": "...", "language": "Python", "stars": 1234, "topics": ["topic1", "topic2"], "tech_stack": ["django", "postgres", "..."], "potential_patterns": ["pipeline", "real-time", "ai/ml"], "skill_angles": ["ai-cv-pipeline"], "readme_excerpt": "primeros 2000 chars del README", "key_files_present": ["package.json", "Dockerfile"], "file_types": {".py": 15, ".js": 8} } ``` ## Pitfalls - **Rate limit GitHub:** 5000 req/h autenticados. Batch de 3 repos ≈ 20 req cada uno = 60/batch. Safe. - **README enorme:** Truncado a 8000 chars. Suficiente para análisis. - **Skills duplicados:** SIEMPRE consultar ChromaDB antes de crear. Si un skill semánticamente similar existe, NO crear otro. Verificado en producción: manim→skip (score 0.85 contra creative/manim-video), twenty→skip (score 0.79 contra crm-erp-fullstack), VibeVoice→skip (score 0.89 contra media/voicebox). - **Quality gate:** No crear skills de "awesome lists" o repos sin código sustancial. - **Re-indexación ChromaDB:** Obligatoria tras crear skills. Sin ella, los nuevos skills son invisibles en búsquedas semánticas. - **Registry creep:** Si un repo no merece skill, marcar con `category: "skip"` y `skill_created: false`. NO re-procesarlo cada run. - **Cron security scanner (CRÍTICO 2026-06-16):** El scanner de cron bloquea prompts que contienen patrones como `cat .env`, `cat credentials`, etc. (regex: `cat\s+[^\n]*(\.env|credentials|\.netrc|\.pgpass)`). **Solución:** usar wrapper script (`run-stars-explorer.sh`) que carga el entorno internamente. NUNCA poner comandos que lean secrets directamente en prompts de cron ni en skills que se carguen en crons. El scanner escanea el prompt ensamblado (user prompt + skill content concatenado). - **ChromaDB dedup funciona en producción (2026-06-16):** El pipeline detectó correctamente 3 repos como "ya cubiertos" en el primer batch nocturno. Scores: manim=0.85, twenty=0.79, VibeVoice=0.89. Threshold 0.25 es suficiente para detectar duplicados semánticos. - **Wrapper script obligatorio para cron:** El script `explorar-stars.py` necesita variables de entorno (token de GitHub, API key de NaN). En vez de exponer el patrón de lectura en el prompt del cron, usar `bash /hermes-home/scripts/run-stars-explorer.sh` que hace source del .env internamente. - **Skill overlap con github-trending-research:** `github-trending-research` explora trending público; `stars-explorer` explora las stars personales de David. Complementarios, no duplicados. Comparten patrones de GitHub API, creación de skills, y dedup via ChromaDB. ## Loop de Aprendizaje Continuo El sistema **no es solo explorador** — es un **motor de aprendizaje** que cada noche: ### Diagrama del Loop ``` 🌙 Cron (03:00 UTC) ↓ 🔍 Explorar 3 stars nuevos ↓ 📖 Analizar README + tree + key files ↓ 🧠 ¿Merece skill? (ChromaDB dedup) ↓ ├── ✅ Sí → Crear skill → Indexar en ChromaDB └── ❌ No → Marcar como skip (razón) ↓ 📈 Registrar en stars-registry.json ↓ 🎯 ¿Patrón relevante para proyecto activo? ↓ ├── Sí → Micro-cron de seguimiento semanal └── No → Esperar próxima noche ↓ 🔄 Loop infinito → Cada noche 3 skills nuevos ``` ### Fases del ciclo | Fase | Descripción | Responsable | |------|-------------|-------------| | **🔍 Explorar** | Fetch 3 repos no procesados | Script `explorar-stars.py` | | **📖 Aprender** | Analizar tech stack + patrones | Agent (con `stars-explorer` skill) | | **✨ Mejorar** | ¿El patrón es nuevo? → skill | Agent + ChromaDB | | **🛠️ Implementar** | Crear skill + indexar | `skill_manage` + `indexar-skills.py` | | **📊 Registrar** | Actualizar registry | Script guarda en JSON | | **👁️ Watch** | Micro-cron semanal si repo >500⭐ | `cronjob` | ### Criterio Avanzado de Creación de Skill **Matriz de decisión:** (stars × topic_count × pattern_diversity) / existing_skill_overlap ```python def should_create_skill(repo): score = repo['stars'] * (1 + 0.1*len(repo['topics'])) * (1 + 0.2*len(repo['potential_patterns'])) # Penalizar si ya hay skill similar chroma_score = chromadb_search(repo['description']) if chroma_score > 0.25: return False return score > 500 # Threshold mínimo ``` ### Micro-crons de Seguimiento Cuando un repo >500⭐ tiene patrones relevantes para un proyecto activo: ```bash # Automatizado por el cron cronjob(action='create', name=f'watch-{repo_basename}', schedule='0 0 * * 1', # Cada lunes prompt=f"Revisar nuevas releases/issues de {owner}/{repo}") ``` Estos micro-crons se auto-destruyen tras 4 semanas si no generan ningún skill → `skill_created: false` en registry tras 4 ciclos sin actividad. --- ## Bulk Processing — Modo "Hazlo Rápido" 🚀 Cuando el usuario pide **procesar TODAS las stars de una vez** (no esperar al cron): ### Pipeline completo (1 hora para ~117 repos) ``` Fase 1: Registrar todas → Fase 2: Clasificar → Fase 3: Analizar en lote → Fase 4: Crear skills → Fase 5: Indexar ChromaDB → Fase 6: GitHub push ``` ### Fase 1 — Registrar masivamente No usar `--all` (timeout 300s). Hacer fetch de todas las stars paginadas + repo info básica (sin README) en batch: ```bash # Fetch de todas las stars curl -s "https://api.github.com/users/Ntizar/starred?per_page=100&page=1" -H "Authorization: token $GITHUB_TOKEN" # Registrar cada repo en el registry como "pending" con stars_count + language # 1 llamada API por repo (GET /repos/{owner}/{repo}) # ~30 segundos para 50 repos ``` ### Fase 2 — Clasificar en 4 tiers ```python tiers = { "high": stars >= 3000, # → subagent prioritario "medium": 500 <= stars < 3000, # → subagent si hay slots "low": stars < 500, # → cron (no urgente) "skip": "awesome" in name.lower() or "clone-wars" in name.lower(), or "collection" in name.lower(), # → marcar y olvidar } ``` También detectar **ALREADY_COVERED** por nombre: si el repo coincide con un skill existente (voicebox→media/voicebox, mlx-vlm→mlx-vlm-inference, nango→nango, city2graph→geoai-city2graph-pattern, postgres-mcp→postgres-mcp, gaze-tracking→gaze-tracking, supervision→vision/roboflow-supervision, etc.) ### Fase 3 — Análisis en lote con subagentes paralelos ```python # 3 subagentes × 6-8 repos cada uno delegate_task(tasks=[ {"goal": "Analizar 6 repos y decidir skills (CREATE/SKIP/COVERED)", "context": "REPOS: [lista de 6...]", "toolsets": ["terminal", "file"]}, ... # hasta 3 tasks en paralelo ]) # Cada subagente: fetch README → check existing skills → decidir CREATE/SKIP/COVERED # Output: JSON con decisión por repo ``` **IMPORTANTE:** Cada subagente recibe una lista explícita de "ya cubiertos" para que no investigue skills existentes desde cero. Pasar en context: ```python context = f""" Ya existen skills para: voicebox (media/voicebox), mlx-vlm (mlx-vlm-inference), nango (nango), city2graph (geoai-city2graph-pattern), postgres-mcp (postgres-mcp), gaze-tracking (gaze-tracking), supervision (vision/roboflow-supervision), crm-erp-fullstack (mastermind/), etc. Repo high-value para analizar: {repo_list} """ ``` ### Fase 4 — Crear skills Para cada repo con CREATE_SKILL: ```python # 1. Fetch README completo (o leer del JSON ya guardado) # 2. skill_manage(action='create', name=..., category=..., content=SKILL.md) # 3. skill_manage(action='patch', name='stars-explorer', ...) # NO — marcar en registry ``` La creación debe ser **rápida**: SKILL.md conciso pero útil, con: - YAML frontmatter (name, version, description, tags) - Resumen del repo - Instalación y uso básico - Integración con Mastermind - Referencia al repo original ### Fase 5 — Indexar en ChromaDB ```bash bash /hermes-home/scripts/start-chromadb.sh # Si no está running python3 /hermes-home/scripts/indexar-skills.py # Re-indexa todo ``` ### Fase 6 — Subir a GitHub (OBLIGATORIO) **Todos los skills deben estar en el repo Mastermind de GitHub.** David es explícito: "recuerda que estén en el github de mastermind también". ```bash # Copiar skills al repo cp -r /hermes-home/skills/<category>/<skill-name> /root/workspace/Mastermind/skills/<category>/ cp /hermes-home/data/stars-registry.json /root/workspace/Mastermind/data/ cp /hermes-home/scripts/explorar-stars.py /root/workspace/Mastermind/scripts/ cp /hermes-home/scripts/run-stars-explorer.sh /root/workspace/Mastermind/scripts/ # Commit + push cd /root/workspace/Mastermind git add -A git commit -m "✨ Stars Explorer: <N> skills nuevos de stars de David" git push ``` ### Resumen de tiempos (117 repos) | Fase | Tiempo | |------|--------| | Registrar 117 repos | ~40s | | Clasificar | ~2s | | 3 subagentes × 6 repos (paralelo) | ~3-5 min | | Crear 8 skills | ~3 min | | Indexar ChromaDB | ~1 min | | GitHub push | ~30s | | **Total** | **~10 min** | ### Lecciones aprendidas (próxima vez) - El `--all` del script timeout a 300s → mejor registrar manualmente con paginación - Los subagentes de `delegate_task` necesitan **context explícito** sobre qué skills ya existen (evita que investiguen desde cero) - Los repos "awesome-*", "Clone-Wars" etc. se SKIP automáticamente - Los skills deben estar en `/hermes-home/skills/` (el sistema Hermes) Y en `/root/workspace/Mastermind/skills/` (GitHub) ## Cron Asociado - **Nombre:** `stars-explorer-nocturno` - **Schedule:** 0 3 * * * (03:00 UTC diario) - **Job ID:** `f22516e4ab77` - **Batch:** 3 repos/run → 3 por noche