CrewAI Vision Tool

Pipeline multiagente que extrae y estructura albaranes (notas de entrega) a partir de imágenes. Combina varios motores OCR, convierte el texto en JSON validado con Pydantic y consolida los resultados con un agente validador que además emite un reporte de validación legible.

Construido sobre CrewAI. Pensado para ser profesional y mantenible: configuración por YAML, salida tipada, guardrails deterministas, tests y un flujo de trabajo Spec-Driven Development (SDD) con Claude Code.

---

Índice

1. ¿Qué hace?
2. Arquitectura del pipeline
3. Estructura del proyecto
4. Requisitos previos
5. Instalación paso a paso
6. Configuración (.env)
7. Primer uso (quickstart)
8. Uso avanzado
9. Salidas generadas
10. Esquema de datos (Albaran)
11. Modelos LLM y coste
12. Tests y verificación
13. Solución de problemas
14. Desarrollo (Claude Code + SDD)
15. Licencia

---

¿Qué hace?

Le pasas la ruta de una imagen de un albarán y obtienes:

• Un JSON estructurado y validado (output/document_final.json) con los datos del documento, cliente, líneas de producto, totales y entrega.
• Un reporte de validación en Markdown (output/validation_report.md) que explica discrepancias entre motores, decisiones de consolidación y nivel de confianza.

Principios de diseño clave:

• Múltiples motores OCR en paralelo: EasyOCR, Tesseract y Ollama Vision (PaddleOCR y OpenAI Vision disponibles como opción). La diversidad reduce errores de un único motor.
• Honestidad de datos (null-honesto): si un campo no aparece o es ilegible, se devuelve null. Nunca se inventan datos.
• Consolidación con guardrail determinista: una función pura verifica la coherencia Σ líneas ≈ totales (con tolerancia) sin fabricar cifras.

Arquitectura del pipeline

flowchart TD
    img["image_url (ruta de imagen)"] --> ex

    subgraph ex [1 - Extraccion OCR en paralelo]
        ocr1[Ollama Vision]
        ocr2[Tesseract]
        ocr3[EasyOCR]
    end

    ocr1 --> an1["Analisis -> AlbaranRaw (JSON)"]
    ocr2 --> an2["Analisis -> AlbaranRaw (JSON)"]
    ocr3 --> an3["Analisis -> AlbaranRaw (JSON)"]

    an1 --> cons["2 - Consolidacion -> Albaran + guardrail coherencia"]
    an2 --> cons
    an3 --> cons

    cons --> jsonout["output/document_final.json"]
    cons --> rep["3 - Reporte de validacion"]
    rep --> mdout["output/validation_report.md"]

| Etapa | Agente(s) | Entrada | Salida | | --- | --- | --- | --- | | 1. Extracción | 3 extractores OCR | imagen | texto crudo por motor | | 2a. Análisis | analista estructurado | texto crudo | AlbaranRaw (JSON sin confidence) | | 2b. Consolidación | validador | 3 análisis | Albaran final + guardrail de coherencia | | 3. Reporte | validador | consolidado + análisis | validation_report.md |

Estructura del proyecto

crewai-vision-tool/
├── src/crewai_vision_tool/
│   ├── config/
│   │   ├── agents.yaml          # Roles, goals y modelo LLM de cada agente
│   │   └── tasks.yaml           # Descripción y salida esperada de cada tarea
│   ├── tools/
│   │   ├── tools_local_ocr.py   # EasyOCR, PaddleOCR, Tesseract
│   │   ├── tool_ollama_vision.py# Ollama Vision (local)
│   │   ├── tool_openai_vision.py# OpenAI Vision (opcional)
│   │   └── vision_tool.py       # Wrapper multi-OCR de conveniencia
│   ├── models.py                # Esquema Pydantic null-honesto (Albaran/AlbaranRaw)
│   ├── validators.py            # Guardrail determinista de coherencia de totales
│   ├── crew.py                  # Ensamblado del crew (agentes + tareas + LLM)
│   └── main.py                  # Punto de entrada (CLI)
├── tests/                       # Tests sin red (esquema y guardrail)
├── examples/check_ocr_tools.py  # Diagnóstico de los motores OCR
├── input/                       # Coloca aquí tus imágenes de albaranes
├── output/                      # Salidas generadas (ignoradas por git)
├── docs/                        # Guías (get-started, SDD, Claude Code)
├── specs/                       # Especificaciones (Spec-Driven Development)
├── .claude/  ·  .specify/  ·  CLAUDE.md   # Soporte para Claude Code + SDD
├── .env.example
├── pyproject.toml
└── README.md

