🤝 Guía de Contribución - Agente de Mercadeo

¡Gracias por tu interés en contribuir al Agente de Mercadeo! Este documento te guiará a través del proceso de contribución para que puedas ayudar a mejorar este proyecto.

📋 Tabla de Contenidos

Código de Conducta
¿Cómo puedo contribuir?
Reportando Bugs
Sugiriendo Mejoras
Configurando el Entorno de Desarrollo
Proceso de Pull Request
Guías de Estilo
Estructura del Proyecto
Testing
Documentación

📜 Código de Conducta

Este proyecto adhiere a un código de conducta. Al participar, se espera que mantengas este código. Por favor reporta comportamientos inaceptables a través de los issues del proyecto.

Nuestros Compromisos

Respeto: Tratamos a todos con respeto, independientemente de su experiencia, identidad o perspectivas
Inclusión: Fomentamos un ambiente acogedor para personas de todos los backgrounds
Colaboración: Trabajamos juntos de manera constructiva y profesional
Aprendizaje: Valoramos el intercambio de conocimientos y el crecimiento mutuo

🚀 ¿Cómo puedo contribuir?

Hay muchas formas de contribuir al Agente de Mercadeo:

🐛 Reportando Bugs

Encuentra y reporta bugs a través de GitHub Issues
Proporciona información detallada sobre el problema
Incluye pasos para reproducir el error

💡 Sugiriendo Mejoras

Propón nuevas características o mejoras
Discute ideas antes de implementarlas
Considera el impacto en el rendimiento y usabilidad

💻 Contribuciones de Código

Mejoras en algoritmos de análisis financiero
Nuevas integraciones de APIs de datos reales
Optimizaciones de rendimiento
Corrección de bugs

📚 Mejoras en Documentación

Correcciones en README, guías de instalación
Nuevos ejemplos de uso
Tutoriales y guías de mejores prácticas
Traducciones

🧪 Testing

Escribir tests para nuevas funcionalidades
Mejorar cobertura de tests existentes
Tests de integración con APIs externas

🐛 Reportando Bugs

Antes de Crear un Issue

Busca issues existentes para evitar duplicados
Verifica la versión - asegúrate de usar la última versión
Reproduce el error en un entorno limpio

Template para Reportar Bugs

## 🐛 Descripción del Bug
Una descripción clara y concisa del bug.

## 🔄 Pasos para Reproducir
1. Ve a '...'
2. Ejecuta '...'
3. Observa el error

## ✅ Comportamiento Esperado
Descripción de lo que esperabas que ocurriera.

## 💻 Entorno
- OS: [e.g. Windows 11, macOS Ventura, Ubuntu 22.04]
- Python: [e.g. 3.11.2]
- Versión del Agente: [e.g. 1.0.0]
- APIs utilizadas: [e.g. OpenAI, Tavily]

## 📋 Información Adicional
- Logs relevantes
- Screenshots si aplica
- Configuración especial

💡 Sugiriendo Mejoras

Template para Feature Requests

## 🚀 Feature Request

### 📝 Descripción
Descripción clara de la mejora propuesta.

### 🎯 Problema que Resuelve
¿Qué problema específico resolvería esta mejora?

### 💭 Solución Propuesta
Descripción detallada de cómo implementarías esta mejora.

### 🎨 Alternativas Consideradas
Otras soluciones que consideraste.

### 📊 Impacto Esperado
- Usuarios beneficiados
- Mejora en rendimiento
- Valor agregado al proyecto

🛠️ Configurando el Entorno de Desarrollo

1. Requisitos Previos

# Python 3.11+
python --version

# Git
git --version

# uv (recomendado) o pip
uv --version

2. Fork y Clone

# Fork el repositorio en GitHub, luego:
git clone https://github.com/TU-USERNAME/agente-mercadeo.git
cd agente-mercadeo

# Agregar upstream remote
git remote add upstream https://github.com/ORIGINAL-OWNER/agente-mercadeo.git

3. Configurar Entorno Virtual

# Con uv (recomendado)
uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Instalar dependencias de desarrollo
uv pip install -e ".[dev]"

4. Configurar Variables de Entorno

