cof-cli 1.0.0__tar.gz → 1.1.0__tar.gz

cof_cli-1.1.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: cof-cli
+Version: 1.1.0
+Summary: COF — Character Open File: validate, pack, unpack and convert .cof character containers
+Author: Yann Souetre
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: jsonschema>=4.20
+Provides-Extra: tokens
+Requires-Dist: tiktoken>=0.7; extra == "tokens"
+Provides-Extra: png
+Requires-Dist: Pillow>=10; extra == "png"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: Pillow>=10; extra == "dev"
+
+# cof-cli
+
+Outil de référence pour COF (Character Open File) : validation, empaquetage, extraction, fusion, conversions, et l'ajout d'un souvenir vécu (1.1). `pip install cof-cli` (PyPI) ou, depuis ce dossier, `pip install -e ".[dev]"`. Python ≥ 3.10.
+
+```bash
+cof validate spec/examples/10-clara-mercier        # dossier ou fichier .cof : erreurs, avertissements, complétude (--json pour la CI)
+cof pack spec/examples/10-clara-mercier -o clara.cof   # recalcule hashes, complétude, langues ; écrit COF.md et la vignette
+cof info clara.cof                                  # presets, déclinaisons, âges, tags — le point de départ pour un agent
+cof unpack clara.cof -o clara/
+cof tokens clara.cof
+cof extract clara.cof --preset fr-65 -o clara-65/   # une tranche plus légère : un preset, un personnage (--identity) ou des tags (--tag fr --tag age-65)
+cof extract clara.cof --identity clara-mercier --all-audiences -o clara-sfw/   # sans nudité ni intime, médias des souvenirs explicites retirés (gist conservé)
+cof extract clara.cof --preset default --keep-personal -o clara-perso/         # garde les souvenirs `visibility: personal` (retirés par défaut)
+cof merge clara.cof martien.cof -o duo/             # un casting : même nom + surnom + statut fictif + morphologie ⇒ même personnage, sinon plusieurs
+cof memory add clara.cof --gist fr="Ce matin, relu avec Léo." --gist en="This morning, reread with Léo." --date 2026-10-25 --who "Léo" --tag travail --personal
+cof memory add clara/ --kind period --gist en="The agency years." --age 24 --approx --fidelity faded   # sur un dossier ; `--help` liste tout (--where, --self-shown, --media, --preset…)
+cof import carte.png -o perso/ --age 30 --lang fr --keep-png   # carte PNG CCv2/V3 → dossier COF
+cof export clara.cof --format png -o clara.png      # → PNG avec chunks chara + ccv3
+cof export clara.cof --format card -o clara.card.json
+cof export clara.cof --format soul -o ./agent/      # → SOUL.md + IDENTITY.md
+cof export clara.cof --format agent -o ./agent/     # → espace de travail d'agent : SOUL.md, IDENTITY.md, skills/, MEMORY.md + memories/ (--keep-personal, --preset)
+cof embed-text clara.png fiche.md -o clara-fiche.png   # texte descriptif dans un PNG (iTXt), lisible par le builder
+cof read-text clara-fiche.png
+cof migrate dossier-v0.5/                           # v0.2 … v0.5 → 1.0
+```
+
+Ce que `validate` vérifie : la structure de l'archive (sentinelle `mimetype`, chemins sûrs, pas d'entrée en double ni chiffrée, taux de compression, taille), les hashes SHA-256 et tailles des assets, les schémas JSON du manifeste et des sous-fichiers (`card`, `psyche`, `weights`, `voice-profile`, `memory`…), la résolution des presets (slots, alternatives, `extends`, `derives_from`), les identifiants d'assets et de déclinaisons, les règles d'âge sur l'**âge le plus bas** d'un preset (déclinaisons appliquées et offertes, `age_override`, souvenirs qui montrent le personnage), l'interdiction de tout contenu nu ou intime sous 18 ans, le consentement d'une personne réelle, les règles des souvenirs (RFC 0002 : forme de `when`, liens, `media_from`, nœuds explicites — qui est montré, âges connus et adultes, âge vécu ≥ 18, drapeau `nudity`, `tags.content`), les relations entre personnages d'un casting (RFC 0003), les styles mélangés, les transcriptions des échantillons de voix, le contenu exécutable non déclaré, les doublons, les budgets de tokens ; puis recalcule la complétude et les cibles prêtes. Les chemins et noms lus dans un manifeste ne sortent jamais du dossier de sortie (`export`, `extract`, `merge`).
+
+Tests : `pytest` (dossier `cli/`, 68 tests) ; le corpus négatif de `tests/invalid/` (63 cas, un par règle) est régénéré par `python tests/invalid/build.py`. Tokens : installer `tiktoken` pour un comptage exact (sinon heuristique par caractères).

cof_cli-1.1.0/README.md

