nature-image2ppt

Nature Image2PPT

Usa este directorio como el entorno de ejecución completo. Ejecuta acciones deterministas solo a través de:

python <image2ppt-root>/cli/image2ppt/cli.py <comando> ...

Usa Python 3.10 o posterior con requirements.txt instalado. Cuando exista un entorno dedicado, sustituye <image2ppt-root>/.venv/bin/python en macOS/Linux o <image2ppt-root>/.venv/Scripts/python.exe en Windows por cada comando python a continuación. No continúes después de un doctor fallido; instala solo la dependencia faltante reportada y luego vuelve a ejecutarlo.

No descubras ni invoques otra habilidad, CLI, prompt, esquema, módulo o máquina de estados.

Lee los contratos locales de forma progresiva

Siempre lee references/workflow.md. Lee references/runtime-dependencies.md solo para la configuración o fallos de doctor, y lee references/ocr-text-hints-contract.md solo al elegir o solucionar problemas de OCR.

Antes de escribir un manifiesto de página, lee references/page-decision-tree.md y references/manifest-schema.md. Agrega solo las referencias necesarias para esa página:

• página estructurada o compuesta: references/region-decomposition.md y references/object-routing.md;
• flechas: references/manifest-arrow-extension.md;
• activos rasterizados o trabajo con backend de imágenes: references/assets-provenance-contract.md.

Antes de aceptar o entregar la salida, lee references/qa-contract.md.

Preserva la fuente única de verdad

• Trata page_jobs.json como la única fuente del estado de las páginas.
• Trata cada pages/page_NNN/manifest.json como la única fuente del contenido de la página.
• Trata deck_manifest.json como la fuente del ensamblaje final.
• Usa solo prepare, run next/dispatch/record/reset/hints/finalize y los comandos de página en la CLI local para operaciones del ciclo de vida con estado.
• Mantén la evidencia de regiones semánticas en manifest.json.image2ppt_region_decomposition.
• Nunca crees un segundo archivo de trabajo, plan de reconstrucción, normalizador de OCR, controlador de página, empaquetador o ruta de finalización.
• Deja que el QA complementario reporte fallos; nunca permitas que mute el estado del ciclo de vida.

Mantén cada escritura dentro de su directorio propietario

• La construcción, validación, sugerencias y QA de la página pueden leer y escribir solo dentro de ese directorio de página. Las rutas de manifiesto, activos registrados, fórmulas, informes, vistas previas y anulaciones --out no deben usar .., enlaces simbólicos o rutas absolutas para escapar de él. La única excepción de entrada externa es un resultado explícito de herramienta de imagen proporcionado a image import o como process-sheet --asset-sheet-source; se copia en la página antes de convertirse en una dependencia de construcción.
• Los manifiestos de nivel de ejecución y las salidas finales deben permanecer dentro del directorio de ejecución preparado. La finalización reconstruye en un archivo temporal del mismo directorio y lo publica atómicamente solo después de una construcción exitosa.
• Trata cualquier rechazo de límite como un fallo grave; no copies el archivo rechazado de vuelta al alcance y lo presentes como salida del tiempo de ejecución.

Preserva el comportamiento previo a la migración

• Trata la autocontención como una migración de ruta/importación/punto de entrada, no un rediseño del comportamiento de reconstrucción.
• Genera cada Prompt de trabajador a partir de la capa base local completa más la capa de perfil Image2PPT preservada. No condenses, reinterpretes ni reemplaces ninguna de las dos capas.
• Prefiere la estrategia visual previamente validada cuando varias rutas cumplan los contratos. Mantén los objetos medidos simples nativos y retén los activos complejos delimitados siempre que un redibujado nativo reduzca la fidelidad.
• Nunca reescribas una línea base de página aceptada meramente para demostrar independencia del tiempo de ejecución.

Ejecuta el flujo de trabajo

Selección del backend de imágenes

Usa builtin-imagegen cuando el tiempo de ejecución del agente exponga image_gen.imagegen; es el backend preferido porque el trabajador puede inspeccionar las entradas de edición e importar el resultado local explícito. Usa el contrato de imagen CLI solo cuando la herramienta integrada no esté disponible, tenga errores, no pueda leer una entrada o no devuelva una salida local válida. Un argumento opcional faltante como modelo, máscara, tamaño, calidad o ruta de salida nunca autoriza la alternativa de respaldo. Registra el productor real y la razón de alternativa permitida en imagegen-jobs.json.

El contrato de imagen CLI es neutral respecto al proveedor en el límite de transporte. Selecciona codex-oauth solo para IDs de modelo GPT Image. Selecciona openai-compatible-api para cualquier modelo específico de proveedor cuyo endpoint implemente el esquema /images/generations y/o /images/edits compatible con OpenAI Images. No infieras el backend de imágenes del modelo de lenguaje de la tarea. Usa un backend explícito cuando la procedencia sea importante; auto usa Codex OAuth solo para IDs de GPT Image compatibles y, de lo contrario, selecciona la API configurada sin enviar credenciales de Codex OAuth a terceros.

1. Verificación previa y elección de OCR

python <image2ppt-root>/cli/image2ppt/cli.py doctor --json

Usa Baidu AI Studio PADDLE_OCR_TOKEN cuando esté configurado. Si está ausente, informa al usuario una vez que la alternativa local builtin-ink mide la geometría del texto pero no reconoce caracteres; ofrece la ruta de configuración en references/ocr-text-hints-contract.md. Respeta una elección sin conexión.

