qagent-pytest 0.1.0__tar.gz

qagent_pytest-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Angel Mauricio Oncoy Patricio, Mateo Castillo Pezo,
+Rodrigo Rodríguez Malca y Adrián Sanchez Vargas (equipo QAgent)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qagent_pytest-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: qagent-pytest
+Version: 0.1.0
+Summary: Sistema multiagente que genera y valida pruebas pytest para código Python 3.10+
+Author: Equipo QAgent - Taller Integrador I (UPAO)
+License-Expression: MIT
+Project-URL: Repositorio, https://github.com/AngelOncoy/QAgent
+Project-URL: Problemas, https://github.com/AngelOncoy/QAgent/issues
+Keywords: pytest,testing,unit tests,llm,multi-agent,test generation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Spanish
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pywebview>=5.0.0
+Requires-Dist: docker>=7.1.0
+Requires-Dist: requests>=2.31
+Requires-Dist: jsonschema>=4.18
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Provides-Extra: empaquetar
+Requires-Dist: pyinstaller>=6.10; extra == "empaquetar"
+Dynamic: license-file
+
+# QAgent
+
+**Genera y valida automáticamente pruebas unitarias (pytest) para tu código Python, con un equipo de tres agentes de IA.**
+
+Abres tu proyecto, eliges qué probar y QAgent escribe las pruebas, las ejecuta en un entorno aislado y te entrega un informe con lo que pasó, lo que falló y por qué. No acepta pruebas «arregladas a la fuerza»: si una prueba solo pasa porque se le quitó o relajó una aserción, la rechaza.
+
+![Pantalla de inicio de QAgent](https://raw.githubusercontent.com/AngelOncoy/QAgent/develop/docs/imagenes/qagent-inicio.png)
+
+## Cómo funciona
+
+| Agente | Qué hace |
+|---|---|
+| **Planner** | Lee tu código (funciones, firmas, docstrings) y decide qué casos hay que probar. |
+| **Generator** | Escribe la prueba pytest de cada caso. |
+| **Reviewer** | La ejecuta en un contenedor Docker sin internet ni acceso a tus archivos, revisa que las aserciones sean legítimas y pide hasta 3 intentos de corrección. |
+
+Por cada prueba registra si pasó, la cobertura de líneas y ramas, cuántos intentos necesitó, los tokens que gastó cada agente y, en las funciones críticas, el Mutation Score.
+
+![Informe de una corrida](https://raw.githubusercontent.com/AngelOncoy/QAgent/develop/docs/imagenes/qagent-informe.png)
+
+## Instalación
+
+### Windows: instalador (recomendado)
+
+1. Descarga `QAgent-<versión>-instalador.exe` desde la [última versión publicada](https://github.com/AngelOncoy/QAgent/releases/latest).
+2. Ejecútalo. No necesita permisos de administrador ni tener Python instalado.
+3. Si Windows muestra «Windows protegió tu PC», elige **Más información → Ejecutar de todas formas** (el instalador aún no está firmado digitalmente).
+
+### Con pip (si ya usas Python 3.10 o superior)
+
+```bash
+pip install qagent-pytest
+qagent
+```
+
+En PyPI se llama `qagent-pytest` porque el nombre `qagent` ya lo usaba otro proyecto; el programa, el comando y la marca siguen siendo **QAgent**.
+
+## Antes de la primera corrida
+
+- **Docker Desktop**, abierto: las pruebas se ejecutan solo dentro de un contenedor aislado. La primera corrida prepara ese entorno sola (necesita internet y tarda unos minutos, una sola vez). [Descargar Docker Desktop](https://www.docker.com/products/docker-desktop/).
+- **Claves de API** de los modelos de IA: se agregan en la pantalla **Configuración** del programa, una por agente.
+- **Git**, si vas a abrir repositorios por su URL.
+
+¿Quieres probarlo sin claves ni costo? Agrega la línea `QAGENT_FAKE_LLM=1` al archivo `.env` de la carpeta `.qagent` de tu usuario (`C:\Users\<tú>\.qagent\.env`): QAgent usará una IA simulada con respuestas grabadas.
+
+Tus claves, tu configuración y la lista de proyectos recientes se guardan en esa carpeta `.qagent` de tu usuario, nunca junto al programa. Desinstalar QAgent no las borra.
+
+## Primeros pasos
+
+1. Abre **QAgent** desde el menú Inicio (o con el comando `qagent`).
+2. En **Configuración**, agrega la API de cada agente.
+3. En **Proyectos**, elige **Abrir proyecto** (una carpeta con código Python) o **Abrir repositorio** (una URL de Git).
+4. Revisa la **Vista previa**, elige el perfil en **Configuración de pruebas** e inicia la corrida.
+5. Sigue el avance en el **Monitor** y revisa el **Reporte final**; puedes exportarlo.
+
+## Alcance
+
+QAgent genera pruebas **unitarias** para código **Python 3.10+** y pruebas de endpoints FastAPI. Integración contra servicios reales, extremo a extremo, carga y estrés quedan fuera de esta versión.
+
+## Para el equipo de desarrollo
+
+Cómo preparar el entorno, ejecutar las pruebas, construir el instalador y publicar una versión: [`docs/desarrollo.md`](https://github.com/AngelOncoy/QAgent/blob/develop/docs/desarrollo.md). Las reglas del proyecto están en [`AGENTS.md`](https://github.com/AngelOncoy/QAgent/blob/develop/AGENTS.md) y las decisiones técnicas en [`docs/decisiones/`](https://github.com/AngelOncoy/QAgent/tree/develop/docs/decisiones).
+
+## Equipo
+
+Proyecto del curso Taller Integrador I, Ingeniería de Sistemas e Inteligencia Artificial, Universidad Privada Antenor Orrego (UPAO).
+
+Castillo Pezo, Mateo · Oncoy Patricio, Angel · Rodríguez Malca, Rodrigo · Sanchez Vargas, Adrián
+
+## Licencia
+
+[MIT](https://github.com/AngelOncoy/QAgent/blob/develop/LICENSE).

qagent_pytest-0.1.0/README.md

@@ -0,0 +1,72 @@
+# QAgent
+
+**Genera y valida automáticamente pruebas unitarias (pytest) para tu código Python, con un equipo de tres agentes de IA.**
+
+Abres tu proyecto, eliges qué probar y QAgent escribe las pruebas, las ejecuta en un entorno aislado y te entrega un informe con lo que pasó, lo que falló y por qué. No acepta pruebas «arregladas a la fuerza»: si una prueba solo pasa porque se le quitó o relajó una aserción, la rechaza.
+
+![Pantalla de inicio de QAgent](https://raw.githubusercontent.com/AngelOncoy/QAgent/develop/docs/imagenes/qagent-inicio.png)
+
+## Cómo funciona
+
+| Agente | Qué hace |
+|---|---|
+| **Planner** | Lee tu código (funciones, firmas, docstrings) y decide qué casos hay que probar. |
+| **Generator** | Escribe la prueba pytest de cada caso. |
+| **Reviewer** | La ejecuta en un contenedor Docker sin internet ni acceso a tus archivos, revisa que las aserciones sean legítimas y pide hasta 3 intentos de corrección. |
+
+Por cada prueba registra si pasó, la cobertura de líneas y ramas, cuántos intentos necesitó, los tokens que gastó cada agente y, en las funciones críticas, el Mutation Score.
+
+![Informe de una corrida](https://raw.githubusercontent.com/AngelOncoy/QAgent/develop/docs/imagenes/qagent-informe.png)
+
+## Instalación
+
+### Windows: instalador (recomendado)
+
+1. Descarga `QAgent-<versión>-instalador.exe` desde la [última versión publicada](https://github.com/AngelOncoy/QAgent/releases/latest).
+2. Ejecútalo. No necesita permisos de administrador ni tener Python instalado.
+3. Si Windows muestra «Windows protegió tu PC», elige **Más información → Ejecutar de todas formas** (el instalador aún no está firmado digitalmente).
+
+### Con pip (si ya usas Python 3.10 o superior)
+
+```bash
+pip install qagent-pytest
+qagent
+```
+
+En PyPI se llama `qagent-pytest` porque el nombre `qagent` ya lo usaba otro proyecto; el programa, el comando y la marca siguen siendo **QAgent**.
+
+## Antes de la primera corrida
+
+- **Docker Desktop**, abierto: las pruebas se ejecutan solo dentro de un contenedor aislado. La primera corrida prepara ese entorno sola (necesita internet y tarda unos minutos, una sola vez). [Descargar Docker Desktop](https://www.docker.com/products/docker-desktop/).
+- **Claves de API** de los modelos de IA: se agregan en la pantalla **Configuración** del programa, una por agente.
+- **Git**, si vas a abrir repositorios por su URL.
+
+¿Quieres probarlo sin claves ni costo? Agrega la línea `QAGENT_FAKE_LLM=1` al archivo `.env` de la carpeta `.qagent` de tu usuario (`C:\Users\<tú>\.qagent\.env`): QAgent usará una IA simulada con respuestas grabadas.
+
+Tus claves, tu configuración y la lista de proyectos recientes se guardan en esa carpeta `.qagent` de tu usuario, nunca junto al programa. Desinstalar QAgent no las borra.
+
+## Primeros pasos
+
+1. Abre **QAgent** desde el menú Inicio (o con el comando `qagent`).
+2. En **Configuración**, agrega la API de cada agente.
+3. En **Proyectos**, elige **Abrir proyecto** (una carpeta con código Python) o **Abrir repositorio** (una URL de Git).
+4. Revisa la **Vista previa**, elige el perfil en **Configuración de pruebas** e inicia la corrida.
+5. Sigue el avance en el **Monitor** y revisa el **Reporte final**; puedes exportarlo.
+
+## Alcance
+
+QAgent genera pruebas **unitarias** para código **Python 3.10+** y pruebas de endpoints FastAPI. Integración contra servicios reales, extremo a extremo, carga y estrés quedan fuera de esta versión.
+
+## Para el equipo de desarrollo
+
+Cómo preparar el entorno, ejecutar las pruebas, construir el instalador y publicar una versión: [`docs/desarrollo.md`](https://github.com/AngelOncoy/QAgent/blob/develop/docs/desarrollo.md). Las reglas del proyecto están en [`AGENTS.md`](https://github.com/AngelOncoy/QAgent/blob/develop/AGENTS.md) y las decisiones técnicas en [`docs/decisiones/`](https://github.com/AngelOncoy/QAgent/tree/develop/docs/decisiones).
+
+## Equipo
+
+Proyecto del curso Taller Integrador I, Ingeniería de Sistemas e Inteligencia Artificial, Universidad Privada Antenor Orrego (UPAO).
+
+Castillo Pezo, Mateo · Oncoy Patricio, Angel · Rodríguez Malca, Rodrigo · Sanchez Vargas, Adrián
+
+## Licencia
+
+[MIT](https://github.com/AngelOncoy/QAgent/blob/develop/LICENSE).

qagent_pytest-0.1.0/pyproject.toml

@@ -0,0 +1,80 @@
+[build-system]
+requires = ["setuptools>=77"]  # 77+: licencia como expresión SPDX (license = "MIT")
+build-backend = "setuptools.build_meta"
+
+[project]
+# Nombre en PyPI (`pip install qagent-pytest`): «qagent» ya era de otro proyecto. El
+# producto, el comando `qagent` y el paquete `import qagent` no cambian (ADR-005).
+name = "qagent-pytest"
+version = "0.1.0"
+description = "Sistema multiagente que genera y valida pruebas pytest para código Python 3.10+"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Equipo QAgent - Taller Integrador I (UPAO)" }]
+keywords = ["pytest", "testing", "unit tests", "llm", "multi-agent", "test generation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Win32 (MS Windows)",
+    "Intended Audience :: Developers",
+    "Natural Language :: Spanish",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "pywebview>=5.0.0",
+    "docker>=7.1.0",
+    "requests>=2.31",  # se usa directamente en sandbox/ejecucion.py
+    "jsonschema>=4.18",
+    "tomli>=2.0; python_version < '3.11'",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "ruff>=0.4.0",
+    "build>=1.2",  # scripts/verificar_paquete.py construye el wheel y el sdist
+]
+# Solo para construir el ejecutable de Windows (scripts/construir_windows.py).
+empaquetar = [
+    "pyinstaller>=6.10",
+]
+
+[project.urls]
+Repositorio = "https://github.com/AngelOncoy/QAgent"
+Problemas = "https://github.com/AngelOncoy/QAgent/issues"
+
+[project.scripts]
+qagent = "qagent.app.desktop:ejecutar"
+
+# Producto, comando y paquete se llaman igual: QAgent / `qagent` (antes `pyagent`).
+[tool.setuptools.packages.find]
+where = ["src"]
+# Se descubren también las carpetas sin __init__.py (frontend/, contracts/ejemplos/):
+# así setuptools no avisa de paquetes «ambiguos» y sus archivos se instalan.
+
+# Recursos que la app necesita instalada (TA-06): sin ellos `pip install qagent` abre sin interfaz.
+[tool.setuptools.package-data]
+"qagent.frontend" = ["**/*"]
+"qagent.config" = ["config.toml", "config.local.ejemplo.toml"]
+"qagent.contracts" = ["*.schema.json", "ejemplos/*.json"]
+"qagent.sandbox" = ["Dockerfile"]
+"qagent.llm" = ["proveedores.toml", "ia_simulada.json"]
+
+[tool.pytest.ini_options]
+# src/ para importar `qagent`; la raíz para importar helpers de las pruebas (`tests.orchestrator.fakes`).
+pythonpath = ["src", "."]
+testpaths = ["tests"]
+markers = [
+    'docker: prueba de integración que necesita Docker Desktop iniciado (omitir con -m "not docker")',
+    'red: prueba de integración que necesita internet (omitir con -m "not red")',
+]
+
+[tool.ruff]
+# bench/ y bench_api/ son bancos con bugs sembrados a propósito: no se reformatea ni se "arregla".
+extend-exclude = ["bench", "bench_api"]

qagent_pytest-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

qagent_pytest-0.1.0/src/qagent/__init__.py

@@ -0,0 +1,14 @@
+"""QAgent: sistema multiagente que genera y valida pruebas pytest para código Python."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+#: Nombre del paquete en PyPI (`pip install qagent-pytest`). El producto y el `import`
+#: siguen siendo QAgent / `qagent`; «qagent» en PyPI es de otro proyecto (TA-06).
+DISTRIBUCION = "qagent-pytest"
+
+try:
+    #: Versión instalada; la única fuente es `version` en pyproject.toml.
+    __version__ = _version(DISTRIBUCION)
+except PackageNotFoundError:  # ejecutado desde src/ sin instalar el paquete
+    __version__ = "0.0.0+desarrollo"

qagent_pytest-0.1.0/src/qagent/__main__.py

@@ -0,0 +1,6 @@
+"""Permite abrir la aplicación de escritorio con ``python -m qagent``."""
+
+from qagent.app.desktop import ejecutar
+
+if __name__ == "__main__":
+    ejecutar()

qagent_pytest-0.1.0/src/qagent/agents/__init__.py

@@ -0,0 +1,13 @@
+"""Agentes reales coordinados por el orquestador de QAgent."""
+
+from qagent.agents.generator import ErrorRespuestaGenerator, GeneratorAgent
+from qagent.agents.planner import ErrorRespuestaPlanner, PlannerAgent
+from qagent.agents.reviewer import ReviewerAgent
+
+__all__ = [
+    "ErrorRespuestaGenerator",
+    "ErrorRespuestaPlanner",
+    "GeneratorAgent",
+    "PlannerAgent",
+    "ReviewerAgent",
+]

qagent_pytest-0.1.0/src/qagent/agents/generator.py

@@ -0,0 +1,190 @@
+"""Agente Generator: convierte un contrato del Planner en código pytest."""
+
+from __future__ import annotations
+
+import ast
+import json
+from pathlib import PurePosixPath
+from typing import Any
+
+from qagent import contracts
+from qagent.llm import ClienteLLM, TokenTracker
+from qagent.llm.fake import MARCA_CONTRATO
+
+#: Caracteres de feedback (salida de pytest) que se reenvían al modelo.
+LARGO_MAXIMO_FEEDBACK = 2000
+
+
+class ErrorRespuestaGenerator(ValueError):
+    """El Generator devolvió una respuesta que no puede utilizarse."""
+
+    def __init__(self, mensaje: str, *, codigo: str = "") -> None:
+        super().__init__(mensaje)
+        self.codigo = codigo
+
+
+class GeneratorAgent:
+    """Genera el test de un único objetivo a partir de su contrato."""
+
+    def __init__(
+        self,
+        cliente: ClienteLLM,
+        tracker: TokenTracker,
+        *,
+        es_simulado: bool = False,
+    ) -> None:
+        """Inicializa el Generator con su cliente y registro de tokens."""
+        self.cliente = cliente
+        self.tracker = tracker
+        self.es_simulado = es_simulado
+
+    def generar(
+        self,
+        contrato: dict[str, Any],
+        intento: int,
+        feedback: str | None,
+    ) -> dict[str, Any]:
+        """Genera o corrige un test pytest."""
+        prompt = self._crear_prompt(contrato, intento, feedback)
+        respuesta = self.cliente.generar(prompt, rol="generator")
+
+        self.tracker.registrar(
+            agente="generator",
+            modelo=respuesta.modelo,
+            tokens_entrada=respuesta.tokens_entrada,
+            tokens_salida=respuesta.tokens_salida,
+            costo_usd=respuesta.costo_usd,
+            es_simulado=self.es_simulado,
+        )
+
+        codigo = _quitar_cerca_python(respuesta.contenido)
+        if not codigo.strip():
+            raise ErrorRespuestaGenerator("El Generator devolvió código vacío.")
+        try:
+            ast.parse(codigo)
+        except (SyntaxError, ValueError) as error:
+            raise ErrorRespuestaGenerator(
+                f"El Generator devolvió código Python inválido: {type(error).__name__}: {error}",
+                codigo=codigo,
+            ) from error
+
+        generado = {
+            "version": "1",
+            "objetivo": contrato["objetivo"],
+            "intento": intento,
+            "codigo": codigo,
+            "casos_cubiertos": [caso["id"] for caso in contrato["casos"]],
+        }
+        contracts.validar(contracts.GENERATED_TEST, generado)
+        return generado
+
+    @staticmethod
+    def _crear_prompt(
+        contrato: dict[str, Any],
+        intento: int,
+        feedback: str | None,
+    ) -> str:
+        # Una sola línea: más corto (menos tokens) y la IA simulada lo puede leer.
+        contrato_json = json.dumps(contrato, ensure_ascii=False)
+        correccion = (
+            _recortar(feedback)
+            if feedback
+            else "No existe feedback porque este es el primer intento."
+        )
+        if contrato.get("tipo") == "endpoint":
+            reglas_objetivo = _reglas_endpoint(contrato)
+        else:
+            importacion = (
+                f"from {modulo_importable(contrato['modulo'])} import "
+                f"{contrato['objetivo']}"
+            )
+            reglas_objetivo = f"""
+- Importa el objetivo exactamente así: {importacion}
+- Llama directamente a la función con la entrada de cada caso.
+- Para un caso con "excepcion" usa: with pytest.raises(<Excepcion>).
+""".strip()
+        return f"""
+Escribe un archivo pytest completo para el contrato indicado.
+
+REGLAS OBLIGATORIAS:
+{reglas_objetivo}
+- Escribe una función test_<id> por cada caso del contrato.
+- Usa exactamente los valores esperados del contrato (pytest.approx para float).
+- No ejecutes el código para descubrir resultados.
+- No elimines, cambies ni debilites las aserciones; sin try/except, skip ni xfail.
+- Simula con mocks las funciones incluidas en llama_a.
+- Devuelve únicamente código Python, sin explicaciones.
+- Este es el intento {intento}.
+
+FEEDBACK DEL INTENTO ANTERIOR:
+{correccion}
+
+{MARCA_CONTRATO} {contrato_json}
+""".strip()
+
+
+def _reglas_endpoint(contrato: dict[str, Any]) -> str:
+    """Reglas de generación para un endpoint FastAPI descrito por el contrato."""
+    modulo = modulo_importable(contrato["modulo"])
+    aplicacion = contrato["aplicacion"]
+    dependencias = contrato.get("dependencias", [])
+    simbolos = [aplicacion]
+    for dependencia in dependencias:
+        simbolos.extend([dependencia["funcion"], dependencia["reemplazo"]])
+    importacion = f"from {modulo} import {', '.join(dict.fromkeys(simbolos))}"
+    detalle_overrides = (
+        json.dumps(dependencias, ensure_ascii=False)
+        if dependencias
+        else "[] (este endpoint no declara Depends)"
+    )
+    return f"""
+- Usa fastapi.testclient.TestClient para realizar una petición HTTP real en memoria.
+- Importa la aplicación y los símbolos de override exactamente así: {importacion}
+- Construye TestClient({aplicacion}, raise_server_exceptions=False).
+- Usa client.request con método, ruta, query, json y headers del contrato.
+- Comprueba siempre response.status_code.
+- Si valor_esperado trae "json", compara response.json() completo.
+- Si trae "json_contiene", comprueba cada clave y valor indicados.
+- Dependencias a reemplazar: {detalle_overrides}
+- Para cada dependencia asigna {aplicacion}.dependency_overrides[funcion] = reemplazo.
+- Si una entrada trae "preparacion", instancia el reemplazo una vez en la fixture,
+  ejecuta allí cada método/modelo/argumentos declarado y usa un lambda que devuelva
+  esa misma instancia durante el test.
+- Usa una fixture con try/finally: guarda una copia de los overrides anteriores y,
+  al terminar cada test, limpia el diccionario y restaura exactamente esa copia.
+- Nunca reemplaces el manejador de la ruta ni modelos Pydantic.
+""".strip()
+
+
+def modulo_importable(modulo: str) -> str:
+    """Ruta del módulo relativa al proyecto -> nombre importable.
+
+    En el sandbox `PYTHONPATH` es la raíz del proyecto, así que
+    `bench/banco_mvp.py` se importa como `bench.banco_mvp`.
+    """
+    return (
+        PurePosixPath(modulo.replace("\\", "/"))
+        .with_suffix("")
+        .as_posix()
+        .replace("/", ".")
+    )
+
+
+def _recortar(texto: str, maximo: int = LARGO_MAXIMO_FEEDBACK) -> str:
+    """Deja solo el final del feedback (donde pytest pone el error) para ahorrar tokens."""
+    if len(texto) <= maximo:
+        return texto
+    return "[…recortado…]\n" + texto[-maximo:]
+
+
+def _quitar_cerca_python(contenido: str) -> str:
+    """Elimina una cerca Markdown ```python si el modelo la agregó."""
+    texto = contenido.strip()
+    if texto.startswith("```"):
+        lineas = texto.splitlines()
+        if lineas and lineas[0].strip().startswith("```"):
+            lineas.pop(0)
+        if lineas and lineas[-1].strip() == "```":
+            lineas.pop()
+        texto = "\n".join(lineas).strip()
+    return texto + "\n" if texto else ""