# Copiar template
cp .env.example .env

# Editar con tus API keys
# Mínimo necesario para desarrollo:
OPENAI_API_KEY=sk-...
TAVILY_API_KEY=tvly-...

5. Verificar Instalación

# Ejecutar tests
pytest

# Ejecutar el servidor de desarrollo
uvx --refresh --from "langgraph-cli[inmem]" --with-editable . --python 3.11 langgraph dev --allow-blocking

🔄 Proceso de Pull Request

1. Crear Branch

# Sincronizar con upstream
git fetch upstream
git checkout main
git merge upstream/main

# Crear nueva branch
git checkout -b feature/nombre-descriptivo
# o
git checkout -b fix/descripcion-del-bug

2. Hacer Cambios

Sigue las guías de estilo
Escribe tests para nuevas funcionalidades
Actualiza documentación si es necesario
Asegúrate que todos los tests pasen

3. Commit Changes

# Staging
git add .

# Commit con mensaje descriptivo
git commit -m "feat: agregar análisis de mercado para sector tecnológico

- Implementar nuevos prompts especializados para startups tech
- Agregar métricas específicas de TAM/SAM para SaaS
- Incluir análisis de competencia para plataformas digitales

Fixes #123"

4. Push y Crear PR

# Push a tu fork
git push origin feature/nombre-descriptivo

# Crear Pull Request en GitHub
# Usar el template proporcionado

Template de Pull Request

## 📝 Descripción
Descripción clara de los cambios realizados.

## 🔗 Issue Relacionado
Fixes #123

## 🧪 Tipo de Cambio
- [ ] Bug fix (cambio que corrige un problema sin romper funcionalidad existente)
- [ ] Nueva funcionalidad (cambio que agrega funcionalidad sin romper la existente)
- [ ] Breaking change (fix o feature que haría que funcionalidad existente no funcione como antes)
- [ ] Documentación (cambios solo en documentación)

## ✅ Checklist
- [ ] Mi código sigue las guías de estilo del proyecto
- [ ] He realizado una auto-revisión de mi código
- [ ] He comentado mi código, particularmente en áreas difíciles de entender
- [ ] He hecho cambios correspondientes a la documentación
- [ ] Mis cambios no generan nuevas advertencias
- [ ] He agregado tests que prueban que mi fix es efectivo o que mi feature funciona
- [ ] Tests nuevos y existentes pasan localmente con mis cambios

## 🧪 Cómo se ha Probado
Describe las pruebas que ejecutaste para verificar tus cambios.

## 📸 Screenshots (si aplica)
Agrega screenshots para ayudar a explicar el problema o la solución.

🎨 Guías de Estilo

Código Python

Seguimos PEP 8 con algunas personalizaciones:

# ✅ Bueno
async def analyze_market_segment(
    product_service: str,
    target_region: str,
    config: RunnableConfig
) -> Dict[str, Any]:
    """
    Analyze market segment for specific product/service.
    
    Args:
        product_service: Product or service to analyze
        target_region: Geographic region for analysis
        config: Configuration for the analysis
        
    Returns:
        Dictionary with market analysis results
    """
    logger.info(f"Starting market analysis for {product_service} in {target_region}")
    
    # Implementation here
    return analysis_results

# ❌ Malo
def analyzeMarket(prod,reg):
    # no docstring, poor naming, no type hints
    return something

Mensajes de Commit

Seguimos Conventional Commits:

# Formato
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

# Ejemplos
feat: agregar análisis de competencia mejorado
fix: corregir error en cálculo de TAM/SAM
docs: actualizar guía de instalación
test: agregar tests para análisis financiero
refactor: optimizar llamadas a APIs externas

Tipos de Commit

feat: Nueva funcionalidad
fix: Corrección de bug
docs: Solo cambios en documentación
style: Cambios que no afectan el significado del código
refactor: Cambio de código que no corrige bug ni agrega feature
test: Agregar tests faltantes o corregir existentes
chore: Cambios en proceso de build o herramientas auxiliares

🏗️ Estructura del Proyecto

