@saulwade/swl-ses 1.0.0

package/habilidades/langchain-langraph/recursos/vectorstores.md

@@ -0,0 +1,306 @@
+# Vector Stores — Referencia completa
+
+Guía de selección, configuración e integración de vector stores para aplicaciones RAG.
+
+---
+
+## Comparativa de vector stores
+
+| Vector Store | Despliegue | Escala | Búsqueda híbrida | Ideal para |
+|-------------|-----------|--------|-----------------|-----------|
+| pgvector | On-premise / Cloud | < 10M vectores | Manual (RRF) | Ya tienes PostgreSQL |
+| Chroma | Local / Self-hosted | < 1M vectores | No | Prototipado rápido |
+| Pinecone | Serverless | Sin límite práctico | Sí (nativo) | Producción sin DevOps |
+| Weaviate | Self-hosted / Cloud | Millones | Sí (BM25 + vector) | Búsqueda semántica avanzada |
+| Qdrant | Self-hosted / Cloud | Millones | Sí | Alta performance, tipado fuerte |
+
+---
+
+## pgvector con SQLAlchemy
+
+### Instalación y configuración
+
+```bash
+# Extensión PostgreSQL
+CREATE EXTENSION IF NOT EXISTS vector;
+
+# Dependencias Python
+pip install pgvector psycopg2-binary langchain-community
+```
+
+### Modelo SQLAlchemy con columna vector
+
+```python
+from pgvector.sqlalchemy import Vector
+from sqlalchemy import Column, String, Text, Integer
+from sqlalchemy.orm import DeclarativeBase
+
+class Base(DeclarativeBase):
+    pass
+
+class DocumentoChunk(Base):
+    __tablename__ = "documento_chunks"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    contenido = Column(Text, nullable=False)
+    fuente = Column(String(500))
+    pagina = Column(Integer)
+    # 1536 dimensiones para text-embedding-3-small de OpenAI
+    # 768 para all-MiniLM-L6-v2 de HuggingFace
+    embedding = Column(Vector(1536))
+```
+
+### Índice HNSW — obligatorio para producción
+
+```sql
+-- Crear índice HNSW DESPUÉS de cargar los datos iniciales
+-- m=16, ef_construction=64 son valores seguros para empezar
+CREATE INDEX idx_chunks_embedding_hnsw
+ON documento_chunks
+USING hnsw (embedding vector_cosine_ops)
+WITH (m = 16, ef_construction = 64);
+
+-- Para distancia euclidiana
+CREATE INDEX idx_chunks_embedding_euclidean
+ON documento_chunks
+USING hnsw (embedding vector_l2_ops)
+WITH (m = 16, ef_construction = 64);
+```
+
+**Por qué HNSW y no IVFFlat**: HNSW tiene mejor performance en queries individuales
+y no requiere pre-entrenamiento con `lists`. IVFFlat es mejor si el dataset es enorme
+(> 10M) y hay tiempo para el clustering inicial.
+
+### Consultas de similitud con LangChain
+
+```python
+from langchain_community.vectorstores import PGVector
+from langchain_openai import OpenAIEmbeddings
+
+embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
+
+# Crear o conectar a store existente
+vectorstore = PGVector(
+    embeddings=embeddings,
+    collection_name="documentos_empresa",
+    connection=DATABASE_URL,  # postgresql+psycopg2://...
+)
+
+# Búsqueda semántica simple
+docs = vectorstore.similarity_search("política de vacaciones", k=4)
+
+# Búsqueda con score de relevancia (1.0 = idéntico, 0.0 = sin relación)
+docs_con_score = vectorstore.similarity_search_with_score("política de vacaciones", k=4)
+for doc, score in docs_con_score:
+    print(f"Score: {score:.3f} | {doc.page_content[:100]}")
+
+# Búsqueda con filtro de metadata
+docs_filtrados = vectorstore.similarity_search(
+    "instrucciones de seguridad",
+    k=4,
+    filter={"fuente": "manual_seguridad_2024.pdf"},
+)
+```
+
+### Búsqueda híbrida manual con pgvector
+
+```sql
+-- Combinar búsqueda vectorial + full-text search con Reciprocal Rank Fusion (RRF)
+WITH vectorial AS (
+    SELECT id, contenido, fuente,
+           1 - (embedding <=> $1::vector) AS score_vector,
+           ROW_NUMBER() OVER (ORDER BY embedding <=> $1::vector) AS rank_vector
+    FROM documento_chunks
+    ORDER BY embedding <=> $1::vector
+    LIMIT 20
+),
+textual AS (
+    SELECT id, contenido, fuente,
+           ts_rank(to_tsvector('spanish', contenido), plainto_tsquery('spanish', $2)) AS score_texto,
+           ROW_NUMBER() OVER (ORDER BY ts_rank(to_tsvector('spanish', contenido), plainto_tsquery('spanish', $2)) DESC) AS rank_texto
+    FROM documento_chunks
+    WHERE to_tsvector('spanish', contenido) @@ plainto_tsquery('spanish', $2)
+    LIMIT 20
+)
+SELECT
+    COALESCE(v.id, t.id) AS id,
+    COALESCE(v.contenido, t.contenido) AS contenido,
+    -- RRF score: 1/(k + rank) donde k=60 es estándar
+    COALESCE(1.0 / (60 + v.rank_vector), 0) + COALESCE(1.0 / (60 + t.rank_texto), 0) AS score_rrf
+FROM vectorial v
+FULL OUTER JOIN textual t ON v.id = t.id
+ORDER BY score_rrf DESC
+LIMIT 5;
+```
+
+---
+
+## Chroma — uso local
+
+```python
+import chromadb
+from langchain_community.vectorstores import Chroma
+from langchain_openai import OpenAIEmbeddings
+
+# Persistente en disco (desarrollo)
+cliente = chromadb.PersistentClient(path="./chroma_db")
+
+vectorstore = Chroma(
+    client=cliente,
+    collection_name="documentos",
+    embedding_function=OpenAIEmbeddings(),
+)
+
+# Agregar documentos
+vectorstore.add_documents(chunks)
+
+# Buscar
+docs = vectorstore.similarity_search("consulta", k=4)
+```
+
+**Limitaciones de Chroma**: no tiene transacciones ACID, rendimiento degrada con
+colecciones > 500k vectores, no tiene búsqueda híbrida nativa. Usar solo en desarrollo.
+
+---
+
+## Pinecone — serverless
+
+```python
+from pinecone import Pinecone
+from langchain_pinecone import PineconeVectorStore
+from langchain_openai import OpenAIEmbeddings
+
+# Inicializar cliente
+pc = Pinecone(api_key=settings.PINECONE_API_KEY)
+
+# Crear índice si no existe
+if "documentos" not in pc.list_indexes().names():
+    pc.create_index(
+        name="documentos",
+        dimension=1536,         # debe coincidir con el modelo de embedding
+        metric="cosine",
+        spec=ServerlessSpec(cloud="aws", region="us-east-1"),
+    )
+
+indice = pc.Index("documentos")
+vectorstore = PineconeVectorStore(index=indice, embedding=OpenAIEmbeddings())
+
+# Upsert con metadata
+vectorstore.add_documents(chunks)
+
+# Búsqueda con filtro de namespace
+docs = vectorstore.similarity_search(
+    "consulta",
+    k=4,
+    namespace="empresa-x",  # para multi-tenancy
+)
+```
+
+---
+
+## Weaviate — búsqueda híbrida
+
+```python
+import weaviate
+from langchain_weaviate.vectorstores import WeaviateVectorStore
+
+cliente_weaviate = weaviate.connect_to_local()  # o connect_to_weaviate_cloud(...)
+
+vectorstore = WeaviateVectorStore(
+    client=cliente_weaviate,
+    index_name="Documentos",
+    text_key="contenido",
+    embedding=OpenAIEmbeddings(),
+)
+
+# Búsqueda híbrida (combina BM25 + vector automáticamente)
+docs = vectorstore.similarity_search(
+    "consulta sobre vacaciones",
+    k=4,
+    search_type="hybrid",
+    alpha=0.5,  # 0 = solo BM25, 1 = solo vector, 0.5 = equilibrado
+)
+```
+
+---
+
+## Estrategia de actualización del vector store
+
+### Re-embedding completo — cuándo hacerlo
+
+- Cambio de modelo de embedding (dimensiones o distribución diferentes).
+- Cambio radical en la base de documentos (> 50% de contenido nuevo).
+- Degradación de métricas RAGAS detectada en evaluación periódica.
+
+### Actualización incremental — el caso más común
+
+```python
+import hashlib
+
+def hash_documento(contenido: str) -> str:
+    """Fingerprint del contenido para detectar cambios."""
+    return hashlib.sha256(contenido.encode()).hexdigest()
+
+async def sincronizar_documento(doc_id: str, contenido: str, vectorstore: PGVector):
+    """Solo re-embebede si el contenido cambió."""
+    hash_nuevo = hash_documento(contenido)
+
+    # Verificar hash almacenado en metadata
+    docs_existentes = vectorstore.similarity_search(
+        "", k=1, filter={"doc_id": doc_id}
+    )
+    if docs_existentes and docs_existentes[0].metadata.get("hash") == hash_nuevo:
+        return  # Sin cambios — omitir re-embedding
+
+    # Eliminar chunks anteriores del documento
+    vectorstore.delete(ids=obtener_ids_por_doc(doc_id))
+
+    # Re-embebeder y guardar
+    chunks_nuevos = splitter.split_text(contenido)
+    vectorstore.add_texts(
+        texts=chunks_nuevos,
+        metadatas=[{"doc_id": doc_id, "hash": hash_nuevo}] * len(chunks_nuevos),
+    )
+```
+
+---
+
+## Costos de embeddings — referencia de precios
+
+| Modelo | Proveedor | Costo / 1M tokens | Dimensiones | Notas |
+|--------|-----------|-------------------|-------------|-------|
+| text-embedding-3-small | OpenAI | $0.020 | 1536 | Mejor relación costo/calidad |
+| text-embedding-3-large | OpenAI | $0.130 | 3072 | Mayor precisión |
+| text-embedding-ada-002 | OpenAI | $0.100 | 1536 | Obsoleto — migrar a v3 |
+| voyage-3 | Anthropic | $0.060 | 1024 | Óptimo con Claude |
+| all-MiniLM-L6-v2 | HuggingFace | Gratis (local) | 384 | Sin costo de API |
+| nomic-embed-text | Ollama | Gratis (local) | 768 | 100% on-premise |
+
+```python
+def estimar_costo_corpus(rutas_pdf: list[str], modelo: str = "text-embedding-3-small") -> dict:
+    """Estima el costo antes de embeber un corpus completo."""
+    import tiktoken
+    from langchain_community.document_loaders import PyPDFLoader
+
+    enc = tiktoken.get_encoding("cl100k_base")
+    total_tokens = 0
+
+    for ruta in rutas_pdf:
+        loader = PyPDFLoader(ruta)
+        docs = loader.load()
+        for doc in docs:
+            total_tokens += len(enc.encode(doc.page_content))
+
+    precios = {
+        "text-embedding-3-small": 0.020,
+        "text-embedding-3-large": 0.130,
+        "voyage-3": 0.060,
+    }
+    costo_usd = total_tokens / 1_000_000 * precios.get(modelo, 0.020)
+
+    return {
+        "total_tokens": total_tokens,
+        "modelo": modelo,
+        "costo_estimado_usd": round(costo_usd, 4),
+    }
+```

