added

Author: mikenieva

.github/workflows/test.yml

@@ -0,0 +1,30 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+      
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+      
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest
+          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+      
+      - name: Run tests
+        run: |
+          pytest tests/ -v --tb=short

.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+venv/
+env/
+ENV/
+build/
+dist/
+*.egg-info/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Pytest
+.pytest_cache/
+.coverage
+htmlcov/

.python-version

@@ -0,0 +1 @@
+3.12.7

README.md

@@ -0,0 +1,81 @@
+# AI Engineering - Week 1: RAG Fundamentals
+
+## 📋 Objetivo del Proyecto
+Implementar un sistema básico de RAG (Retrieval-Augmented Generation) usando embeddings y búsqueda semántica.
+
+## 🚀 Instrucciones
+
+### 1. Fork este repositorio
+Haz click en "Fork" arriba a la derecha para crear tu propia copia.
+
+### 2. Clona tu fork
+```bash
+git clone https://github.com/TU-USUARIO/mb-python-week-01-test.git
+cd mb-python-week-01-test
+```
+
+### 3. Crea y activa virtual environment
+```bash
+python3 -m venv venv
+source venv/bin/activate  # En Windows: venv\Scripts\activate
+```
+
+### 4. Instala dependencias
+```bash
+pip install -r requirements.txt
+```
+
+### 5. Completa el código
+Implementa las funciones en `src/main.py` siguiendo los comentarios.
+
+### 6. Prueba localmente
+```bash
+pytest tests/ -v
+```
+
+Todos los tests deben pasar (✅ 10 passed).
+
+### 7. Push y verifica
+```bash
+git add .
+git commit -m "Completar proyecto week 1"
+git push origin main
+```
+
+GitHub Actions correrá los tests automáticamente. Verifica que todos pasen (✅ green check).
+
+### 8. Envía en la plataforma
+Copia la URL de tu repo y pégala en la plataforma de Nieva AI para verificación automática.
+
+## ✅ Criterios de Aprobación
+- ✅ Todos los tests deben pasar (100%)
+- ✅ El código debe estar bien documentado
+- ✅ Debe ser un fork de este template oficial
+
+## 🧪 Tests Incluidos
+
+### `calculate_cosine_similarity`
+- Vectores idénticos → similitud 1.0
+- Vectores ortogonales → similitud 0.0
+- Vectores opuestos → similitud -1.0
+- Test con similitud conocida
+
+### `find_most_similar`
+- Encuentra documento idéntico
+- Encuentra documento más cercano
+- Maneja un solo documento
+
+### `retrieve_top_k`
+- Retorna top 3 documentos en orden
+- Maneja k > número de documentos
+- k=1 se comporta como find_most_similar
+
+## 📚 Recursos
+- [NumPy Documentation](https://numpy.org/doc/)
+- [Cosine Similarity Explained](https://en.wikipedia.org/wiki/Cosine_similarity)
+- [RAG Introduction](https://docs.anthropic.com/claude/docs/retrieval-augmented-generation)
+
+---
+
+**¿Tienes dudas?** Únete al Discord de Nieva AI.
+

requirements.txt

@@ -0,0 +1,2 @@
+pytest
+numpy

setup.py

@@ -0,0 +1,12 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="ai-engineering-week-1",
+    version="1.0.0",
+    packages=find_packages(),
+    install_requires=[
+        "pytest",
+        "numpy",
+    ],
+)
+

src/__init__.py

@@ -0,0 +1,82 @@
+"""
+AI Engineering - Week 1: RAG Fundamentals
+Implementa las funciones siguientes para completar el proyecto.
+"""
+
+import numpy as np
+from typing import List, Tuple
+
+
+def calculate_cosine_similarity(vec1: np.ndarray, vec2: np.ndarray) -> float:
+    """
+    Calcula la similitud coseno entre dos vectores.
+    
+    Args:
+        vec1: Primer vector (numpy array)
+        vec2: Segundo vector (numpy array)
+    
+    Returns:
+        float: Similitud coseno (entre -1 y 1)
+    
+    Ejemplo:
+        >>> vec1 = np.array([1, 2, 3])
+        >>> vec2 = np.array([4, 5, 6])
+        >>> calculate_cosine_similarity(vec1, vec2)
+        0.9746318461970762
+    """
+    # TODO: Implementa el cálculo de similitud coseno
+    # Fórmula: (vec1 · vec2) / (||vec1|| * ||vec2||)
+    
+    raise NotImplementedError("Implementa esta función")
+
+
+def find_most_similar(
+    query_embedding: np.ndarray,
+    document_embeddings: List[np.ndarray]
+) -> int:
+    """
+    Encuentra el índice del documento más similar a la query.
+    
+    Args:
+        query_embedding: Embedding de la consulta
+        document_embeddings: Lista de embeddings de documentos
+    
+    Returns:
+        int: Índice del documento más similar
+    
+    Ejemplo:
+        >>> query = np.array([1, 0, 0])
+        >>> docs = [np.array([0, 1, 0]), np.array([1, 0, 0]), np.array([0, 0, 1])]
+        >>> find_most_similar(query, docs)
+        1
+    """
+    # TODO: Encuentra el documento con mayor similitud coseno
+    
+    raise NotImplementedError("Implementa esta función")
+
+
+def retrieve_top_k(
+    query_embedding: np.ndarray,
+    document_embeddings: List[np.ndarray],
+    k: int = 3
+) -> List[int]:
+    """
+    Recupera los k documentos más similares.
+    
+    Args:
+        query_embedding: Embedding de la consulta
+        document_embeddings: Lista de embeddings de documentos
+        k: Número de documentos a recuperar
+    
+    Returns:
+        List[int]: Índices de los k documentos más similares (ordenados)
+    
+    Ejemplo:
+        >>> query = np.array([1, 0, 0])
+        >>> docs = [np.array([0, 1, 0]), np.array([1, 0, 0]), np.array([0.9, 0.1, 0])]
+        >>> retrieve_top_k(query, docs, k=2)
+        [1, 2]
+    """
+    # TODO: Encuentra los top k documentos más similares
+    
+    raise NotImplementedError("Implementa esta función")

src/main.py

@@ -0,0 +1,123 @@
+"""
+Tests para Week 1: RAG Fundamentals
+NO MODIFIQUES ESTE ARCHIVO
+"""
+
+import pytest
+import numpy as np
+from src.main import (
+    calculate_cosine_similarity,
+    find_most_similar,
+    retrieve_top_k
+)
+
+
+class TestCosineSimilarity:
+    """Tests para calculate_cosine_similarity"""
+    
+    def test_identical_vectors(self):
+        """Vectores idénticos deben tener similitud 1.0"""
+        vec = np.array([1, 2, 3])
+        similarity = calculate_cosine_similarity(vec, vec)
+        assert np.isclose(similarity, 1.0), "Vectores idénticos deben tener similitud 1.0"
+    
+    def test_orthogonal_vectors(self):
+        """Vectores ortogonales deben tener similitud 0.0"""
+        vec1 = np.array([1, 0, 0])
+        vec2 = np.array([0, 1, 0])
+        similarity = calculate_cosine_similarity(vec1, vec2)
+        assert np.isclose(similarity, 0.0), "Vectores ortogonales deben tener similitud 0.0"
+    
+    def test_opposite_vectors(self):
+        """Vectores opuestos deben tener similitud -1.0"""
+        vec1 = np.array([1, 2, 3])
+        vec2 = np.array([-1, -2, -3])
+        similarity = calculate_cosine_similarity(vec1, vec2)
+        assert np.isclose(similarity, -1.0), "Vectores opuestos deben tener similitud -1.0"
+    
+    def test_known_similarity(self):
+        """Test con similitud conocida"""
+        vec1 = np.array([1, 2, 3])
+        vec2 = np.array([4, 5, 6])
+        similarity = calculate_cosine_similarity(vec1, vec2)
+        expected = 0.9746318461970762
+        assert np.isclose(similarity, expected), f"Esperado {expected}, obtenido {similarity}"
+
+
+class TestFindMostSimilar:
+    """Tests para find_most_similar"""
+    
+    def test_exact_match(self):
+        """Debe encontrar el documento idéntico"""
+        query = np.array([1, 0, 0])
+        docs = [
+            np.array([0, 1, 0]),
+            np.array([1, 0, 0]),  # Exacto
+            np.array([0, 0, 1])
+        ]
+        result = find_most_similar(query, docs)
+        assert result == 1, "Debe encontrar el documento idéntico (índice 1)"
+    
+    def test_closest_match(self):
+        """Debe encontrar el documento más cercano"""
+        query = np.array([1, 0, 0])
+        docs = [
+            np.array([0, 1, 0]),
+            np.array([0.5, 0.5, 0]),
+            np.array([0.9, 0.1, 0])  # Más cercano
+        ]
+        result = find_most_similar(query, docs)
+        assert result == 2, "Debe encontrar el documento más cercano (índice 2)"
+    
+    def test_single_document(self):
+        """Con un solo documento, debe retornar índice 0"""
+        query = np.array([1, 2, 3])
+        docs = [np.array([4, 5, 6])]
+        result = find_most_similar(query, docs)
+        assert result == 0, "Con un solo documento debe retornar 0"
+
+
+class TestRetrieveTopK:
+    """Tests para retrieve_top_k"""
+    
+    def test_top_3(self):
+        """Debe retornar los top 3 documentos en orden"""
+        query = np.array([1, 0, 0])
+        docs = [
+            np.array([0, 1, 0]),      # Menos similar
+            np.array([1, 0, 0]),      # Más similar (índice 1)
+            np.array([0.9, 0.1, 0]),  # 2do más similar (índice 2)
+            np.array([0.8, 0.2, 0]),  # 3ro más similar (índice 3)
+            np.array([0, 0, 1])       # Menos similar
+        ]
+        result = retrieve_top_k(query, docs, k=3)
+        assert len(result) == 3, "Debe retornar exactamente 3 documentos"
+        assert result[0] == 1, "El más similar debe ser índice 1"
+        assert result[1] == 2, "El 2do debe ser índice 2"
+        assert result[2] == 3, "El 3ro debe ser índice 3"
+    
+    def test_k_larger_than_docs(self):
+        """Si k > número de docs, retorna todos los docs"""
+        query = np.array([1, 0, 0])
+        docs = [
+            np.array([1, 0, 0]),
+            np.array([0, 1, 0])
+        ]
+        result = retrieve_top_k(query, docs, k=5)
+        assert len(result) == 2, "Debe retornar todos los documentos disponibles"
+    
+    def test_k_equals_1(self):
+        """Con k=1 debe comportarse como find_most_similar"""
+        query = np.array([1, 0, 0])
+        docs = [
+            np.array([0, 1, 0]),
+            np.array([1, 0, 0]),
+            np.array([0, 0, 1])
+        ]
+        result = retrieve_top_k(query, docs, k=1)
+        assert len(result) == 1, "Debe retornar exactamente 1 documento"
+        assert result[0] == 1, "Debe ser el documento más similar (índice 1)"
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])