Skip to main content

​
Quick Start Guide

This guide will walk you through your first inventory analysis in just a few minutes. By the end, you’ll have processed inventory data, generated reports, and understood the system’s outputs.

​
Prerequisites

Before starting, make sure you’ve completed the installation steps and have Python 3 and all dependencies installed.

​
Step-by-Step Tutorial

1

Create Sample Inventory Data

Create a file named inventario.xlsx in the data/ directory with the following structure:
productostock_actualstock_minimoventas_mensuales
Laptop HP151045
Mouse Logitech82060
Teclado Mecánico251530
Monitor Samsung51240
Cable HDMI503025
Auriculares Sony121035
These four columns are required: producto, stock_actual, stock_minimo, and ventas_mensuales. The system will fail if any column is missing.
2

Run the System

Execute the main script from the project root:
python src/main.py
You should see output similar to:
✅ Inventario cargado correctamente
✅ Clasificación ABC aplicada
✅ Riesgo evaluado y reposición recomendada
✅ Reporte Excel generado en output/reporte_inventario.xlsx
✅ Gráficos generados correctamente
⚠️ Envío de correo omitido (credenciales no configuradas)
If you see all checkmarks, the system ran successfully! The warning about email is expected if you haven’t configured email credentials yet.
3

Review the Excel Report

Open output/reporte_inventario.xlsx to see the generated report with three sheets:
  • Inventario_Completo: Full inventory with ABC classification and stock status
  • Productos_Criticos: Products with CRÍTICO status (immediate attention needed)
  • Productos_En_Riesgo: Products with RIESGO status (monitor closely)
4

View the Generated Charts

Check the output/graficos/ directory for two PNG files:
  • estado_inventario.png: Bar chart showing distribution of OK/RIESGO/CRÍTICO products
  • clasificacion_abc.png: Pie chart showing A/B/C category distribution
5

Understand the Results

Review the classification and recommendations for each product:Example Analysis:
  • Mouse Logitech: CRÍTICO (8 ≤ 20 minimum) → Reorder 52 units
  • Monitor Samsung: CRÍTICO (5 ≤ 12 minimum) → Reorder 35 units
  • Laptop HP: OK (15 > 10 minimum) → No action needed

​
Understanding the Business Logic

The system applies two key analyses to your inventory:

​
ABC Classification

Products are categorized by their contribution to total sales (from analisis.py:20-26):
  • Category A: Top 70% of cumulative sales (high-value products)
  • Category B: Next 20% (70-90% cumulative sales)
  • Category C: Remaining 10% (low-value products)
In our example:
  • Laptop HP (45 sales), Mouse Logitech (60 sales), Monitor Samsung (40 sales) → Likely Category A
  • Other products → Categories B or C

​
Stock Status Evaluation

Each product receives a status based on current stock vs. minimum threshold (from decisiones.py:11-17):
  • OK: stock_actual > stock_minimo × 1.2 (healthy buffer)
  • RIESGO: stock_minimo < stock_actual ≤ stock_minimo × 1.2 (approaching minimum)
  • CRÍTICO: stock_actual ≤ stock_minimo (below minimum, immediate action required)

​
Reorder Calculation

For products in CRÍTICO or RIESGO status, the system recommends (from decisiones.py:22-25): 
reponer_cantidad = max(ventas_mensuales - stock_actual, 0)
Example: Mouse Logitech has 8 units in stock and 60 monthly sales → Reorder 52 units.

​
Real-World Example

Using the sample data above:
ProductStatusReasonAction
Mouse LogitechCRÍTICO8 ≤ 20 (below minimum)Reorder 52 units immediately
Monitor SamsungCRÍTICO5 ≤ 12 (below minimum)Reorder 35 units immediately
Teclado MecánicoOK25 > 15 × 1.2 = 18 (healthy buffer)No action needed
Auriculares SonyRIESGO10 < 12 ≤ 12 × 1.2 = 14.4 (approaching minimum)Monitor closely, may need 23 units

​
Common Issues

Create the data/ directory in your project root and place your inventory Excel file there. The system looks for data/inventario.xlsx by default (configured in main.py:9).
Your Excel file must have these exact column names: producto, stock_actual, stock_minimo, ventas_mensuales. Check for typos or missing columns.
This is expected if you haven’t configured email credentials. See the email setup guide to enable automated email delivery.
Check the console for error messages. The system creates output/ and output/graficos/ directories automatically, but it needs write permissions in your project folder.

​
Next Steps

Configure Email

Set up automated email delivery for your reports

Customize Output

Adjust file paths and system settings

Understand ABC Classification

Learn the methodology behind product categorization

Extend the System

Add custom features and integrate with other tools
Pro Tip: Run the system on a schedule (e.g., daily at 8 AM) using cron (Linux/Mac) or Task Scheduler (Windows) to automate your inventory monitoring completely. See Running the System for details.

Build docs developers (and LLMs) love

Get started for freeTalk to us