@@ -0,0 +1,29 @@
+# cof-cli
+
+Outil de référence pour COF (Character Open File) : validation, empaquetage, extraction, fusion, conversions, et l'ajout d'un souvenir vécu (1.1). `pip install cof-cli` (PyPI) ou, depuis ce dossier, `pip install -e ".[dev]"`. Python ≥ 3.10.
+
+```bash
+cof validate spec/examples/10-clara-mercier        # dossier ou fichier .cof : erreurs, avertissements, complétude (--json pour la CI)
+cof pack spec/examples/10-clara-mercier -o clara.cof   # recalcule hashes, complétude, langues ; écrit COF.md et la vignette
+cof info clara.cof                                  # presets, déclinaisons, âges, tags — le point de départ pour un agent
+cof unpack clara.cof -o clara/
+cof tokens clara.cof
+cof extract clara.cof --preset fr-65 -o clara-65/   # une tranche plus légère : un preset, un personnage (--identity) ou des tags (--tag fr --tag age-65)
+cof extract clara.cof --identity clara-mercier --all-audiences -o clara-sfw/   # sans nudité ni intime, médias des souvenirs explicites retirés (gist conservé)
+cof extract clara.cof --preset default --keep-personal -o clara-perso/         # garde les souvenirs `visibility: personal` (retirés par défaut)
+cof merge clara.cof martien.cof -o duo/             # un casting : même nom + surnom + statut fictif + morphologie ⇒ même personnage, sinon plusieurs
+cof memory add clara.cof --gist fr="Ce matin, relu avec Léo." --gist en="This morning, reread with Léo." --date 2026-10-25 --who "Léo" --tag travail --personal
+cof memory add clara/ --kind period --gist en="The agency years." --age 24 --approx --fidelity faded   # sur un dossier ; `--help` liste tout (--where, --self-shown, --media, --preset…)
+cof import carte.png -o perso/ --age 30 --lang fr --keep-png   # carte PNG CCv2/V3 → dossier COF
+cof export clara.cof --format png -o clara.png      # → PNG avec chunks chara + ccv3
+cof export clara.cof --format card -o clara.card.json
+cof export clara.cof --format soul -o ./agent/      # → SOUL.md + IDENTITY.md
+cof export clara.cof --format agent -o ./agent/     # → espace de travail d'agent : SOUL.md, IDENTITY.md, skills/, MEMORY.md + memories/ (--keep-personal, --preset)
+cof embed-text clara.png fiche.md -o clara-fiche.png   # texte descriptif dans un PNG (iTXt), lisible par le builder
+cof read-text clara-fiche.png
+cof migrate dossier-v0.5/                           # v0.2 … v0.5 → 1.0
+```
+
+Ce que `validate` vérifie : la structure de l'archive (sentinelle `mimetype`, chemins sûrs, pas d'entrée en double ni chiffrée, taux de compression, taille), les hashes SHA-256 et tailles des assets, les schémas JSON du manifeste et des sous-fichiers (`card`, `psyche`, `weights`, `voice-profile`, `memory`…), la résolution des presets (slots, alternatives, `extends`, `derives_from`), les identifiants d'assets et de déclinaisons, les règles d'âge sur l'**âge le plus bas** d'un preset (déclinaisons appliquées et offertes, `age_override`, souvenirs qui montrent le personnage), l'interdiction de tout contenu nu ou intime sous 18 ans, le consentement d'une personne réelle, les règles des souvenirs (RFC 0002 : forme de `when`, liens, `media_from`, nœuds explicites — qui est montré, âges connus et adultes, âge vécu ≥ 18, drapeau `nudity`, `tags.content`), les relations entre personnages d'un casting (RFC 0003), les styles mélangés, les transcriptions des échantillons de voix, le contenu exécutable non déclaré, les doublons, les budgets de tokens ; puis recalcule la complétude et les cibles prêtes. Les chemins et noms lus dans un manifeste ne sortent jamais du dossier de sortie (`export`, `extract`, `merge`).
+
+Tests : `pytest` (dossier `cli/`, 68 tests) ; le corpus négatif de `tests/invalid/` (63 cas, un par règle) est régénéré par `python tests/invalid/build.py`. Tokens : installer `tiktoken` pour un comptage exact (sinon heuristique par caractères).

{cof_cli-1.0.0 → cof_cli-1.1.0}/cof_cli/__init__.py

@@ -1,5 +1,5 @@
 """cof-cli — reference tooling for COF (Character Open File)."""
 
-__version__ = "1.0.0"
+__version__ = "1.1.0"
 MIMETYPE = "application/vnd.cof.character+zip"
-SPEC_VERSION = "1.0"
+SPEC_VERSION = "1.1"

cof_cli-1.1.0/cof_cli/cast.py