---

1. Requisitos previos

| Requisito | Detalle | | --- | --- | | Python | >=3.10,<3.14 | | Gestor de paquetes | uv (recomendado) o pip | | Clave de OpenAI | OPENAI_API_KEY (los agentes usan modelos OpenAI por defecto) | | Tesseract (opcional) | Binario del SO para el motor Tesseract | | Ollama (opcional) | Servicio local + modelo de visión para el motor Ollama |

Dependencias de sistema por motor OCR (todas opcionales: si falta una, ese motor se omite con un mensaje controlado y el resto del pipeline continúa):

• Tesseract: Windows · sudo apt-get install tesseract-ocr tesseract-ocr-spa (Linux) · brew install tesseract tesseract-lang (macOS).
• Ollama: instala Ollama y descarga un modelo de visión: ollama pull llama3.2-vision.
• EasyOCR / PaddleOCR: descargan sus pesos automáticamente en la primera ejecución.

2. Instalación paso a paso

Opción A — con uv (recomendado):

# 1. Clona el repositorio y entra en la carpeta
git clone <url-del-repo> crewai-vision-tool
cd crewai-vision-tool

# 2. Crea el entorno e instala dependencias (incluye el grupo de desarrollo)
uv sync

Opción B — con pip y venv:

python -m venv .venv
# Windows:        .venv\Scripts\activate
# Linux/macOS:    source .venv/bin/activate
pip install -e .

La primera ejecución puede tardar: EasyOCR/PaddleOCR descargan sus pesos y CrewAI resuelve dependencias pesadas.

3. Configuración (.env)

# Copia la plantilla
copy .env.example .env     # Windows
cp .env.example .env       # Linux/macOS

Edita .env y rellena al menos tu clave:

OPENAI_API_KEY=sk-...            # obligatorio
# IMAGE_URL=input/mi_albaran.jpg # opcional: imagen por defecto
# OLLAMA_HOST=http://localhost:11434  # opcional

El fichero .env contiene secretos y está en .gitignore. No lo subas al repositorio.

4. Primer uso (quickstart)

# 1. Coloca una imagen de albarán en input/, p. ej. input/mi_albaran.jpg

# 2. Ejecuta el crew sobre esa imagen
uv run python -m crewai_vision_tool.main input/mi_albaran.jpg

# 3. Revisa las dos salidas
#    output/document_final.json   -> albarán estructurado
#    output/validation_report.md  -> reporte de validación

Atajos equivalentes:

crewai run                                  # usa IMAGE_URL del .env o la imagen por defecto
python -m crewai_vision_tool.main           # idem, sin uv

5. Uso avanzado

Procesar una imagen concreta (primer argumento de línea de comandos):

uv run python -m crewai_vision_tool.main input/otro_albaran.png

Uso programático desde Python:

from crewai_vision_tool.crew import CrewaiVisionToolCrew

result = CrewaiVisionToolCrew().crew().kickoff(
    inputs={"image_url": "input/mi_albaran.jpg"}
)

# El JSON consolidado se persiste en output/document_final.json.
# result.raw contiene el reporte Markdown (última tarea del pipeline).
print(result.raw)

Diagnóstico de los motores OCR (comprueba qué motores están operativos):

uv run python examples/check_ocr_tools.py input/mi_albaran.jpg

---

Salidas generadas

Todas las salidas se escriben en output/ (ignorado por git):

