# L'agent Arkadium

Arkadium es un agent conversacional ancorat estructuralment al **Meta-Globàlium**, un model ontologic hyperdimensional que organitza el coneixement humà en **80 categories distintes** repartides en 8 quadrants. A diferencia d'un LLM generic amb RAG sobre internet, Arkadium opera amb una ontologia canonica curada i verifica les seves respostes contra una nocio formal del **Bé** com a compensacio harmonica entre les diferents parts del model.

## Model: Meta-Globàlium

El Meta-Globàlium es una hipersfera 4D projectada a 3D. Quatre dimensions fonamentals:

| Eix | Pol negatiu | Pol positiu |
|-----|-------------|-------------|
| D1 | OBJ (objectiu) | SUB (subjectiu) |
| D2 | TEO (teoria) | PRA (practica) |
| D3 | NOU (noumenon) | FEN (phenomenon) |
| D4 | PLA (plasma) | MON (mon) |

Arquitectura per capes: 8 primaries → 26 segon nivell → 80 categories distintes en total (les 8 primaries estan topològicament situades dins les capes, no en formen una de separada).

## El Mètode d'Aplicació ANA→SIN→AMO→EXP

Cada interaccio travessa quatre fases (alineades amb el Mètode d'Aplicació de la Globalistica):

1. **ANA — Anàlisi**: vector search top-5 sobre les 80 categories distintes, ancora la pregunta a l'ontologia.
2. **SIN — Síntesi**: validacio de coherencia globalistica entre les categories rellevants.
3. **AMO — Amor**: generacio de la resposta amb traçabilitat, citant codis de categories.
4. **EXP — Experiència**: visualitzacio (highlight al model 3D) i feedback estructural.

> 📖 **Vegeu [pipeline-end-to-end.md](pipeline-end-to-end.md)** per al fil complet de les 23 fases que es generen per cada resposta: pre-LLM (auth, RAG, structural pre-pass, question classification, escope, backbone, cycle state, coaching), LLM call, i post-LLM (verifier, re-prompt loop, two-pass polish, SD-WISE probe, auto-save, output JSON).

## Verificador estructural

Despres de cada generacio, l'agent extreu els codis citats i mesura la dispersio entre els 8 quadrants:

- `n_quadrants` — quants quadrants diferents toca la resposta (0..8)
- `harmonic_score` — cobertura + entropia de Shannon, normalitzada 0..1
- `needs_reprompt` — true si toca menys de 3 quadrants (resposta esbiaxada)

Score alt (>0.7) → resposta amb perspectives multiples (subjectives + objectives, teoriques + practiques). Score baix → suggereix un "Cicle" complementari.

### Mètriques canòniques addicionals (2026-05-02)

A més de la cobertura per quadrants, el verificador mesura tres dimensions complementàries derivades de la mineria de descripcions del meta-de-PLA (vegeu `docs/canonical-mappings.md`):

**Cobertura causal** (Aristòtel) — `causal_coverage` ∈ [0,1] sobre 7 causes:
- Material/formal/final → OBJ — Eficient → SUB — Exemplar → DIV — Contextual → FEN — Essencial → ORG

**Cobertura epistemològica** (3 tipus d'inferència) — `epistemic_coverage` ∈ [0,1] sobre 4 tipus:
- Deducció: LOG, ANA — Inducció: IDE, SIN — Abducció selectiva: EST — Abducció creativa: MIT

**Balanç Solve-Coagula** (meta-operació alquímica) — `solve_coagula_balance` ∈ [0,1]:
- Solve-side (dissoldre/diferenciar): ANA + CIE — Coagula-side (coagular/integrar): SIN + MTP
- Score 1.0 quan ambdues bandes estan equilibrades

**Cobertura tempeternal** (D4 transversal — adoptat 2026-05-02) — `tempeternal_coverage` i `tempeternal_balance` ∈ [0,1]:
- D4 (eix radial PLA-MON) s'anomena canònicament **tempeternitat** (portmanteau català: temps + eternitat)
- És la meta-dimensió transversal: cada pol cartesià té 3 moments tempeternals (PLA-side atemporal-essencial / NEU equilibri / MON-side temporal-manifest)
- `tempeternal_coverage` mesura quantes capes (PLA/NEU/MON) toca la resposta (0=cap, 1=totes 3)
- `tempeternal_balance` mesura distribució equilibrada entre les 3 capes via entropia normalitzada
- Una resposta tota PLA-side és "abstracta-eterna sense aterrar"; tota MON-side és "factual sense profunditat de principi"; només NEU és "operativa sense arrels ni fruits". La saviesa integra els tres moments tempeternals.

Una resposta puerament deductiva, sense induir o abduir, és epistemològicament parcial. Una explicació sense causa final és causalment incompleta. Una resposta tota Solve sense Coagula és analíticament fragmentada (i a l'inrevés). Una resposta amb `tempeternal_coverage < 1` està restringida a un sol estrat radial.

## Iteració Solve-Coagula (meta-operació, 2026-05-02)

L'aforisme alquímic *solve et coagula* descriu el cicle iteratiu de transformació conceptual: dissol allò compost i coagula-ho de nou en una forma superior. L'agent d'Arkadium aplica aquesta meta-operació recursivament sobre les seves respostes:

1. **Iteració 0**: pregunta → resposta inicial (cicle Mètode FEN→ANA→TEO→SIN→NOU→AMO→PRA→EXP)
2. **Iteració 1**: Solve la resposta inicial (analitzar, criticar, identificar buits) → Coagula resposta millorada
3. **Iteració N**: fins a estabilitat o llindar de qualitat

### Aplicabilitat direccional de Solve-Coagula

**Solve-Coagula ÉS literalment el moviment FEN→NOU** (essencialització) — només aplica quan la pregunta requereix extreure essència del fenomen:
- ✅ **Aplicable al Cicle del Mètode** (FEN→ANA→TEO→SIN→NOU... — ANA+SIN són Solve-Coagula directe)
- ✅ **Aplicable al Cicle del Coneixement** (FEN→ART→SUB→MTP→NOU... — recorre les 4 operacions de cara que essencialitzen)
- ❌ **Inaplicable al Cicle de la Relació/Orientació** (NOU→CNF→FEN→CMN→MON... — moviment invers NOU→FEN, no essencialitza)

Per això el verificador només mesura `solve_coagula_balance` quan la resposta inclou essencialització (cita ANA, CIE, SIN o MTP). Per preguntes d'orientació tipus *"on sóc?"*, *"què em passa?"*, *"quin sentit té això?"* el chip Solve-Coagula no es mostra (no és una mètrica adequada per aquest tipus de viatge).

Aquesta meta-operació formalitza el re-prompt loop existent: el sistema fa empíricament des del 2026-04-30 el que ara queda inscrit al model com a operació canònica.

## Compensació harmònica en runtime (multi-iteració 2026-05-02)

L'agent no només verifica les seves respostes contra el model: també hi reacciona. Quan el verificador detecta **alguna mètrica desbalançada** (cobertura de quadrants, balanç Solve-Coagula direccional o cobertura tempeternal D4), l'agent es **reformula a si mateix** amb una consigna pedagògica específica al tipus de desequilibri detectat.

Aquest gest materialitza, en runtime, el principi del manifest: el **Bé** entès com a **compensació harmònica** entre les parts del model. No és un filtre que rebutja respostes "dolentes": és un convit a equilibrar perspectiva.

### Multi-iteració del cicle Solve-Coagula

L'agent pot iterar fins a **N vegades** (default 2, configurable) sobre la mateixa pregunta:

1. **Iteració 0**: pregunta → resposta inicial (cicle Mètode FEN→ANA→TEO→SIN→NOU→AMO→PRA→EXP)
2. **Iteració 1**: Solve la resposta inicial (analitzar buits) → Coagula resposta millorada
3. **Iteració 2**: Solve la millorada → Coagula refinada
4. ... fins a estabilitat

**El loop s'atura quan**:
- ✅ L'`harmonic_score` és prou alt (≥ 0.85)
- ✅ La millora entre iteracions és petita (Δ < 0.05) → **convergència**
- ❌ Una iteració no millora → defensiu
- ⏱️ S'arriba al límit d'iteracions (default 2)

### El badge "🔄 Reformulada"

Veuràs aquest badge sota la resposta del bot quan s'ha aplicat compensació. Si hi ha hagut més d'una iteració, mostra **"×N"** (e.g., "Reformulada ×2"). El **tooltip** mostra:
- Motiu (legible): *baixa dispersió de quadrants*, *desbalanç Solve-Coagula (FEN→NOU)*, *cobertura tempeternal parcial*, *múltiples senyals*
- Nombre d'iteracions del cicle Solve-Coagula
- Harmònic final + delta acumulat

### Mètriques que poden disparar reformulació

| Trigger | Significat | Tipus de viatge |
|---------|-----------|------------------|
| `low_dispersion` | < 3 quadrants tocats — resposta esbiaixada | qualsevol |
| `solve_coagula_imbalance` | Solve sense Coagula o viceversa, **només si essencialització FEN→NOU** | axial vertical |
| `tempeternal_partial` | No toca les 3 capes PLA-NEU-MON (D4 transversal) | radial |
| `multi_signal` | Múltiples triggers alhora | combinat |

L'agent **mai empitjora una resposta ja balancejada** — només manté la nova versió si efectivament millora les mètriques. Si una iteració no aporta millora, atura el loop. Si Solve-Coagula no és aplicable (pregunta d'orientació, sense moviment FEN→NOU), no es penalitza el desbalanç.

És una alternativa pràctica al model "Constitutional AI": en lloc d'una constitució textual fixa, l'agent es regula contra una estructura ontològica explícita (el Meta-Globàlium) i un Process Reward Model — vegeu Berenguer J. (2026), *Globalium Manifest Tecnic*.

## Memòria personal i sobirania de dades

Cada usuari té la seva pròpia **KB-B privada** (memòria personal), independent de la KB-A canònica que comparteix tothom. L'agent recupera context dels dos àmbits a cada conversa:

- **KB-A — ontologia compartida**: les 80 categories distintes del Meta-Globàlium, curades centralitzadament. Marcada com a `[ONTOLOGIA]` al prompt.
- **KB-B — memòria personal**: històric de converses, fets, anotacions, preferències. Marcada com a `[MEMÒRIA]` al prompt. Aïllament estricte: cap usuari mai accedeix a la memòria d'un altre.

Hi ha cinc tipus d'items a la memòria personal: `fact`, `annotation`, `position` (zones d'interès al Globe), `preference`, `message` (preguntes prèvies indexades automàticament).

**Manifest sobiranista**: pots **exportar** tota la teva memòria en qualsevol moment (`/memory_export` retorna un JSON sencer amb les teves entrades, sense embeddings) o **esborrar-la** físicament (`/memory_erase` elimina el fitxer i les files de la base de dades). Aquest dret a l'oblit forma part del disseny de l'eina, no és una opció afegida.

## La teva trajectòria al model

Cada vegada que parles amb l'agent arkadium, el verificador estructural mesura quins eixos del Meta-Globàlium ha tocat la resposta. Aquesta dada — quins quadrants s'han activat, amb quina dispersió, amb quina freqüència — s'acumula al teu històric personal i dibuixa, conversa rere conversa, una **trajectòria** pròpia per l'espai ontològic.

Pots veure aquesta trajectòria a la pàgina **"Memòria personal"**, en una secció dedicada que mostra la freqüència de cada un dels 8 quadrants (PLA, MON, TEO, PRA, SUB, OBJ, FEN, NOU), un indicador de **diversitat** (entropia normalitzada entre 0 i 1, on 1 vol dir exploració equilibrada de tots els eixos), el teu harmònic mitjà i una línia temporal de les últimes interaccions. També la pots **visualitzar directament al model 3D del dashboard**: un botó "Veure trajectòria" il·lumina els pols cardinals proporcionalment a com els has treballat, i esvaeix les categories que no formen part del teu camí actual.

Aquesta dada és **estrictament personal**. La KB-B està aïllada per usuari (cap usuari pot veure la trajectòria d'un altre) i el contracte respecta plenament les regles GDPR ja explicades: pots exportar-la o esborrar-la quan vulguis.

L'eina suggereix, de tant en tant, que potser val la pena explorar zones poc tocades del model — no com a crítica ni gamification, sinó com a **invitació pedagògica** a ampliar perspectiva. Si la teva pràctica habitual gravita cap a un parell d'eixos, descobrir què hi diu el model en un eix complementari pot enriquir el diàleg. La trajectòria és, en aquest sentit, un mirall: una eina d'autoconsciència, no un rànquing.

## API: endpoints disponibles

L'API es publica a `https://api.arkadium.ai/`. Tots els endpoints requereixen autenticació via cookie `arkadium_token` (emès al login, vàlid 30 dies, `domain=.arkadium.ai`, `httponly`, `secure`, `samesite=Lax`).

### Conversa
- `/get_config` — configuració de providers/agents/models disponibles.
- `/reset` — reinicia l'historial de la sessió actual.
- `/ask` — pregunta a l'agent (vegeu contracte sota).

### Threads
- `/list_threads` — llista les teves converses ordenades per última activitat.
- `/load_thread` (`{thread_id}`) — carrega els missatges d'una conversa.
- `/save_thread` (`{thread_id?, title?}`) — crea o actualitza una conversa.
- `/delete_thread` (`{thread_id}`) — esborra (soft-delete) una conversa.

### Memòria
- `/memory_search` (`{query, top_k?}`) — vector search dins la teva memòria personal.
- `/memory_list` (`{kind?, limit?, offset?}`) — llista paginada d'entrades.
- `/memory_delete` (`{item_id}`) — esborra una entrada concreta.
- `/memory_export` — descarrega la teva memòria sencera (JSON, GDPR-friendly).
- `/memory_erase` — esborra completament la teva memòria personal.

### Trajectòria
- `/coverage_summary` (`{window?}`) — resum analític de la teva trajectòria al Meta-Globàlium (`window` ∈ `7d` / `30d` / `all`, default `all`). Retorna distribució per quadrant, entropia normalitzada, harmònic mitjà, banderes pedagògiques i activitat recent.

## API: endpoint `/ask`

**Request** (POST a `https://api.arkadium.ai/ask`):

```json
{
  "question": "que es la bellesa?",
  "agent": "arkadium",
  "provider": "openai",
  "userLanguage": "catala",
  "thread_id": 2,
  "escope": 0
}
```

**Response**:

```json
{
  "answer": {"choices": [{"message": {"content": "..."}}]},
  "meta": {
    "provider": "openai",
    "model": "gpt-4o",
    "agent": "arkadium",
    "escope": 0,
    "two_pass_applied": true,
    "two_pass_first_draft": "..."
  },
  "thread_id": 2,
  "categories_touched": ["BEL","FEN","OBJ","SLM","TEO"],
  "harmonic_score": 0.778,
  "wisdom_score": 0.74,
  "verification_meta": {"n_quadrants": 6, "needs_reprompt": false},
  "reprompt_iterations": 0,
  "reprompt_reason": null,
  "reprompt_attempted": false,
  "memory_hits": [
    {"id": 1, "kind": "message", "content_excerpt": "que es la bellesa?", "score": 0.609, "created_at": "2026-04-30 17:18:02"}
  ],
  "retrieved": [{"label": "BEL", "nom": "Bellesa", "score": 0.6125}]
}
```

El camp `answer.choices[0].message.content` conte el text de la resposta. El camp `thread_id` permet continuar la conversa; si no s'envia, l'agent en crea un de nou amb auto-títol. El camp `memory_hits` mostra quines entrades de la teva memòria personal s'han recuperat per contextualitzar la resposta. Els camps `reprompt_*` informen si l'agent ha aplicat una reformulació per compensació harmònica (`reprompt_iterations=1` quan s'ha aplicat i acceptat). Els camps additius permeten al frontend ressaltar al **Metamodeler 3D** les categories citades.

### Paràmetre `escope` (Phase 1.5, 2026-05-08)

L'usuari pot triar el mode de generació amb el paràmetre `escope ∈ {-1, 0, +1}`. Aquest paràmetre és una **interfície directa amb la dimensió radial PLA-MON** del Meta-Globàlium:

| Valor | Mode | Registre | Quan demanar-lo |
|---|---|---|---|
| `-1` | **General** | Holístic, integrador, sense bastida estructural visible. Wisdom register. | Quan vols la visió global, una articulació sintètica que t'inspiri o t'orienti |
| `0` | **Equilibrat** (default) | Estructura dialèctica + registre savi. Polish savi automàtic. | Default — bona resposta per la majoria de preguntes |
| `+1` | **Focal** | Concret, amb autors / dates / casos verificables. Citacions explícites. | Quan vols fonts, evidència, depth d'un aspecte concret |

Quan `escope ∈ {-1, 0}`, l'agent fa una **generació en dues passades**: pass-1 produeix la resposta amb tota l'estructura dialèctica (codis cardinals, mediadors anomenats, headings); pass-2 (poliment savi) reescriu la mateixa substància com a articulació integrada, eliminant la bastida visible. El draft pre-poliment es retorna a `meta.two_pass_first_draft` per transparència — el frontend l'exposa com a `<details>` plegat ("veure el procés"). Quan `escope = +1`, el polish no s'aplica: la bastida estructural és precisament el que el mode focal vol mantenir visible.

La mètrica primària `wisdom_score` reflecteix el **draft** (la feina dialèctica feta), no el polished (el polished elimina per disseny els codis que 𝓦 v2 mesura). `meta.polished_*` exposa la mateixa mètrica sobre la resposta polida — només per anàlisi.

Spec completa: [`docs/escope-parameter-design.md`](https://arkadium.ai/docs/escope-parameter-design.md).

## Citacions

- Xirinacs LM (1997). *A global model of reality*. Tesi doctoral, Universitat de Barcelona.
- Berenguer J. (2023). *Saviesa Artificial — Quadern de Globalistica*. Opengea SCCL.
- Berenguer J. (2024). *Globàlium petit manual*. Mas el Negre.
- Berenguer J. (2026). *Globalium Manifest Tecnic*. Opengea SCCL.

Codi: https://github.com/opengea/arkadium · https://github.com/opengea/metamodeler