From 26f0b72b3c03a019819c0a9a7394a034961159b1 Mon Sep 17 00:00:00 2001 From: Ubuntu Date: Sun, 3 May 2026 20:12:10 +0000 Subject: [PATCH] docs(spec): add F2-A design spec for agent edit, regen and clone Co-Authored-By: Claude Sonnet 4.6 --- ...05-03-f2a-agent-edit-regen-clone-design.md | 283 ++++++++++++++++++ 1 file changed, 283 insertions(+) create mode 100644 docs/superpowers/specs/2026-05-03-f2a-agent-edit-regen-clone-design.md diff --git a/docs/superpowers/specs/2026-05-03-f2a-agent-edit-regen-clone-design.md b/docs/superpowers/specs/2026-05-03-f2a-agent-edit-regen-clone-design.md new file mode 100644 index 00000000..c57ff0c8 --- /dev/null +++ b/docs/superpowers/specs/2026-05-03-f2a-agent-edit-regen-clone-design.md @@ -0,0 +1,283 @@ +# Spec F2-A: Edició, Regeneració i Clonació d'Agents + +**Data:** 2026-05-03 +**Fase:** Fase 2-A del roadmap enterprise (2026-04-26-enterprise-roadmap.md) +**Estat:** Aprovat per disseny + +--- + +## Context + +La Fase 2 del roadmap enterprise té com a objectiu un flux iteratiu: +construir graf → ajustar agents → simular → ajustar → re-simular. + +Fins ara, MiroFish genera N agents a partir del graf de forma automàtica i no +permet modificar-los ni reutilitzar-los entre simulacions. L'usuari ha de +reconstruir tot el projecte si vol ajustar qualsevol cosa. + +Aquesta spec cobreix: +1. **Selector de nombre d'agents** — triar top-N per connectivitat abans de generar +2. **Edició d'agents individuals** — editar camps LLM-generats d'un agent concret +3. **Regeneració individual** — demanar al LLM que torni a generar un agent concret +4. **Clonació de simulació** — crear una nova simulació dins el mateix projecte + partint dels agents i config d'una simulació anterior + +### Nota sobre l'arquitectura de grafs (F2-D) + +El flag `enable_graph_memory_update` resta a `False` (default actual) durant F2-A. +Els reports es basen en el `graph_document` pur. L'arquitectura de múltiples +`group_id` per simulació (F2-D) es resoldrà en una fase posterior: clonar el +`graph_document` → `graph_sim_N` via Neo4j/APOC just abans de llançar cada +simulació (viable perquè Neo4j Aura Cloud inclou APOC de sèrie). + +--- + +## Model de dades + +### Canvi a la BD: `parent_simulation_id` + +Afegir una columna nullable a la taula `simulations`: + +```sql +ALTER TABLE simulations ADD COLUMN parent_simulation_id VARCHAR(64) REFERENCES simulations(simulation_id); +``` + +- `NULL` → simulació nova (comportament actual) +- Valor → simulació clonada d'una existent + +No hi ha canvis a cap altra taula ni model existent. + +### Immutabilitat de simulacions completades + +Una simulació amb `status IN ('completed', 'running')` no es pot editar. +Una simulació amb `status IN ('created', 'prepared', 'stopped', 'failed')` és editable. + +### Camps editables d'un perfil d'agent + +Editables (LLM-generats): `name`, `bio`, `persona`, `age`, `gender`, `mbti`, +`country`, `profession`, `interested_topics`, `stance`, `sentiment_bias`, `activity_level`. + +Immutables (OASIS els necessita intactes): `user_id`, `source_entity_uuid`, `source_entity_type`. + +### Flag de protecció contra sobreescriptura + +Cada agent té un flag `manually_edited: bool` (default `False`) a +`reddit_profiles.json` i `simulation_config.json`. Quan el generador inicial +treballa en batch, salta els agents amb `manually_edited: True`. + +--- + +## Subsistema 1: Selector de nombre d'agents (pre-generació) + +### Comportament + +Abans del botó "Generar agents" al Step 2, el sistema consulta quantes entitats +hi ha disponibles al graf. Mostra el total com a suggeriment (ex: "66 agents +disponibles"). L'usuari pot reduir el número. Si no toca res, el comportament +és idèntic a l'actual (es generen tots). + +Si l'usuari redueix a N, el backend selecciona les **top-N entitats per grau de +connectivitat** (nombre d'edges entrants + sortints al graf Zep). Les entitats +més connectades representen els actors amb més relacions al document, i generen +simulacions socialment més riques. + +**Mínim recomanat:** 15 agents (mida de batch de generació; per sota, la dinàmica +social és molt pobra). El frontend mostra un avís si l'usuari intenta posar menys de 15. + +### Canvis al backend + +**`POST /api/simulation/prepare`** — afegir paràmetre opcional: +```json +{ "max_agents": 40 } +``` + +Si `max_agents` present, `ZepEntityReader` ordena les entitats filtrades per +grau de connectivitat descendent i agafa les primeres N. + +Canvis a `oasis_profile_generator.py` / `simulation.py`: +- `ZepEntityReader.get_entities_by_connectivity(graph_id, max_n)` → nova funció +- Ordena per `len(edges)` de cada node retornat per `get_all_edges()` + +### Canvis al frontend (Step 2) + +Afegir just abans del botó "Generar agents": +- Crida a `GET /api/simulation/entities/{graph_id}` (ja existent) per obtenir el + total d'entitats disponibles +- Camp numèric amb valor default = total disponible +- Avís visual si valor < 15 +- El valor es passa a `POST /api/simulation/prepare` com a `max_agents` + +--- + +## Subsistema 2: Edició d'agents individuals + +### Comportament + +El modal de visualització d'agents (ja existent a `Step2EnvSetup.vue`) afegeix +un botó "Editar" que converteix els camps en inputs editables. En desar, el +backend actualitza el perfil i marca `manually_edited: True`. + +L'edició és possible: +- Durant la generació (altres agents en curs) → l'agent editat queda protegit +- Després de la generació completa +- No és possible si la simulació té `status: running` o `completed` + +### Canvis al backend + +**`PATCH /api/simulation/{sim_id}/agent/{user_id}`** + +``` +Body: { camps editables (qualsevol subconjunt) } +``` + +Acció: +1. Valida que la simulació no és `running` ni `completed` +2. Carrega `reddit_profiles.json` i `simulation_config.json` +3. Localitza l'agent per `user_id` +4. Aplica els canvis + `manually_edited: True` +5. Desa els fitxers atòmicament (backup previ → escriptura → elimina backup si OK, restaura si falla) +6. Retorna el perfil actualitzat + +### Canvis al frontend (Step 2) + +Al modal d'agent (`Step2EnvSetup.vue`): +- Botó "Editar" → converteix camps en `` / `