agente-mercadeo/
├── src/
│   ├── open_deep_research/      # Core del agente
│   │   ├── deep_researcher.py   # Lógica principal del agente
│   │   ├── utils.py             # Utilities y funciones de APIs
│   │   ├── prompts.py           # Prompts especializados
│   │   ├── state.py             # Definiciones de estado
│   │   └── configuration.py     # Configuración del sistema
│   ├── security/                # Autenticación y seguridad
│   │   └── auth.py              # Autenticación JWT con Supabase
│   └── legacy/                  # Código legacy para referencia
├── tests/                       # Tests automatizados
│   ├── unit/                    # Tests unitarios
│   ├── integration/             # Tests de integración
│   └── fixtures/                # Datos de prueba
├── examples/                    # Ejemplos de análisis
├── docs/                        # Documentación adicional
├── scripts/                     # Scripts de utilidad
└── .github/                     # GitHub workflows

Directrices para Cada Módulo

`src/open_deep_research/`

deep_researcher.py: Lógica principal, orquestación de agentes
utils.py: Funciones de APIs, cálculos financieros, utilidades
prompts.py: Todos los prompts del sistema, organizados por función
state.py: Definiciones de estado y modelos de datos
configuration.py: Configuración y validación de parámetros

`tests/`

Tests unitarios para cada función
Tests de integración para flujos completos
Mocks para APIs externas durante testing
Fixtures con datos de ejemplo

🧪 Testing

Ejecutar Tests

# Todos los tests
pytest

# Tests específicos
pytest tests/unit/test_utils.py

# Con cobertura
pytest --cov=src --cov-report=html

# Tests de integración (requiere API keys)
pytest tests/integration/ --api-keys

Escribir Tests

import pytest
from unittest.mock import AsyncMock, patch
from src.open_deep_research.utils import calculate_market_metrics

class TestMarketMetrics:
    """Test cases for market metrics calculations."""
    
    def test_calculate_tam_sam_som(self):
        """Test TAM/SAM/SOM calculation with valid inputs."""
        result = calculate_market_metrics(
            population=50_000_000,
            avg_price=100,
            frequency=12,
            penetration=10.0
        )
        
        assert result['tam'] == 60_000_000_000  # 50M * 100 * 12
        assert result['sam'] == 6_000_000_000   # TAM * 10%
        assert result['som'] == 300_000_000     # SAM * 5%
        
    @pytest.mark.asyncio
    async def test_get_real_exchange_rate(self):
        """Test real exchange rate API call."""
        with patch('aiohttp.ClientSession.get') as mock_get:
            mock_response = AsyncMock()
            mock_response.status = 200
            mock_response.json.return_value = {
                'rates': {'COP': 4000.0}
            }
            mock_get.return_value.__aenter__.return_value = mock_response
            
            from src.open_deep_research.utils import get_real_exchange_rate
            rate, source_info = await get_real_exchange_rate()
            
            assert rate == 4000.0
            assert source_info['success'] is True

Tipos de Tests

Unit Tests: Funciones individuales, lógica de negocio
Integration Tests: Flujos completos, APIs externas
Performance Tests: Tiempo de respuesta, uso de memoria
Security Tests: Validación de inputs, sanitización

📚 Documentación

Docstrings

Usa docstrings estilo Google:

def calculate_financial_projections(
    initial_customers: int,
    monthly_price: float,
    growth_rate: float,
    churn_rate: float = 5.0
) -> Dict[str, Any]:
    """
    Generate 3-year financial projections for a business.
    
    This function calculates customer growth, revenue projections,
    and key financial metrics for business planning.
    
    Args:
        initial_customers: Starting number of customers
        monthly_price: Monthly price per customer in local currency
        growth_rate: Monthly growth rate as percentage (e.g., 10.0 for 10%)
        churn_rate: Monthly churn rate as percentage, defaults to 5.0
        
    Returns:
        Dictionary containing:
            - projections: List of yearly projections
            - break_even_customers: Number of customers needed to break even
            
    Raises:
        ValueError: If any input parameter is negative or invalid
        
    Example:
        >>> projections = calculate_financial_projections(
        ...     initial_customers=100,
        ...     monthly_price=50.0,
        ...     growth_rate=15.0
        ... )
        >>> print(projections['projections'][0]['annual_revenue'])
        60000.0
    """