@@ -0,0 +1,291 @@
+"""RFC 0003 (1.1): gender, archetype, narrative role, relations between characters.
+
+Shared by the validator (vocabularies, cast rules, coherence), the exports (IDENTITY.md / SOUL.md lines)
+and `extract --identity` (relations whose target leaves the file).
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .model import resolve_preset_slots, resolve_variant
+
+GENDERS = ("female", "male", "non-binary", "none", "other")
+RELATION_TYPES = ("parent", "child", "sibling", "partner", "ex-partner", "spouse", "friend", "colleague", "mentor", "student",
+                  "rival", "enemy", "acquaintance", "creator", "creation", "owner", "pet", "other")
+SYMMETRIC = {"sibling", "partner", "ex-partner", "spouse", "friend", "colleague", "rival", "enemy", "acquaintance"}
+INVERSE = {"parent": "child", "child": "parent", "mentor": "student", "student": "mentor", "creator": "creation", "creation": "creator",
+           "owner": "pet", "pet": "owner"}
+ARCHETYPES = ("innocent", "everyman", "hero", "caregiver", "explorer", "rebel", "lover", "creator", "jester", "sage", "magician", "ruler")
+ROLES = ("protagonist", "antagonist", "mentor", "ally", "sidekick", "foil", "love-interest", "narrator", "ensemble", "other")
+
+GENDER_WORDS = {"en": {"female": "female", "male": "male", "non-binary": "non-binary", "none": "no gender (entity)", "other": "other"},
+                "fr": {"female": "féminin", "male": "masculin", "non-binary": "non binaire", "none": "sans genre (entité)", "other": "autre"}}
+ARCHETYPE_WORDS = {"en": {"innocent": "the Innocent", "everyman": "the Everyman", "hero": "the Hero", "caregiver": "the Caregiver", "explorer": "the Explorer",
+                          "rebel": "the Rebel", "lover": "the Lover", "creator": "the Creator", "jester": "the Jester", "sage": "the Sage",
+                          "magician": "the Magician", "ruler": "the Ruler"},
+                   "fr": {"innocent": "l'Innocent", "everyman": "le Citoyen ordinaire", "hero": "le Héros", "caregiver": "le Protecteur", "explorer": "l'Explorateur",
+                          "rebel": "le Rebelle", "lover": "l'Amoureux", "creator": "le Créateur", "jester": "le Bouffon", "sage": "le Sage",
+                          "magician": "le Magicien", "ruler": "le Souverain"}}
+RELATION_WORDS = {"en": {t: t.replace("-", " ") for t in RELATION_TYPES},
+                  "fr": {"parent": "parent", "child": "enfant", "sibling": "frère / sœur", "partner": "partenaire", "ex-partner": "ex-partenaire", "spouse": "époux / épouse",
+                         "friend": "ami(e)", "colleague": "collègue", "mentor": "mentor", "student": "élève", "rival": "rival(e)", "enemy": "ennemi(e)",
+                         "acquaintance": "connaissance", "creator": "créateur", "creation": "création", "owner": "maître", "pet": "animal", "other": "autre"}}
+ROLE_WORDS = {"en": {r: r.replace("-", " ") for r in ROLES},
+              "fr": {"protagonist": "protagoniste", "antagonist": "antagoniste", "mentor": "mentor", "ally": "allié(e)", "sidekick": "acolyte", "foil": "faire-valoir",
+                     "love-interest": "intérêt amoureux", "narrator": "narrateur", "ensemble": "ensemble", "other": "autre"}}
+
+# the voice profile's gender_presentation vocabulary (voice-profile.schema.json) mapped onto RFC 0003 genders
+VOICE_TO_GENDER = {"feminine": "female", "masculine": "male", "female": "female", "male": "male"}    # androgynous / neutral never conflict (RFC 0003 § 6)
+
+
+def text_in(m, lang: str | None) -> str:
+    """A language-map entry: the language, else its base, else the first (RFC 0002 § 3 reading rule, short texts)."""
+    if isinstance(m, str):
+        return m
+    if not isinstance(m, dict) or not m:
+        return ""
+    if lang:
+        if lang in m:
+            return m[lang]
+        base = lang.lower().split("-")[0]
+        for k, v in m.items():
+            if k.lower().split("-")[0] == base:
+                return v
+    return next(iter(m.values()))
+
+
+OVERRIDABLE = ("name", "given_name", "family_name", "nicknames", "gender", "gender_label", "summary")
+
+
+def identity_override(manifest: dict, pid: str | None) -> dict:
+    """The preset chain's identity_override, merged field by field (nearest declaration wins) — RFC 0003 § 4."""
+    presets = manifest.get("presets") or {}
+    out, q, seen = {}, pid, set()
+    while q and q in presets and q not in seen:
+        seen.add(q)
+        for k, v in (presets[q].get("identity_override") or {}).items():
+            if k in OVERRIDABLE and k not in out and v is not None:
+                out[k] = v
+        q = presets[q].get("extends")
+    return out
+
+
+def identity_view(manifest: dict, pid: str | None, iid: str | None = None) -> dict:
+    """The identity as presented by a preset: the identity's record with the override applied (never morphology, fictional, consent, rights)."""
+    presets = manifest.get("presets") or {}
+    if iid is None and pid and pid in presets:
+        iid = presets[pid].get("identity") or manifest.get("default_identity")
+    base = dict((manifest.get("identities") or {}).get(iid or "", {}) or {})
+    if not base:                                   # a root-only 1.0 file: the character's record is the root copy (SPEC § 2.1)
+        base = {k: manifest[k] for k in ("name", "nickname", "summary", "fictional", "morphology", "language", "rights") if k in manifest}
+    base.update(identity_override(manifest, pid))
+    return base
+
+
+def preset_prompts(manifest: dict, pid: str | None) -> dict:
+    """The preset's own default prompts (`scene`, `greeting`) — not inherited through extends: a scene fits one presentation (RFC 0003 § 4 bis)."""
+    p = (manifest.get("presets") or {}).get(pid or "") or {}
+    return {k: v for k, v in (p.get("prompts") or {}).items() if k in ("scene", "greeting") and v}
+
+
+def preset_gender(manifest: dict, pid: str | None, iid: str | None = None) -> str | None:
+    """identity_override.gender of the preset chain (nearest wins), else the identity's gender, else None (RFC 0003 § 4)."""
+    return identity_view(manifest, pid, iid).get("gender")
+
+
+def nicknames(i: dict) -> list[str]:
+    """Every nickname: `nicknames` (1.1) else `nickname` (1.0), semicolon-separated values accepted."""
+    out = list(i.get("nicknames") or [])
+    if not out and i.get("nickname"):
+        out = [x.strip() for x in str(i["nickname"]).split(";") if x.strip()]
+    return out
+
+
+def uses_1_1_fields(manifest: dict, src: Path | None = None) -> list[str]:
+    """Which RFC 0003 fields a manifest uses (for the 'declare 1.1' rule)."""
+    used = []
+    for iid, i in (manifest.get("identities") or {}).items():
+        for k in ("gender", "gender_label", "relations", "given_name", "family_name", "nicknames"):
+            if (i or {}).get(k) is not None:
+                used.append(f"identities.{iid}.{k}")
+    for pid, p in (manifest.get("presets") or {}).items():
+        if (p or {}).get("identity_override") is not None:
+            used.append(f"presets.{pid}.identity_override")
+        if (p or {}).get("prompts") is not None:
+            used.append(f"presets.{pid}.prompts")
+    if src is not None:
+        for vid, v in (((manifest.get("elements") or {}).get("personality") or {}).get("variants") or {}).items():
+            if v.get("psyche") and (src / v["psyche"]).is_file():
+                try:
+                    ps = json.loads((src / v["psyche"]).read_text("utf-8"))
+                except Exception:
+                    continue
+                for k in ("archetype", "role"):
+                    if ps.get(k) is not None:
+                        used.append(f"personality.{vid}.psyche.{k}")
+    return used
+
+
+def cast_rules(manifest: dict, src: Path, rep) -> None:
+    """Errors and warnings of RFC 0003 § 6 (vocabularies are enforced by the schema; this is what the schema cannot say)."""
+    ids = manifest.get("identities") or {}
+    for iid, i in ids.items():
+        i = i or {}
+        if i.get("gender") == "other" and not i.get("gender_label"):
+            rep.warnings.append(f"identities.{iid}: gender 'other' without gender_label")
+        for n, r in enumerate(i.get("relations") or []):
+            where = f"identities.{iid}.relations[{n}]"
+            to = r.get("to")
+            if to == iid:
+                rep.errors.append(f"{where}: a relation to oneself")
+            elif to not in ids:
+                rep.errors.append(f"{where}: unknown identity {to!r} (a relation names another character of the same file)")
+            if r.get("type") == "other" and not r.get("label"):
+                rep.errors.append(f"{where}: type 'other' needs a label")
+        pairs = [(r.get("to"), r.get("type")) for r in i.get("relations") or []]
+        for pr in {x for x in pairs if pairs.count(x) > 1}:
+            rep.errors.append(f"identities.{iid}.relations: the same relation twice ({pr[1]} → {pr[0]}); two relations to one character must differ in type (colleague and friend)")
+        if i.get("nicknames") and i.get("nickname") and i["nickname"] not in i["nicknames"]:
+            rep.warnings.append(f"identities.{iid}: nickname {i['nickname']!r} is not among nicknames — 1.0 readers see `nickname`, keep it the first of `nicknames`")
+        if i.get("given_name") and i.get("name") and i["given_name"].lower() not in i["name"].lower():
+            rep.warnings.append(f"identities.{iid}: given_name {i['given_name']!r} does not appear in name {i['name']!r}")
+    for pid, p in (manifest.get("presets") or {}).items():
+        ov = (p or {}).get("identity_override") or {}
+        if ov.get("gender") == "other" and not ov.get("gender_label") and not (ids.get((p or {}).get("identity") or manifest.get("default_identity") or "", {}) or {}).get("gender_label"):
+            rep.warnings.append(f"presets.{pid}.identity_override: gender 'other' without gender_label")
+    # both sides stored: they must agree (coherence)
+    for iid, i in ids.items():
+        for r in (i or {}).get("relations") or []:
+            to, ty = r.get("to"), r.get("type")
+            if to not in ids or to == iid:
+                continue
+            back = [b for b in ((ids[to] or {}).get("relations") or []) if b.get("to") == iid]
+            if not back or r.get("mutual") is False or any(b.get("mutual") is False for b in back):     # a one-sided relation is declared on purpose
+                continue
+            want = ty if ty in SYMMETRIC else INVERSE.get(ty)
+            if want and all(b.get("type") != want for b in back):
+                rep.warnings.append(f"identities.{iid}.relations → {to}: '{ty}' on this side, {[b.get('type') for b in back]} on the other — the two sides disagree (coherence)")
+    # a relation that began after the age the preset shows (coherence, RFC 0003 § 6)
+    from .model import preset_age, preset_owner
+    for pid in (manifest.get("presets") or {}):
+        pa = preset_age(manifest, pid, ignore={"memories"})
+        oid = preset_owner(manifest, pid)
+        if pa is None or not oid:
+            continue
+        for r in ((ids.get(oid) or {}).get("relations") or []):
+            sa = ((r.get("since") or {}).get("age") or {}).get("value") if isinstance(r.get("since"), dict) else None
+            if isinstance(sa, (int, float)) and sa > pa:
+                rep.warnings.append(f"presets.{pid}: relation {r.get('type')} → {r.get('to')} began at {sa:g}, after the age this preset shows ({pa:g}) — the character does not know that person yet (coherence)")
+    # preset gender vs the voice's presentation (never blocking)
+    for pid, p in (manifest.get("presets") or {}).items():
+        g = preset_gender(manifest, pid)
+        if not g or g in ("none", "other"):
+            continue
+        slots = resolve_preset_slots(manifest, pid)
+        for vid in slots.get("voice") or []:
+            v = resolve_variant(manifest, "voice", vid) or {}
+            if not v.get("profile") or not (src / v["profile"]).is_file():
+                continue
+            try:
+                prof = json.loads((src / v["profile"]).read_text("utf-8"))
+            except Exception:
+                continue
+            if not isinstance(prof, dict) or not isinstance(prof.get("canonical"), dict):
+                continue
+            gp = str(((prof.get("canonical") or {}).get("gender_presentation") or "")).lower()
+            vg = VOICE_TO_GENDER.get(gp)
+            if vg and vg != g and g in ("female", "male"):      # only female × masculine and male × feminine are conflicts
+                rep.warnings.append(f"presets.{pid}: gender {g} but voice {vid} presents as {gp} (coherence, not an error: a voice may differ on purpose)")
+
+
+def relations_of(manifest: dict, iid: str) -> list[dict]:
+    """The relations of a character, stored on either side: own entries, plus the inverse of what others declare (RFC 0003 § 3)."""
+    ids = manifest.get("identities") or {}
+    out = [dict(r, _stored=True) for r in ((ids.get(iid) or {}).get("relations") or []) if r.get("to") in ids and r.get("to") != iid]
+    seen = {(r["to"], r.get("type")) for r in out}
+    for oid, o in ids.items():
+        if oid == iid:
+            continue
+        for r in (o or {}).get("relations") or []:
+            if r.get("to") != iid or r.get("mutual") is False:
+                continue
+            ty = r.get("type")
+            inv = ty if ty in SYMMETRIC else INVERSE.get(ty)
+            if inv and inv != "other" and (oid, inv) not in seen:
+                out.append({"to": oid, "type": inv, "_stored": False, "_declared_by": oid})     # the label and `since` are the other side's words and age: not carried over
+                seen.add((oid, inv))
+    return out
+
+
+def drop_foreign_relations(manifest: dict) -> list[str]:
+    """After an extract: relations whose target is no longer an identity of the file leave; returns what was dropped."""
+    ids = manifest.get("identities") or {}
+    gone = []
+    for iid, i in ids.items():
+        rel = (i or {}).get("relations")
+        if not rel:
+            continue
+        keep = [r for r in rel if r.get("to") in ids and r.get("to") != iid]
+        for r in rel:
+            if r not in keep:
+                gone.append(f"identities.{iid} → {r.get('to')} ({r.get('type')})")
+        if keep:
+            i["relations"] = keep
+        else:
+            i.pop("relations", None)
+    return gone
+
+
+def identity_lines(manifest: dict, iid: str, pid: str | None, lang: str) -> list[str]:
+    """Lines for IDENTITY.md / a character card: gender (preset override first), relations."""
+    L = "fr" if str(lang).lower().startswith("fr") else "en"
+    i = identity_view(manifest, pid, iid)
+    base = (manifest.get("identities") or {}).get(iid) or {}
+    out = []
+    nk = nicknames(i)
+    if nk:
+        out.append(("Surnoms" if L == "fr" else "Nicknames") + ": " + ", ".join(nk))
+    g = preset_gender(manifest, pid, iid)
+    if g:
+        word = GENDER_WORDS[L].get(g, g)
+        lab = text_in(i.get("gender_label"), lang)
+        if g == "other" and lab:
+            word = lab
+        elif lab:
+            word += f" ({lab})"
+        if base.get("gender") and g != base.get("gender"):
+            word += " — " + ("dans ce preset" if L == "fr" else "in this preset") + f" ({GENDER_WORDS[L].get(base['gender'], base['gender'])} " + ("au canon" if L == "fr" else "in canon") + ")"
+        out.append(("Genre" if L == "fr" else "Gender") + f": {word}")
+    rels = relations_of(manifest, iid)
+    if rels:
+        ids = manifest.get("identities") or {}
+        items = []
+        for r in rels:
+            name = (ids.get(r["to"]) or {}).get("name") or r["to"]
+            word = RELATION_WORDS[L].get(r["type"], r["type"])
+            lab = text_in(r.get("label"), lang)
+            items.append(f"{name} — {word}" + (f" ({lab})" if lab else "") + ((" (" + ("déclaré par " if L == "fr" else "declared by ") + name + ")") if r.get("_declared_by") else ""))
+        out.append("Relations: " + " · ".join(items))
+    return out
+
+
+def psyche_lines(psyche: dict | None, lang: str) -> list[str]:
+    """Lines for SOUL.md: the archetype and the role (RFC 0003 § 5)."""
+    if not psyche:
+        return []
+    L = "fr" if str(lang).lower().startswith("fr") else "en"
+    out = []
+    a = psyche.get("archetype")
+    if isinstance(a, dict) and a.get("value"):
+        word = text_in(a.get("label"), lang) or (ARCHETYPE_WORDS[L].get(a["value"], a["value"]) if a.get("model") == "pearson-12" else a["value"])
+        sec = [ARCHETYPE_WORDS[L].get(x, x) for x in (a.get("secondary") or [])]
+        line = ("Archétype" if L == "fr" else "Archetype") + f": {word}"
+        if sec:
+            line += " (" + ("secondaire" if L == "fr" else "secondary") + ": " + ", ".join(sec) + ")"
+        if a.get("model") == "pearson-12":
+            line += " — Mark & Pearson" if L == "en" else " — modèle Mark & Pearson"
+        out.append(line)
+    if psyche.get("role"):
+        out.append(("Rôle narratif" if L == "fr" else "Narrative role") + f": {ROLE_WORDS[L].get(psyche['role'], psyche['role'])}")
+    return out