package/habilidades/legacy-code-rescue/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: legacy-code-rescue
+description: >
+  Técnicas para trabajar con código heredado sin tests, siguiendo la metodología
+  de Michael Feathers ("Working Effectively with Legacy Code"). Cubre
+  identificación de seams, characterization tests para capturar comportamiento
+  real (no el deseado), patrones para introducir cambios sin romper
+  (sprout method, sprout class, wrap method, wrap class), técnicas para romper
+  dependencias problemáticas, y orden de prioridad cuando se hereda código
+  sin cobertura. Cargar cuando se herede código sin tests, cuando un módulo
+  crítico tenga cobertura <30%, o cuando se planee refactoring de un sistema
+  heredado.
+version: "1.0.0"
+evolved: false
+herramientasPermitidas: [Read]
+exclusiones:
+  - "No cargar para refactoring de código moderno con buena cobertura — si los tests existen y cubren el área a refactorear, basta con `tdd-workflow`. Este skill es específico para código sin red de seguridad."
+  - "No cargar para migración entre versiones de framework — usar `deprecacion-migracion`. Este skill cubre rescate de código heredado en general, no actualizaciones de stack."
+  - "No cargar para deprecación planificada de features — usar `deprecacion-migracion`. Este skill cubre el problema inverso: código que NO se quiere deprecar pero hay que cambiar con seguridad."
+  - "No cargar para optimización de rendimiento de código moderno — los patrones aquí (especialmente characterization tests) priorizan seguridad sobre velocidad. Si la prioridad es perf, usar `performance-baseline` y profilers."
+evolvable: true
+---
+
+# Legacy Code Rescue
+
+Adaptado de "Working Effectively with Legacy Code" (Michael Feathers, 2004).
+Definición operativa de Feathers: **legacy code es código sin tests**, sin
+importar su edad o calidad aparente.
+
+## Cuándo cargar
+
+- Se hereda un módulo crítico con cobertura <30% y hay que cambiarlo.
+- Se diagnostica un bug en código que nadie ha tocado en meses/años.
+- Se planea un refactor de un sistema sin red de seguridad de tests.
+- Se necesita agregar una feature en código que actualmente no se puede
+  testear de forma aislada.
+- Se reciben quejas tipo "tengo miedo de tocar X porque puede romper Y".
+
+## Cuándo NO cargar
+
+- El código tiene cobertura ≥80% y los tests pasan — usar `tdd-workflow`.
+- Se está migrando entre versiones de framework — usar `deprecacion-migracion`.
+- Se está deprecando una feature intencionalmente — usar `deprecacion-migracion`.
+- El objetivo es optimizar rendimiento — los patrones aquí priorizan seguridad
+  sobre velocidad; usar `performance-baseline` y profilers.
+
+## Directiva primaria
+
+**Antes de cambiar código heredado, capturar lo que hace**, no lo que se
+supone que debe hacer. El comportamiento actual (incluidos sus bugs) es
+la fuente de verdad — algún caller probablemente depende de cada peculiaridad.
+
+Orden estricto:
+1. **Caracterizar** el comportamiento actual con tests.
+2. **Romper dependencias** lo mínimo necesario para que los tests sean posibles.
+3. **Cambiar** el código.
+4. **Refactorizar** ya con red de seguridad.
+
+NO empezar refactorizando "porque el código está feo". Sin tests, cada cambio
+es una apuesta.
+
+---
+
+## Identificar seams (costuras)
+
+Un **seam** es un punto donde el comportamiento del programa puede cambiarse
+sin editar el código original. Los seams son la palanca para introducir
+tests sin romper nada.
+
+### Tipos de seams
+
+| Tipo | Cuándo aplica | Cómo se activa |
+|------|---------------|----------------|
+| **Object seam** | OOP con polimorfismo | Inyectar una subclase/mock que herede |
+| **Preprocessing seam** | C/C++ con `#define` | Macros o preprocesador |
+| **Link seam** | Lenguajes compilados con linker | Sustituir librería en build |
+| **Method seam** (Python/JS) | Lenguajes dinámicos | Monkeypatching, importlib |
+
+En Python/TypeScript modernos, el object seam es el predominante:
+inyectar dependencias en lugar de instanciarlas dentro del constructor.
+
+### Identificar seams en código existente
+
+Buscar:
+- `new SomeClass()` dentro de constructores → object seam latente al refactorizar.
+- Llamadas estáticas a clases globales → buscar wrappers o usar dependency injection.
+- Imports de módulos con efectos secundarios → candidato a method seam.
+- Funciones puras escondidas dentro de métodos largos → extraer es seam barato.
+
+---
+
+## Characterization tests — capturar el comportamiento real
+
+Un **characterization test** documenta lo que el código HACE, no lo que
+debería hacer. Son la red de seguridad mínima antes de cualquier cambio.
+
+### Receta
+
+1. Tomar el código y ejecutarlo con un input concreto.
+2. Capturar el output exacto (incluido errores, side effects, state final).
+3. Escribir un test que assert ese output específico.
+4. Repetir con varios inputs representativos: caso típico, edge cases
+   conocidos, inputs malformados, valores extremos.
+5. Cuando el test pasa, **es la verdad** — incluso si revela un bug.
+
+```python
+# Ejemplo: función legacy sin tests
+def calcular_descuento(precio, tipo_cliente):
+    # ... 80 líneas de if/else, redondeos extraños, edge cases ocultos
+    return total
+
+# Characterization test — captura el comportamiento ACTUAL
+def test_caracterizacion_descuento():
+    # Input típico
+    assert calcular_descuento(100, "VIP") == 85.0
+    # Edge case observado: tipo_cliente vacío
+    assert calcular_descuento(100, "") == 100.0
+    # Bug aparente, pero callers pueden depender de él
+    assert calcular_descuento(0, "VIP") == 0.0
+    # Negativos: el código devuelve negativos sin validar — documentarlo
+    assert calcular_descuento(-50, "VIP") == -42.5
+```
+
+### Reglas para characterization tests
+
+- **No "arreglar" bugs** mientras se caracteriza — eso viene después.
+- Si el comportamiento parece incorrecto, escribir un test que lo
+  documente Y abrir un ticket separado para discutir el cambio.
+- Apuntar a cubrir los flujos que se van a tocar — no toda la base de
+  código.
+- Tests rápidos > tests perfectos. Un test feo que corre es mejor que
+  uno elegante que no se escribió.
+
+---
+
+## Patrones para cambio seguro
+
+Cuando hay que agregar comportamiento sin tocar código existente.
+
+### Sprout Method
+
+Si necesitas lógica nueva dentro de un método legacy difícil de testear,
+**escribe la lógica nueva como método aparte** (con tests propios) y
+llámalo desde el método legacy.
+
+```python
+# Antes — quieres agregar validación al método legacy
+def procesar_orden(orden):
+    # 200 líneas legacy intocables
+    ...
+
+# Después — la nueva validación vive aparte y SÍ es testeable
+def procesar_orden(orden):
+    # 200 líneas legacy intocables
+    if not _validar_disponibilidad_inventario(orden):  # nuevo
+        return ResultadoOrden.fallo("sin stock")
+    ...
+
+def _validar_disponibilidad_inventario(orden):
+    """Nuevo método con tests propios (no toca el legacy)."""
+    return all(item.cantidad <= item.producto.stock for item in orden.items)
+```
+
+### Sprout Class
+
+Cuando la lógica nueva es suficientemente grande, va en una **clase nueva**
+en lugar de un método. Misma idea: lógica nueva con tests, llamada desde
+el legacy.
+
+### Wrap Method
+
+Si necesitas ejecutar algo ANTES o DESPUÉS de un método legacy, renombra
+el original a algo interno (`_procesar_orden_original`) y crea uno nuevo
+con la firma original que llame al wrap + el original.
+
+```python
+def procesar_orden(orden):  # firma pública intacta
+    _registrar_intento(orden)         # nueva pre-acción, testeable
+    resultado = _procesar_orden_original(orden)
+    _registrar_resultado(resultado)   # nueva post-acción, testeable
+    return resultado
+
+def _procesar_orden_original(orden):
+    # 200 líneas legacy intocables, ahora son privadas
+    ...
+```
+
+### Wrap Class
+
+Para wrap de un sistema más grande: una clase nueva con la misma interfaz
+delega al legacy y agrega comportamiento alrededor (decorator pattern).
+
+---
+
+## Romper dependencias
+
+Algunos legacy methods son intratables por dependencias:
+- Conexiones a BD/red en el constructor.
+- Singletons globales que se acceden en cualquier parte.
+- Llamadas a `time.now()`, `random()`, filesystem.
+
+Técnicas (en orden de invasividad creciente):
+
+1. **Subclass and Override Method**: hereda de la clase legacy, sobreescribe
+   el método problemático con un mock para los tests.
+2. **Extract Interface / Extract Class**: extrae una interfaz pequeña con
+   solo los métodos que el código usa, e inyecta una implementación de prueba.
+3. **Parameterize Method/Constructor**: inyecta como parámetro lo que antes
+   se obtenía globalmente (clock, random, IO).
+4. **Replace Function with Function Pointer / Strategy**: cambiar funciones
+   estáticas por callables inyectables.
+
+Aplicar la técnica MENOS invasiva que resuelva el problema. Cuanto más
+invasiva, más riesgo de romper algo durante el rescate.
+
+---
+
+## Anti-patrones
+
+- **Refactorizar antes de tener characterization tests**: cualquier cambio
+  estructural sin red de seguridad es una apuesta.
+- **"Mejorar" el comportamiento mientras se caracteriza**: si parece un
+  bug, documéntalo en un ticket y déjalo intacto en el characterization
+  test. Cambios funcionales van en commits separados con su propia revisión.
+- **Apuntar a 100% de cobertura del módulo entero**: el objetivo es
+  cubrir lo que se va a tocar. Cobertura completa puede tomar meses;
+  cubrir el slice de cambio toma horas.
+- **Borrar código "muerto" sin verificar**: en legacy, algo que parece
+  muerto puede ser invocado por reflection o cron. Buscar referencias
+  con `grep -r` antes de borrar.
+- **Sustituir "todo" con un mock**: si el test pasa solo porque mockeaste
+  todas las dependencias, ya no testea nada. Mockear solo lo necesario
+  para aislar el código bajo prueba.
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+- **Characterization test "perfecto" que se rompe en CI por orden no determinista**: el código legacy depende del orden de iteración de un dict (Python <3.7) o del timezone del servidor. Causa: comportamiento dependiente de entorno. Solución: capturar la dependencia (forzar timezone UTC en el test, ordenar collections antes de assert) y documentar la dependencia ambiental como bug a discutir.
+- **Sprout Method que sí toca el legacy "solo un poquito"**: el desarrollador agrega un `if condicion_nueva` dentro del legacy en lugar de extraer. Causa: parece más simple. Solución: si tocas el legacy, ya no es sprout; o caracterizas primero, o aplicas wrap method que NO modifica el cuerpo original.
+- **Inyectar dependencia con un default que llama al global**: `def __init__(self, db=None): self.db = db or get_global_db()`. Causa: querer mantener compatibilidad con callers viejos. Solución: el default escondido invalida la inyección — los tests acaban tocando el global. Aceptar que romper la firma es parte del rescate; agregar wrappers de compatibilidad fuera de la clase si es necesario.
+- **Cobertura como métrica engañosa**: 80% de cobertura de líneas pero los asserts solo verifican que "no lanza excepción". Causa: tests escritos para subir el número, no para capturar comportamiento. Solución: cada characterization test debe tener al menos un assert sobre el output o side effect concreto, no solo `assert resultado is not None`.
+- **Mock de la BD que devuelve datos perfectos donde el legacy maneja datos sucios**: el código legacy tiene defensas contra datos inconsistentes que el mock no reproduce. Causa: el mock idealiza la realidad. Solución: el mock debe reproducir la sucidad observada en producción (NULLs inesperados, encodings raros, duplicados) — caracterizar la entrada real es parte del rescate.
+
+## Orden de prioridad cuando se hereda código
+
+1. **Estabilizar**: identificar el módulo más crítico, escribir
+   characterization tests sobre los flujos que se van a tocar pronto.
+2. **Aislar**: romper dependencias problemáticas con seams para que el
+   módulo crítico pueda testearse en isolation.
+3. **Cubrir**: agregar tests sobre código nuevo (Sprout/Wrap) y sobre
+   regresiones detectadas.
+4. **Cambiar**: hacer el cambio funcional pedido, ya con red de seguridad.
+5. **Refactorizar**: mejorar la estructura ya que está cubierta. NO antes.
+
+NO refactorices código que no piensas tocar. La cobertura no es un fin
+en sí mismo — es palanca para cambios futuros.
+
+## Checklist antes de tocar código heredado
+
+- [ ] ¿Existen characterization tests sobre la zona de cambio?
+- [ ] Si no: ¿se escribieron antes de cualquier modificación?
+- [ ] ¿Las dependencias bloqueantes (DB, red, time, random) están aisladas?
+- [ ] ¿El cambio funcional va en un commit separado del refactor estructural?
+- [ ] ¿Se documentaron en tickets los bugs detectados durante la caracterización?
+- [ ] ¿La cobertura nueva es del slice tocado, no del módulo completo?
+- [ ] ¿El sprout/wrap se queda fuera del cuerpo legacy original?