From a1862c1c8657ebc5fb49ea121f5c85d124adbd25 Mon Sep 17 00:00:00 2001 From: Ubuntu Date: Sun, 3 May 2026 20:32:33 +0000 Subject: [PATCH] =?UTF-8?q?docs(spec):=20update=20F2-A=20spec=20=E2=80=94?= =?UTF-8?q?=20add=20agent=20creation/deletion=20and=20graph=20isolation=20?= =?UTF-8?q?(ex=20F2-D)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- ...05-03-f2a-agent-edit-regen-clone-design.md | 362 ++++++++++++------ 1 file changed, 245 insertions(+), 117 deletions(-) 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 index c57ff0c8..3883eaf4 100644 --- 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 @@ -1,7 +1,7 @@ -# Spec F2-A: Edició, Regeneració i Clonació d'Agents +# Spec F2-A: Edició, Regeneració, Creació i Clonació d'Agents -**Data:** 2026-05-03 -**Fase:** Fase 2-A del roadmap enterprise (2026-04-26-enterprise-roadmap.md) +**Data:** 2026-05-03 +**Fase:** Fase 2-A del roadmap enterprise (2026-04-26-enterprise-roadmap.md) **Estat:** Aprovat per disseny --- @@ -16,19 +16,12 @@ 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). +3. **Regeneració, creació i eliminació d'agents individuals** — regenerar un agent, crear-ne un de nou basat en una entitat del graf, o eliminar-ne un +4. **Clonació de simulació** — crear una nova simulació dins el mateix projecte partint dels agents i config d'una simulació anterior +5. **Aïllament de grafs per simulació** (ex F2-D) — cada simulació escriu les converses al seu propi `group_id` Neo4j via clonatge APOC --- @@ -39,7 +32,8 @@ simulació (viable perquè Neo4j Aura Cloud inclou APOC de sèrie). Afegir una columna nullable a la taula `simulations`: ```sql -ALTER TABLE simulations ADD COLUMN parent_simulation_id VARCHAR(64) REFERENCES simulations(simulation_id); +ALTER TABLE simulations + ADD COLUMN parent_simulation_id VARCHAR(64) REFERENCES simulations(simulation_id); ``` - `NULL` → simulació nova (comportament actual) @@ -47,23 +41,37 @@ ALTER TABLE simulations ADD COLUMN parent_simulation_id VARCHAR(64) REFERENCES s No hi ha canvis a cap altra taula ni model existent. +### Canvi a la BD: `graph_id_simulation` + +Afegir una columna nullable a la taula `simulations`: + +```sql +ALTER TABLE simulations + ADD COLUMN graph_id_simulation VARCHAR(128); +``` + +Conté el `group_id` Neo4j exclusiu d'aquesta simulació (creat per clonatge APOC +just abans de llançar). `NULL` fins que la simulació s'inicia. + ### 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. +- `status IN ('completed', 'running')` → no es pot editar +- `status IN ('created', 'prepared', 'stopped', 'failed')` → 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`. +`country`, `profession`, `interested_topics`, `stance`, `sentiment_bias`, +`activity_level`. -Immutables (OASIS els necessita intactes): `user_id`, `source_entity_uuid`, `source_entity_type`. +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`. +Cada agent porta un flag `manually_edited: bool` (default `False`) a +`reddit_profiles.json` i `simulation_config.json`. El generador en batch salta +els agents amb `manually_edited: True`. --- @@ -72,37 +80,36 @@ treballa en batch, salta els agents amb `manually_edited: True`. ### 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 +hi ha disponibles al graf i 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). +és idèntic a l'actual. 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 +connectivitat** (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. +**Mínim recomanat:** 15 agents. El frontend mostra un avís si el valor és inferior. ### Canvis al backend -**`POST /api/simulation/prepare`** — afegir paràmetre opcional: +`POST /api/simulation/prepare` — nou paràmetre opcional: + ```json { "max_agents": 40 } ``` -Si `max_agents` present, `ZepEntityReader` ordena les entitats filtrades per +Si `max_agents` és 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()` +Nova funció: `ZepEntityReader.get_entities_by_connectivity(graph_id, max_n)` — +obté totes les entitats, les ordena per `len(edges)` i retorna les top-N. ### 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 +Just abans del botó "Generar agents": + +- Crida a `GET /api/simulation/entities/{graph_id}` (ja existent) per obtenir el total - 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` @@ -117,77 +124,110 @@ 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` +L'edició és possible durant la generació (l'agent editat queda protegit) i +després de la generació completa. No és possible si `status: running` o `completed`. ### Canvis al backend -**`PATCH /api/simulation/{sim_id}/agent/{user_id}`** +`PATCH /api/simulation/{sim_id}/agent/{user_id}` -``` -Body: { camps editables (qualsevol subconjunt) } +```json +{ "bio": "...", "stance": "opposing" } ``` 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) +5. Desa atòmicament (backup → 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 `` / `