2. Preparar una ejecución

python <image2ppt-root>/cli/image2ppt/cli.py prepare <entrada...> \
  --out-root output/image2ppt --image-backend builtin-imagegen

Para fijar un proveedor/modelo de terceros configurado para una procedencia auditable, prepara con --image-backend openai-compatible-api. El contrato de ejecución registra el IMAGE2PPT_IMAGE_MODEL exacto de la configuración del proyecto activo o del entorno; no sustituye un valor predeterminado de GPT Image simplemente porque no se pasó la bandera --model.

Usa --no-text-hints solo cuando el procesamiento OCR esté intencionalmente deshabilitado. Vuelve a generar sugerencias sin crear una nueva ejecución cuando sea necesario:

python <image2ppt-root>/cli/image2ppt/cli.py run hints <dir-ejecucion>

3. Avanzar y reclamar páginas

python <image2ppt-root>/cli/image2ppt/cli.py run next <dir-ejecucion> --json
python <image2ppt-root>/scripts/build_page_worker_prompt.py \
  <dir-ejecucion> --page <id-pagina> --out <dir-pagina-absoluto>/worker-prompt.md
python <image2ppt-root>/cli/image2ppt/cli.py run dispatch \
  <dir-ejecucion> --page <id-pagina> --agent-id <id> --prompt-file <prompt-absoluto>

Para exactamente una página, reclámala con --local y reconstruye en el agente actual. Para varias páginas, despacha trabajadores de página independientes hasta la capacidad en page_jobs.json. No reinicies un trabajador activo simplemente porque es lento.

4. Reconstruir y compuerta cada página

Planifica una página estructurada como 3–5 regiones semánticas y enruta cada región de forma independiente. Usa diagramas compuestos medidos: mide cada nodo, relación y anclaje protegido. Mantén círculos, tarjetas, relaciones rectas/discontinuas y conectores simples medibles nativos. Usa activos transparentes delimitados solo para subpartes locales complejas.

Representa una flecha delgada como un conector con su punta de flecha en el mismo objeto. Representa una flecha rellena como una Autoforma de Flecha, con el texto de la etiqueta centrado dentro del mismo objeto. Nunca construyas una flecha ordinaria a partir de una línea más un triángulo y nunca aplastes un grafo de conocimiento completo en una imagen.

Escribe nuevos manifiestos de página con schema_version: 2. Usa elementos de visual_inventory estructurados con valores kind y representation explícitos, y escribe una observación quality_evidence concreta para cada verificación de calidad requerida. La representación de fórmulas es una compuerta estricta: un motor faltante, convertidor o compilación fallida debe mantener la página como fallida a menos que el usuario apruebe explícitamente esa excepción de fórmula exacta y el manifiesto registre tanto user_approved_exception: true como una approval_note concreta.

El Prompt del trabajador realiza la secuencia determinista. Sus compuertas finales son:

python <image2ppt-root>/cli/image2ppt/cli.py page build <dir-pagina>
python <image2ppt-root>/scripts/run_image2ppt_qa.py <dir-pagina>
# La primera ejecución escribe visual-review-evidence.template.json y permanece pendiente.
# Inspecciona source.png contra render/rendered.png, copia y completa la plantilla
# como visual-review-evidence.json, repara si es necesario, luego:
python <image2ppt-root>/scripts/run_image2ppt_qa.py <dir-pagina> \
  --visual-review-status reviewed \
  --visual-review-evidence <dir-pagina>/visual-review-evidence.json
python <image2ppt-root>/cli/image2ppt/cli.py page contact-sheet <dir-pagina>

El archivo de evidencia debe cubrir los hashes actuales de source/render y cada verificación requerida con una observación específica. --visual-review-notes es contexto opcional y no puede sustituir al archivo de evidencia.

Registra solo después de que pasen la validación estándar y las compuertas de región, flecha y representación de Image2PPT:

python <image2ppt-root>/cli/image2ppt/cli.py run record \
  <dir-ejecucion> --page <id-pagina> --agent-id <id>

Usa el mismo ciclo de vida run reset → dispatch → record para reparar páginas rechazadas.

5. Finalizar y revalidar la presentación reconstruida

Cuando run next reporte finalize, ejecuta:

python <image2ppt-root>/cli/image2ppt/cli.py run finalize <dir-ejecucion>
python <image2ppt-root>/scripts/run_final_image2ppt_qa.py <dir-ejecucion>
# La primera ejecución escribe final/visual-review-evidence.template.json y permanece pendiente.
# Inspecciona cada diapositiva renderizada, completa final/visual-review-evidence.json, luego:
python <image2ppt-root>/scripts/run_final_image2ppt_qa.py <dir-ejecucion> \
  --visual-review-status reviewed \
  --visual-review-evidence <dir-ejecucion>/final/visual-review-evidence.json

Finalizar reconstruye a partir de los manifiestos de página, preserva las notas del orador de la fuente, valida el paquete y escribe la salida registrada por deck_manifest.json. El QA final reaplica las flechas del manifiesto, verifica la atomicidad de las flechas y la estructura compuesta, renderiza cada diapositiva, verifica la integridad de las notas del orador y escribe final/image2ppt_qa.json.

Entregar

Devuelve la ruta final del PPTX, la validación final estándar y final/image2ppt_qa.json. Informa qué imágenes complejas permanecen como activos de mapa de bits reemplazables. No consideres la presentación completa mientras alguna compuerta de página o final esté pendiente o haya fallado.