From 005f3e19b57ea01a641076c73d41a01503f3f201 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Fri, 21 Nov 2025 08:29:04 +0000 Subject: [PATCH] Update documentation to include Prompts management details --- docs/IDi_documentacion.md | 2 ++ docs/arquitectura.md | 6 +++--- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/IDi_documentacion.md b/docs/IDi_documentacion.md index 121bd23..f35b030 100644 --- a/docs/IDi_documentacion.md +++ b/docs/IDi_documentacion.md @@ -12,6 +12,7 @@ - Vistas previas de contexto recuperado (archivos, descripciones y fragmentos) y estimación de costes antes de ejecutar operaciones, lo que habilita control financiero y técnico. - Selección granular de pasos/fragmentos generados y aplicación automática de cambios en el repositorio, manteniendo historial claro de acciones. - Gestión de prompts personalizados, chat contextual sobre el código y panel de uso/costes, facilitando iteraciones rápidas y reproducibles. +- La página de gestión de prompts permite ver y modificar los prompts utilizados por los agentes, adaptando el comportamiento de la herramienta a necesidades específicas sin tocar el código fuente. - Exportación e importación de metadatos para acelerar sesiones posteriores o compartir conocimiento entre equipos. ### Innovación frente al estado del arte @@ -105,6 +106,7 @@ 3. **Plan de despliegue y Terraform**: estrategia para AWS con recursos derivados del código y scripts Terraform generados. Incluir validación con `terraform plan` y evidencias de conformidad con políticas internas. 4. **Refactorización**: lista de archivos candidatos, plan de cambios y diff aplicado en un módulo específico. Acompañar con ejecución de tests relacionados para demostrar no regresión. 5. **Chat contextual**: conversación guiada para resolver dudas de arquitectura o seguridad usando el contexto recuperado, mostrando precisión y rapidez frente a búsquedas manuales. +6. **Gestión de Prompts**: demostración de cómo la modificación de un prompt de sistema afecta la salida de un caso de uso (ej. cambiar el estilo de documentación), evidenciando la flexibilidad de la plataforma. ### Trazabilidad y anexos - Para cada caso, incluir: contexto seleccionado (archivos y descripciones), prompt utilizado, salida generada y resultado aplicado (si procede). Adjuntar hashes o referencias de commit para asegurar reproducibilidad. diff --git a/docs/arquitectura.md b/docs/arquitectura.md index e2d87ce..b5e40c8 100644 --- a/docs/arquitectura.md +++ b/docs/arquitectura.md @@ -4,13 +4,13 @@ Este documento resume cómo está organizada la herramienta **codeas**, cuáles ## Arquitectura global -1. **Entrada y experiencia de usuario**. El ejecutable `codeas` inicia la interfaz de Streamlit definida en `src/codeas/main.py`, la cual carga la página principal `ui/🏠_Home.py`. Desde allí se navega por las páginas de documentación, despliegue, testing, refactorización, chat y uso (todas en `src/codeas/ui/pages`). +1. **Entrada y experiencia de usuario**. El ejecutable `codeas` inicia la interfaz de Streamlit definida en `src/codeas/main.py`, la cual carga la página principal `ui/🏠_Home.py`. Desde allí se navega por las páginas de documentación, despliegue, testing, refactorización, chat, gestión de prompts y uso (todas en `src/codeas/ui/pages`). 2. **Estado compartido de la sesión**. `codeas.core.state.State` centraliza la ruta del repositorio activo, la instancia del cliente LLM, los metadatos precargados y los filtros de archivos. El estado también gestiona la tabla de archivos visibles, la lectura/escritura de salidas y la persistencia de filtros en `.codeas/filters.json`. 3. **Modelo del repositorio**. `codeas.core.repo.Repo` indexa todos los archivos, calcula su costo en tokens, aplica filtros `include/exclude` y expone las rutas incluídas para los distintos casos de uso. 4. **Metadatos y enriquecimiento**. `codeas.core.metadata.RepoMetadata` coordina agentes especializados para clasificar cada archivo (`FileUsage`), generar descripciones, extraer detalles de código y de pruebas, y persistir los resultados en `.codeas/metadata.json`. 5. **Recuperación de contexto**. `codeas.core.retriever.ContextRetriever` decide qué archivos (o resúmenes) enviar al LLM según flags por dominio (UI, API, DB, etc.) y según si se requieren descripciones o detalles estructurados. 6. **Casos de uso**. Cada funcionalidad de alto nivel (documentación, despliegue, testing, refactorización) reside en `src/codeas/use_cases`. Allí se preparan contextos, prompts y modelos específicos, y se registra el costo en `UsageTracker`. -7. **Agentes y clientes LLM**. `codeas.core.agent.Agent` encapsula la construcción de mensajes, el cálculo de costos/tokens (vía `tokencost`) y la ejecución en `codeas.core.llm.LLMClient` (OpenAI) o `codeas.core.clients.LLMClients` (OpenAI/Anthropic/Gemini). Los prompts se parametrizan en `src/codeas/configs/prompts.py` y las páginas usan `configs/agents_configs.py` y `configs/llm_params.py` según corresponda. +7. **Agentes y clientes LLM**. `codeas.core.agent.Agent` encapsula la construcción de mensajes, el cálculo de costos/tokens (vía `tokencost`) y la ejecución en `codeas.core.llm.LLMClient` (OpenAI) o `codeas.core.clients.LLMClients` (OpenAI/Anthropic/Gemini). Los prompts de los casos de uso se parametrizan en `src/codeas/configs/prompts.py`, mientras que los prompts de metadatos residen en `src/codeas/core/metadata.py`. Las páginas usan `configs/agents_configs.py` y `configs/llm_params.py` según corresponda. 8. **Telemetría de uso**. `codeas.core.usage_tracker.UsageTracker` persiste estadísticas de cada llamada (costos, recuentos y logs de chat) en `~/codeas/usage.json`, lo cual alimenta la página “Usage”. ## Servicios y módulos clave @@ -18,7 +18,7 @@ Este documento resume cómo está organizada la herramienta **codeas**, cuáles | Servicio / módulo | Responsabilidad principal | | --- | --- | | `src/codeas/main.py` | Lanza la aplicación Streamlit y enlaza la CLI con la UI. | -| `src/codeas/ui/🏠_Home.py` + `ui/pages` | Componen la experiencia visual, muestran formularios para cada caso de uso y disparan acciones sobre el `state`. | +| `src/codeas/ui/🏠_Home.py` + `ui/pages` | Componen la experiencia visual, muestran formularios para cada caso de uso (Docs, Test, Deploy, Refactor, Chat, Prompts) y disparan acciones sobre el `state`. | | `src/codeas/core/state.py` | Mantiene el estado compartido (repo activo, metadatos, filtros, datos para tablas) y coordina operaciones auxiliares (lectura/escritura de salidas). | | `src/codeas/core/repo.py` | Descubre archivos, calcula tokens y aplica filtros `include/exclude` con coincidencias flexibles. | | `src/codeas/core/metadata.py` | Define los esquemas de metadatos, orquesta agentes para poblarlos y expone helpers de lectura/exportación. |