{cof_cli-1.0.0 → cof_cli-1.1.0}/cof_cli/cli.py

@@ -3,6 +3,10 @@ from __future__ import annotations
 
 import argparse
 import json
+import zipfile
+import shutil
+import math
+import re
 import sys
 import tempfile
 from pathlib import Path
@@ -73,6 +77,9 @@ def cmd_pack(a):
         from datetime import datetime, timezone
         manifest.setdefault("provenance", {})["modified"] = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
         (src / "manifest.json").write_text(json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", "utf-8")
+    if manifest and not getattr(a, "no_readme", False):
+        from .selfdesc import write_self_description
+        write_self_description(src, manifest)                     # COF.md: the container describes itself (never normative)
     out = Path(a.out) if a.out else src.with_suffix(".cof")
     try:
         pack(src, out)
@@ -158,6 +165,11 @@ def cmd_import(a):
     return _print_report(rep, a.json)
 
 
+def _fname(manifest: dict) -> str:
+    """A default output name from the character's name: a plain file name, never a path."""
+    return re.sub(r"[^A-Za-z0-9._-]+", "-", str(manifest.get("name") or "character")).strip("-.") or "character"
+
+
 def cmd_export(a):
     src = Path(a.src)
     with tempfile.TemporaryDirectory() as td:
@@ -179,7 +191,7 @@ def cmd_export(a):
                 png = (d / head).read_bytes()
             else:
                 png = _placeholder_png(d / head if head else None)
-            out = out or Path(f"{manifest['name']}.png")
+            out = out or Path(f"{_fname(manifest)}.png")
             out.write_bytes(write_card_to_png(png, card))
         elif fmt == "soul":
             soul, identity = export_soul(d, pid)
@@ -189,12 +201,14 @@ def cmd_export(a):
             (out / "IDENTITY.md").write_text(identity, "utf-8")
         elif fmt == "agent":
             from .convert import export_agent
-            out = out or Path(f"{manifest['name']}-agent")
-            done = export_agent(d, out, pid)
-            print(f"skills: {', '.join(done['skills']) or '—'} · memories: {len(done['memories'])} · documents: {len(done['documents'])}")
+            out = out or Path(f"{_fname(manifest)}-agent")
+            done = export_agent(d, out, pid, keep_personal=getattr(a, "keep_personal", False))
+            print(f"skills: {', '.join(done['skills']) or '—'} · memory files: {len(done['memories'])} · memories (nodes): {done.get('memory_nodes', 0)} · documents: {len(done['documents'])}")
+            if done.get("personal_dropped"):
+                print(f"personal memories not exported: {done['personal_dropped']} (--keep-personal exports them)")
         elif fmt == "card":
             card = json.loads((d / card_path).read_text("utf-8"))
-            out = out or Path(f"{manifest['name']}.card.json")
+            out = out or Path(f"{_fname(manifest)}.card.json")
             out.write_text(json.dumps(card, ensure_ascii=False, indent=2), "utf-8")
         else:
             print(f"unsupported format: {fmt}", file=sys.stderr)
@@ -205,34 +219,90 @@ def cmd_export(a):
 
 def cmd_merge(a):
     dirs = []
-    for src in a.sources:
-        p = Path(src)
-        if p.is_file():
-            td = Path(tempfile.mkdtemp()); unpack(p, td); dirs.append(td)
-        else:
-            dirs.append(p)
-    merge_dirs(dirs, Path(a.out))
+    with tempfile.TemporaryDirectory(prefix="cof-merge-") as td:
+        for i, src in enumerate(a.sources):
+            p = Path(src)
+            if p.is_file():
+                d = Path(td) / str(i); unpack(p, d); dirs.append(d)
+            else:
+                dirs.append(p)
+        merge_dirs(dirs, Path(a.out))
     rep = Report(); validate_dir(Path(a.out), rep, recompute=True)
     Path(a.out, "manifest.json").write_text(json.dumps(json.loads(Path(a.out, "manifest.json").read_text("utf-8")) | {}, ensure_ascii=False, indent=2) + "\n", "utf-8")
     print(f"merged into: {a.out}")
     return _print_report(rep, a.json)
 
 
+def cmd_memory_add(a):
+    import tempfile
+    from .selfdesc import memory_add, write_self_description
+    gists = {}
+    for g in a.gist:
+        if "=" not in g:
+            print("ERROR  --gist expects LANG=TEXT (e.g. fr=\"…\")", file=sys.stderr); return 2
+        k, v = g.split("=", 1); gists[k.strip()] = v.strip()
+    src = Path(a.src)
+    if not src.exists():
+        print(f"ERROR  {src}: no such file or folder", file=sys.stderr); return 2
+    if a.age is not None and not (math.isfinite(a.age) and 0 <= a.age <= 200):
+        print("ERROR  --age must be a number of years between 0 and 200", file=sys.stderr); return 2
+    is_file = src.is_file()
+    tmp = tempfile.TemporaryDirectory(prefix="cof-mem-")             # a folder is edited through a copy: nothing lands in it unless the result validates
+    work = Path(tmp.name) / "x"
+    try:
+        if is_file:
+            unpack(src, work)
+        else:
+            shutil.copytree(src, work)
+        vid = memory_add(work, identity=a.identity, kind=a.kind, gists=gists, label=a.label, age=a.age, date=a.date, approx=a.approx, where=a.where,
+                         who=a.who, tags=a.tag, personal=a.personal, origin=a.origin, disclosure=a.disclosure, fidelity=a.fidelity, salience=a.salience,
+                         media=[Path(x) for x in (a.media or [])], presets=a.preset, self_shown=a.self_shown)
+        rep = Report()
+        manifest = validate_dir(work, rep, recompute=True)
+        if rep.errors:
+            _print_report(rep, False); print("Memory not added: the file would not validate.", file=sys.stderr); return 1
+        if manifest:
+            (work / "manifest.json").write_text(json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", "utf-8")
+            write_self_description(work, manifest)
+        if is_file:
+            out = Path(a.out) if a.out else src
+            pack(work, out)
+            print(f"added {vid} → {out}")
+        else:
+            shutil.copytree(work, src, dirs_exist_ok=True)
+            print(f"added {vid} in {src}")
+        for w in rep.warnings:
+            print(f"WARN   {w}")
+        return 0
+    except (ValueError, ContainerError) as e:
+        print(f"ERROR  {e}", file=sys.stderr); return 2
+    finally:
+        tmp.cleanup()
+
+
 def cmd_extract(a):
     src = Path(a.src)
     with tempfile.TemporaryDirectory() as td:
         d = src if src.is_dir() else unpack(src, td)
+        notes: list[str] = []
         if a.tag:
             extract_tag(d, Path(a.out), a.tag)
         elif getattr(a, "identity", None):
             from .ops import extract_identity
-            extract_identity(d, Path(a.out), a.identity)
+            extract_identity(d, Path(a.out), a.identity, notes)
         else:
             extract_preset(d, Path(a.out), a.preset)
+        for n in notes:
+            print(f"WARN   {n}")
+        if not getattr(a, "keep_personal", False):           # RFC 0002 § 5.7: personal memories never travel unasked
+            from .ops import drop_personal_memories
+            dropped = drop_personal_memories(Path(a.out))
+            if dropped:
+                print(f"personal memories dropped: {', '.join(dropped)} (--keep-personal keeps them)")
         if getattr(a, "no_intimate", False):
             from .ops import strip_intimate
             gone = strip_intimate(Path(a.out))
-            print(f"--no-intimate: removed {', '.join(gone) or 'nothing'}; allowSexualUsage set to false — review tags.content")
+            print(f"--all-audiences: removed {', '.join(gone) or 'nothing'}; allowSexualUsage set to false — review tags.content")
     rep = Report(); validate_dir(Path(a.out), rep, recompute=True)
     what = 'tags ' + '+'.join(a.tag) if a.tag else ('character ' + a.identity if getattr(a, "identity", None) else 'preset ' + a.preset)
     print(f"{what} extracted to: {a.out}")
@@ -282,23 +352,41 @@ def main(argv=None) -> int:
 
     s = sub.add_parser("validate", help="validate a .cof or a character folder"); s.add_argument("path"); s.add_argument("--json", action="store_true"); s.set_defaults(fn=cmd_validate)
     s = sub.add_parser("pack", help="folder → .cof (recomputes hashes and completeness)"); s.add_argument("dir"); s.add_argument("-o", "--out"); s.add_argument("--force", action="store_true"); s.add_argument("--json", action="store_true"); s.set_defaults(fn=cmd_pack)
+    s = sub.add_parser("memory", help="memories: `memory add` appends a lived memory to a .cof or a folder (RFC 0002, the write path of COF.md)")
+    ms = s.add_subparsers(dest="mcmd", required=True)
+    ma = ms.add_parser("add", help="append one memory node"); ma.add_argument("src", help=".cof file or character folder")
+    ma.add_argument("--identity", help="character id (default: the file's default character)"); ma.add_argument("--kind", choices=["moment", "period"], default="moment")
+    ma.add_argument("--gist", action="append", required=True, metavar="LANG=TEXT", help="the memory in one paragraph; repeat per language")
+    ma.add_argument("--label"); ma.add_argument("--age", type=float); ma.add_argument("--date", help="YYYY, YYYY-MM or YYYY-MM-DD"); ma.add_argument("--approx", action="store_true")
+    ma.add_argument("--where"); ma.add_argument("--who", action="append", metavar="LABEL[|shown][|AGE][|real]", help="a person: label, then optional words 'shown' (appears in a media), their age, 'real' (a real person who is not a character of the file); repeat");
+    ma.add_argument("--self-shown", action="store_true", help="the character appears in the media (requires --age: the minor rules read it)"); ma.add_argument("--tag", action="append")
+    ma.add_argument("--personal", action="store_true", help="visibility: personal (one user's data) instead of canon"); ma.add_argument("--origin", choices=["lived", "authored"], default="lived")
+    ma.add_argument("--disclosure", choices=["open", "guarded", "secret"], default="open"); ma.add_argument("--fidelity", choices=["vivid", "clear", "faded", "fragment"], default="clear"); ma.add_argument("--salience", type=int)
+    ma.add_argument("--media", action="append", help="image / audio / video / short text file; repeat"); ma.add_argument("--preset", action="append", help="preset(s) that may recall it (default: the character's presets)")
+    ma.add_argument("-o", "--out", help="output .cof (default: in place)"); ma.set_defaults(fn=cmd_memory_add)
     s = sub.add_parser("unpack", help=".cof → folder"); s.add_argument("cof"); s.add_argument("-o", "--out"); s.set_defaults(fn=cmd_unpack)
     s = sub.add_parser("info", help="summary of a .cof"); s.add_argument("cof"); s.set_defaults(fn=cmd_info)
     s = sub.add_parser("tokens", help="token estimate per block"); s.add_argument("path"); s.set_defaults(fn=cmd_tokens)
     s = sub.add_parser("embed-text", help="write a text (.md/.txt) into a PNG as iTXt 'Description' — readable by the builder (personality + appearance)"); s.add_argument("png"); s.add_argument("text"); s.add_argument("-o", "--out"); s.set_defaults(fn=cmd_embed_text)
     s = sub.add_parser("read-text", help="show the descriptive text embedded in an image (PNG/JPEG: iTXt, XMP, EXIF)"); s.add_argument("image"); s.set_defaults(fn=cmd_read_text)
     s = sub.add_parser("import", help="PNG/JSON card (CCv2/V3) → COF folder"); s.add_argument("src"); s.add_argument("-o", "--out"); s.add_argument("--age", type=int); s.add_argument("--real", action="store_true", help="character based on a real person (consent required)"); s.add_argument("--lang", default="en"); s.add_argument("--keep-png", action="store_true", help="keep the PNG as the head.front view"); s.add_argument("--json", action="store_true"); s.set_defaults(fn=cmd_import)
-    s = sub.add_parser("export", help="folder/.cof → png | soul | card | agent (workspace: SOUL.md, IDENTITY.md, skills/, memories) — from the default preset or --preset"); s.add_argument("src"); s.add_argument("--format", choices=["png", "soul", "card", "agent"], required=True); s.add_argument("-o", "--out"); s.add_argument("--preset"); s.set_defaults(fn=cmd_export)
+    s = sub.add_parser("export", help="folder/.cof → png | soul | card | agent (workspace: SOUL.md, IDENTITY.md, skills/, memories) — from the default preset or --preset"); s.add_argument("src"); s.add_argument("--format", choices=["png", "soul", "card", "agent"], required=True); s.add_argument("-o", "--out"); s.add_argument("--preset"); s.add_argument("--keep-personal", action="store_true", help="agent: also export `visibility: personal` memories (dropped by default)"); s.set_defaults(fn=cmd_export)
     s = sub.add_parser("migrate", help="folder v0.2 … v0.5 → v1.0"); s.add_argument("dir"); s.add_argument("--json", action="store_true"); s.set_defaults(fn=cmd_migrate)
     s = sub.add_parser("merge", help="merge several .cof files/folders (same name, nickname, fictional status and morphology class ⇒ same identity, otherwise multiple identities)"); s.add_argument("sources", nargs="+"); s.add_argument("-o", "--out", required=True); s.add_argument("--json", action="store_true"); s.set_defaults(fn=cmd_merge)
-    s = sub.add_parser("extract", help="extract a preset, a character (--identity), or the presets carrying one or more tags (intersection), into a lighter COF folder"); s.add_argument("src"); g = s.add_mutually_exclusive_group(required=True); g.add_argument("--preset"); g.add_argument("--identity", help="one character: all its presets, elements, files and rights"); g.add_argument("--tag", action="append", help="repeatable: --tag english --tag age-12"); s.add_argument("-o", "--out", required=True); s.add_argument("--json", action="store_true"); s.add_argument("--no-intimate", action="store_true", help="safe-for-work slice: drop intimate variants, allowSexualUsage = false"); s.set_defaults(fn=cmd_extract)
+    s = sub.add_parser("extract", help="extract a preset, a character (--identity), or the presets carrying one or more tags (intersection), into a lighter COF folder"); s.add_argument("src"); g = s.add_mutually_exclusive_group(required=True); g.add_argument("--preset"); g.add_argument("--identity", help="one character: all its presets, elements, files and rights"); g.add_argument("--tag", action="append", help="repeatable: --tag english --tag age-12"); s.add_argument("-o", "--out", required=True); s.add_argument("--json", action="store_true"); s.add_argument("--all-audiences", "--no-intimate", dest="no_intimate", action="store_true", help="all-audiences slice: drop intimate / nude variants and the media of explicit memories (gist kept), allowSexualUsage = false"); s.add_argument("--keep-personal", action="store_true", help="keep `visibility: personal` memories (a user's data; dropped by default)"); s.set_defaults(fn=cmd_extract)
 
     a = ap.parse_args(argv)
     try:
         return a.fn(a)
-    except (ContainerError, ValueError) as e:
+    except (ContainerError, ValueError) as e:                    # ValueError covers JSONDecodeError
         print(f"ERROR  {e}", file=sys.stderr)
         return 1
+    except zipfile.BadZipFile as e:
+        print(f"ERROR  not a .cof archive: {e}", file=sys.stderr)
+        return 1
+    except OSError as e:
+        print(f"ERROR  {e.strerror or e}: {e.filename or ''}".rstrip(": "), file=sys.stderr)
+        return 1
 
 
 if __name__ == "__main__":

{cof_cli-1.0.0 → cof_cli-1.1.0}/cof_cli/completeness.py

@@ -37,6 +37,8 @@ def compute_preset(manifest: dict, pid: str | None, src: Path | None = None) ->
     if p and p.get("kind") == "card" and p.get("card"):
         s += 30
         card = _load(src, p["card"]); d = (card or {}).get("data", {})
+        if not isinstance(d, dict):
+            d = {}
         if card is None and src is None:
             s += 25
         s += 10 * bool(d.get("description")) + 10 * bool(d.get("personality")) + 5 * bool(d.get("scenario")) + 10 * bool(d.get("first_mes")) + 10 * bool(d.get("mes_example"))