Guía del formato de proyectos

Qué es un proyecto

Un proyecto de Reporithm es un único documento JSON (proyecto-reporithm-v1) que describe un recurso de aprendizaje reproducible en el player del repositorio: título, descripción, código Python que se muestra sincronizado, y —según el formato— un algoritmo en JavaScript que genera la animación (formato: "codigo") o una animación dibujada paso a paso (formato: "animacion", la salida del creador visual).

Puedes crearlo en el creador (modo visual o modo código), escribirlo a mano, o pedírselo a un agente de IA (Claude Code, etc.) dándole esta guía. Para probarlo: creador → Abrir recurso (JSON) → Vista previa. Para publicarlo: botón Publicar en la comunidad, o la API de más abajo.

Estructura común

{
  "_tipo": "proyecto-reporithm-v1",
  "formato": "codigo",              // "codigo" | "animacion"
  "renderer": "array",              // "graph" | "array" | "list" | "hash"
  "titulo": "Suma acumulada",
  "desc": "Recorre el arreglo acumulando la suma.",
  "archivo": "suma.py",             // nombre del archivo Python mostrado
  "badges": [["TIEMPO","O(n)","time"], ["ESPACIO","O(1)","space"]],
  "code": ["def suma(a):", "    total = 0", "    ..."],   // Python mostrado
  "input": { "valores": [6, 3, 8] },   // entrada por defecto de run(input)
  "js": "function run(input) { ... }", // solo formato "codigo"
  "presentacion": { "showCode": true, "autoplay": false, "loop": false }
}

Límite de tamaño: 400 KB. Las clases de las badges son time, space y extra.

Formato «codigo»: run(input) y tracer()

El campo js contiene JavaScript que define function run(input) y devuelve un array de frames. Se ejecuta en un sandbox aislado (Web Worker, sin DOM ni página), con límite de tiempo (6 s) y de pasos (3000). Dispones del helper global tracer(base):

function run(input) {
  var a = (input.valores || [4, 8, 15]).slice();
  var T = tracer({ data: { a: a, estados: {}, ptr: [] } }); // base de cada frame
  T.st.COMPARACIONES = 0;      // T.st: contadores → píldoras de estadísticas
  T.push({ msg: "Inicio", kind: "idle", line: 1 });
  // ... T.push({...}) por cada paso ...
  return T.frames;
}

Campos de un frame

Campo	Descripción
msg	Mensaje del paso (chip coloreado).
kind	Color del chip: idle · select · compare · swap · move · write · visit · front · path · hash · insert · delete · fail · done.
line	Línea (1-based) del código Python a resaltar; 0 = ninguna.
stats	Contadores {ETIQUETA: valor} (T.st los rellena solo).
aux	Fila auxiliar {label, items:[{t, cls}]} (cola, pila…) o null.
data	Estado del escenario; su forma depende del renderer (abajo).

data según el renderer

renderer «array» — tarjetas de un arreglo:

data: {
  a: [6, 3, 8],                       // valores (misma longitud en todos los frames)
  estados: { 0: "cmp-a" },            // "cmp-a"|"cmp-b"|"key"|"ok"|"fail"|"dim"
  ptr: [ { i: 0, label: "i", c: "a" } ]  // punteros; c: "a"|"b"|"k"
}

renderer «graph» — grafo SVG (la clave de arista es "A|B" con los extremos ordenados alfabéticamente):

data: {
  graph: { nodes: [{ id: "A", x: 140, y: 110 }, ...],
           edges: [{ u: "A", v: "B", w: 4 }, ...] },   // igual en todos los frames
  nodos:  { A: "current" },     // "current"|"frontier"|"visited"|"path"|"done"
  aristas:{ "A|B": "active" },  // "active"|"tree"|"path"|"reject"|"dim"
  dist:   { A: "0", B: "∞" },   // etiqueta bajo cada nodo, o null
  inicio: "A", destino: null    // anillos punteados
}

renderer «list» — lista enlazada, pila o cola:

data: {
  modo: "lista",                          // "lista"|"pila"|"cola"
  nodos: [ { v: 7, estado: "current" } ], // ""|"current"|"cmp"|"ok"|"new"|"del"|"dim"
  tags:  [ { i: 0, label: "head", tipo: "head" } ],  // tipo: "head"|"ptr"|"tail"
  flecha: null                            // índice del enlace resaltado
}

renderer «hash» — tabla hash:

data: {
  modo: "chain",                          // "chain"|"open"
  calc: "hash(\"sol\") = 334 % 5 = 4",   // cálculo mostrado, o ""
  activo: 4,                              // cubeta resaltada o null
  buckets: [ [ { k: "sol", estado: "new" } ], [], ... ]  // chain: lista por cubeta
  // modo open: [ {k, estado}|null, ... ]  · estados: ""|"current"|"cmp"|"ok"|"new"|"del"|"tomb"
}

Formato «animacion»

Es lo que produce el creador visual: en lugar de js lleva la estructura y los pasos dibujados. Campos extra: tipo (grafo | arreglo | lista), grafo / arreglo / lista (la estructura) y pasos: [{msg, kind, line, nodos, aristas, celdas}]. Lo más práctico es dibujarlo en el creador y guardar el JSON.

Trabaja con tu agente de IA

Todo lo de esta página existe también en markdown para dárselo a tu agente (Claude Code, etc.): cópialo con el botón, o haz que el agente lo descargue él mismo de https://api.reporithm.com/spec.

Copiar la guía completa (markdown) Ver el markdown

1 · Genera tu token de API

Los agentes necesitan un token de larga duración (90 días) ligado a tu cuenta (docente o superior). Trátalo como una contraseña.

2 · Conecta el servidor MCP (recomendado)

Reporithm expone un servidor MCP real en https://api.reporithm.com/mcp: tu asistente trabaja directamente contra la comunidad — lee la guía, valida documentos, lista y lee proyectos, y publica proyectos o versiones nuevas — igual que tú desde la web. Con Claude Code:

claude mcp add --transport http reporithm https://api.reporithm.com/mcp \
  --header "Authorization: Bearer TU_TOKEN"

Copiar comando

Herramienta MCP	Qué hace
guia_formato	Devuelve esta guía en markdown.
listar_proyectos / obtener_proyecto	Explora la comunidad (con mine incluye tus privados).
validar_proyecto	Valida la estructura de un documento antes de publicar.
crear_proyecto / publicar_version	Publica un proyecto nuevo o una versión (docente+).
actualizar_proyecto	Cambia metadatos (título, resumen, categoría, visibilidad).

3 · O por la API REST

# crear el proyecto (content = el JSON proyecto-reporithm-v1)
curl -s https://api.reporithm.com/projects \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"Suma acumulada","summary":"…","category":"busqueda",
       "tags":["sumas"],"visibility":"private","content":{…}}'   # → public_id

# publicar una versión nueva
curl -s https://api.reporithm.com/projects/$PUBLIC_ID/versions \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"message":"Mejora los mensajes","content":{…}}'

Método	Ruta	Qué hace
GET	/spec	Esta guía en markdown (sin autenticación).
POST	/account/api-token	Token de API de 90 días (docente+).
GET	/projects	Lista pública (?category=&q=&sort=stars|recent&mine=1).
POST	/projects	Crea un proyecto (docente+).
GET	/projects/{id}	Proyecto + contenido de la última versión.
PATCH	/projects/{id}	Metadatos (título, resumen, categoría, tags, visibilidad).
POST	/projects/{id}/versions	Publica una versión nueva.
GET	/projects/{id}/versions[/{n}]	Historial / contenido de una versión.
POST	/projects/{id}/fork	Fork a tu cuenta ({visibility, title}).
PUT	/projects/{id}/star	Da o quita tu estrella.
GET/POST	/projects/{id}/comments	Comentarios.
POST	/projects/{id}/collaborators	Añade un colaborador por correo (solo el dueño).