| Archivo | Contenido | | --- | --- | | extracted_text_{ollama,tesseract,easyocr}.txt | Texto crudo extraído por cada motor | | albaran_analysis_{ollama,tesseract,easyocr}.json | JSON AlbaranRaw por motor (sin confidence) | | document_final.json | Albarán consolidado y validado (Albaran) | | validation_report.md | Reporte de discrepancias, decisiones y confianza |

Esquema de datos (Albaran)

El esquema vive en models.py y sigue una política null-honesta (principio P3 del proyecto):

• Siempre presentes: la lista items (puede estar vacía) y document_info.type (constante "albarán").
• Todo lo demás es opcional y vale null cuando el dato está ausente o es ilegible. Nunca se inventan valores.

Dos modelos por etapa:

• AlbaranRaw (fase de análisis): sin confidence por ítem.
• Albaran (documento final): añade confidence por ítem (alto / medio / bajo), asignado durante la consolidación.

Estructura resumida:

Albaran
├── document_info  { type, number, date, company, nif }
├── client         { name, nif, address, contact }
├── items[]        { sku, description, quantity, unit_price, base, total_price, confidence }
├── totals         { subtotal, base_total, tax, total }
├── delivery       { date, location, conditions }
└── notes

Guardrail de coherencia (validators.py): durante la consolidación se comprueba que Σ items.total_price ≈ totals.subtotal (tolerancia del 1%). Si no cuadra, se refleja la discrepancia en el reporte sin fabricar el total.

Modelos LLM y coste

Los modelos se asignan por rol para equilibrar rendimiento y coste. Se configuran en config/agents.yaml; la temperatura y el reasoning_effort se fijan en crew.py (el YAML solo admite el nombre del modelo como cadena).

| Rol | Modelo por defecto | Por qué | | --- | --- | --- | | Extractores OCR | openai/gpt-5.4-mini | Orquestan la herramienta OCR: rápido y barato | | Analista / Validador | openai/gpt-5.5 (temperature=0.2, reasoning_effort="medium") | Razonamiento y salida estructurada fiable |

Para abaratar, usa openai/gpt-5.4-mini en todos los agentes. Para máxima capacidad, sube el analista/validador a openai/gpt-5.5-pro.

Tests y verificación

Los tests no requieren red ni claves (solo Pydantic), porque el esquema y el guardrail están desacoplados de CrewAI:

# Tests del esquema null-honesto y del guardrail de coherencia
uv run pytest

# Verificación de sintaxis (barata, sin dependencias)
python -m compileall src

El smoke test real (crewai run sobre una imagen) requiere OPENAI_API_KEY y, opcionalmente, Tesseract/Ollama; no se ejecuta en la suite automática.

Solución de problemas

| Síntoma | Solución | | --- | --- | | OPENAI_API_KEY no configurada | Copia .env.example a .env y añade tu clave | | Tesseract not found | Instala el binario del SO y verifica que está en el PATH | | Ollama no responde | Inicia el servicio (ollama serve) y descarga el modelo (ollama pull llama3.2-vision) | | PaddleOCR falla al instalar | Es opcional; el crew no lo usa por defecto | | La primera ejecución es muy lenta | Normal: descarga de pesos OCR y resolución de dependencias |

Desarrollo (Claude Code + SDD)

El repositorio está preparado para Spec-Driven Development con Claude Code:

• CLAUDE.md — reglas persistentes y comandos clave.
• .claude/ — reglas por ruta (rules/), workflows (skills/), subagents (agents/) y hooks de validación (settings.json + hooks/).
• .specify/ — constitución del proyecto y plantillas SDD.
• specs/ — especificaciones; consulta el catálogo en specs/README.md.

El flujo es spec → plan → tasks → implementación → validación. Empieza por docs/get-started.md y, para el detalle, docs/sdd-workflow.md.

Además incluye el pack oficial de CrewAI Skills en .claude/skills/ (diseño de agentes/tareas, scaffolding y consulta de docs). Para reinstalarlo:

npx skills add crewaiinc/skills --agent claude-code

Licencia

Distribuido bajo licencia MIT.