Comentarios en Código

# ✅ Bueno - Explica el "por qué"
# Use exponential backoff to handle rate limiting from World Bank API
await asyncio.sleep(2 ** attempt)

# ✅ Bueno - Explica lógica compleja
# Calculate SOM as 5% of SAM (conservative estimate based on 
# typical market penetration for new entrants in Colombian market)
som = sam * 0.05

# ❌ Malo - Explica el "qué" obvio
# Increment counter by 1
counter += 1

🚀 Roadmap de Contribuciones

🟢 Beginner Friendly

Corregir typos en documentación
Agregar ejemplos de uso
Mejorar mensajes de error
Escribir tests unitarios

🟡 Intermediate

Optimizar consultas a APIs externas
Implementar nuevas métricas financieras
Agregar soporte para nuevos países
Mejorar manejo de errores

🔴 Advanced

Implementar sistema de cache distribuido
Agregar soporte para APIs adicionales
Optimizaciones de rendimiento
Arquitectura de microservicios

🎯 Prioridades Actuales

Cache System: Implementar cache para respuestas de APIs
Error Handling: Mejorar robustez ante fallas de APIs
Export Formats: Soporte para PDF, Excel, PowerPoint
Sector Templates: Plantillas especializadas por industria
Multi-country: Expandir a México, Argentina, Chile

📞 Obtener Ayuda

Canales de Comunicación

GitHub Issues: Para bugs y feature requests
GitHub Discussions: Para preguntas generales y discusiones
Email: Para temas de seguridad o privados

Preguntas Frecuentes

Q: ¿Necesito API keys para contribuir? A: Para desarrollo básico no, pero para testing completo sí necesitas al menos OpenAI y Tavily.

Q: ¿Puedo contribuir sin conocer LangGraph? A: ¡Sí! Hay muchas áreas como documentación, tests, y utilidades que no requieren conocimiento específico de LangGraph.

Q: ¿Hay algún chat o Discord para discusiones? A: Por ahora utilizamos GitHub Discussions. Si el proyecto crece, consideraremos otros canales.

🙏 Reconocimientos

Agradecemos a todos los contributors que hacen posible este proyecto. Tu tiempo y esfuerzo son muy valorados.

Contributors

Tu nombre podría estar aquí 😊

¿Listo para contribuir? ¡Excelente! No dudes en abrir un issue si tienes preguntas o necesitas ayuda para empezar. ¡Esperamos tu pull request! 🚀

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

🤝 Guía de Contribución - Agente de Mercadeo

📋 Tabla de Contenidos

📜 Código de Conducta

Nuestros Compromisos

🚀 ¿Cómo puedo contribuir?

🐛 Reportando Bugs

💡 Sugiriendo Mejoras

💻 Contribuciones de Código

📚 Mejoras en Documentación

🧪 Testing

🐛 Reportando Bugs

Antes de Crear un Issue

Template para Reportar Bugs

💡 Sugiriendo Mejoras

Template para Feature Requests

🛠️ Configurando el Entorno de Desarrollo

1. Requisitos Previos

2. Fork y Clone

3. Configurar Entorno Virtual

4. Configurar Variables de Entorno

5. Verificar Instalación

🔄 Proceso de Pull Request

1. Crear Branch

2. Hacer Cambios

3. Commit Changes

4. Push y Crear PR

Template de Pull Request

🎨 Guías de Estilo

Código Python

Mensajes de Commit

Tipos de Commit

🏗️ Estructura del Proyecto

Directrices para Cada Módulo

src/open_deep_research/

tests/

🧪 Testing

Ejecutar Tests

Escribir Tests

Tipos de Tests

📚 Documentación

Docstrings

Comentarios en Código

🚀 Roadmap de Contribuciones

🟢 Beginner Friendly

🟡 Intermediate

🔴 Advanced

🎯 Prioridades Actuales

📞 Obtener Ayuda

Canales de Comunicación

Preguntas Frecuentes

🙏 Reconocimientos

Contributors

`src/open_deep_research/`

`tests/`