goanon

README

go-anon

Pipeline de reconnaissance d'entités nommées (NER) et d'anonymisation pour le français et l'anglais. Zéro dépendance externe — bibliothèque standard Go uniquement.

Installation

go get github.com/bornholm/go-anon

Utilisation rapide

import (
    "os"
    goanon "github.com/bornholm/go-anon"
)

// 1. Charger le modèle
f, err := os.Open("model_en.crf.gz")
if err != nil {
    log.Fatal(err)
}
defer f.Close()

m, err := goanon.LoadModel(f)
if err != nil {
    log.Fatal(err)
}

// 2. Construire le recognizer
r, err := goanon.NewRecognizer(m, goanon.WithLanguage("en"))
if err != nil {
    log.Fatal(err)
}

// 3. Détecter les entités
entities, err := r.Recognize("Marie Curie was born in Warsaw.")
// → [{Text:"Marie Curie", Type:"PER", Confidence:0.97}, {Text:"Warsaw", Type:"LOC", ...}]

// 4. Anonymiser
anon := goanon.NewAnonymizer(r, goanon.Config{Strategy: goanon.TagReplace})
result, err := anon.Anonymize("Marie Curie was born in Warsaw.")
// result.Text  → "[PERSON_1] was born in [LOCATION_1]."
// result.Mapping → {"[PERSON_1]": "Marie Curie", "[LOCATION_1]": "Warsaw"}

// 5. Dé-anonymiser
original, err := anon.Deanonymize(result.Text, result.Mapping)

Modèles

Les modèles ne sont pas inclus dans la librairie. Ils doivent être fournis explicitement via LoadModel. Utiliser cmd/train pour entraîner un modèle :

# Entraîner un modèle français
./bin/train \
  -train data/wikiner_fr_full.train.wikiner \
  -dev   data/wikiner_fr_full.dev.wikiner \
  -lang fr -format wikiner \
  -workers 1 -epochs 20 -lr 0.1 -l2 0.01 \
  -clusters data/brown_clusters_fr.txt \
  -prune-threshold 0.001 \
  -output model_fr.crf.gz

Langue	Code WithLanguage
Français	"fr"
Anglais	"en"

Stratégies d'anonymisation

Constante	Exemple	Description
TagReplace	[PERSON_1]	Remplacement par tag typé (défaut)
Redact	████	Caviardage caractère par caractère
Hash	[PER_a1b2c3]	Empreinte SHA-256 (6 hex)
Consistent	[PERSON_1]	Même entité → même placeholder

Filtres post-NER

r, _ := goanon.NewRecognizer(
    goanon.WithLanguage("fr"),
    goanon.WithPostFilters(
        goanon.MinConfidenceFilter(0.7),   // supprimer < 70 % de confiance
        goanon.MaxTokensFilter(5),          // supprimer les spans > 5 tokens
        goanon.BlocklistFilter(goanon.TypePER, "Monsieur", "Madame"),
    ),
)

Gazetteers et Brown clusters

import "os"

f, _ := os.Open("data/villes.txt")
gaz, _ := goanon.LoadGazetteer("cities", f)

fc, _ := os.Open("data/brown_clusters_fr.txt")
clusters, _ := goanon.LoadBrownClusters(fc)

r, _ := goanon.NewRecognizer(
    goanon.WithLanguage("fr"),
    goanon.WithGazetteers(map[string]*goanon.Gazetteer{"cities": gaz}),
    goanon.WithBrownClusters(clusters),
)

Outils en ligne de commande

go build -o bin/train        ./cmd/train/
go build -o bin/eval         ./cmd/eval/
go build -o bin/demo         ./cmd/demo/
go build -o bin/prune        ./cmd/prune/
go build -o bin/brown-cluster ./cmd/brown-cluster/

Outil	Description
train	Entraîner un modèle CRF sur un corpus CoNLL ou WikiNER
eval	Évaluer le F1 (strict type + span) sur un corpus de test
demo	Démo interactive / anonymisation depuis stdin
prune	Réduire un modèle existant sans ré-entraînement
brown-cluster	Générer des Brown clusters depuis un corpus

# Démo rapide (-model est obligatoire)
echo "Jean Dupont habite à Paris." | ./bin/demo -model model_fr.crf.gz -lang fr -anonymize

# Évaluation
./bin/eval -model model_fr.crf.gz -lang fr \
  -test data/wikiner_fr.test.conll -format conll

Architecture

texte brut
  → UnicodeTokenizer     (pkg/tokenizer)  — segmentation rune-par-rune, offsets byte-accurate
  → FeatureExtractor     (pkg/features)   — ~40-60 features/token : morpho, shape, contexte, clusters
  → CRF Viterbi          (pkg/model)      — décodage optimal en BIO
  → decodeEntities       (pkg/ner)        — reconstruction des spans avec scores de confiance
  → EntityFilter[]       (pkg/ner)        — post-filtres chaînables
  → Anonymizer           (pkg/anonymizer) — remplacement en ordre inverse des offsets

Packages

Package	Rôle
pkg/model	CRF linéaire : poids, Viterbi, forward-backward, SGD/Adam
pkg/features	Features : morphologie, shape, Brown clusters, gazetteers
pkg/ner	Orchestration NER, décodage BIO→entités, filtres
pkg/anonymizer	Remplacement et restauration des entités
pkg/corpus	Lecture CoNLL et WikiNER, conversion BIO/BIOES
pkg/tokenizer	UnicodeTokenizer — offsets byte-précis, FR/EN
pkg/lang	Profils linguistiques : stop-words, préfixes, abréviations

Points de vigilance

• Les offsets Start/End sont des positions byte UTF-8, pas des indices de caractères. Les caractères accentués (é, à) occupent 2 octets.
• workers > 1 avec peu de phrases cause une divergence Hogwild! — utiliser -workers 1 sur les petits corpus.
• Le modèle FR de production recommandé est entraîné avec prune-threshold 0.001 (F1 ≈ 82,4 % sur WikiNER).

Licence

Voir LICENSE.

Documentation

Overview

Package goanon fournit une API de haut niveau pour la reconnaissance d'entités nommées (NER) et l'anonymisation de texte en français et en anglais.

Usage minimal :

f, _ := os.Open("model.crf.gz")
m, err := goanon.LoadModel(f)
r, err := goanon.NewRecognizer(m, goanon.WithLanguage("fr"))
entities, err := r.Recognize("Jean Dupont habite à Paris.")

Anonymisation :

anon := goanon.NewAnonymizer(r, goanon.Config{Strategy: goanon.TagReplace})
result, err := anon.Anonymize("Jean Dupont habite à Paris.")
// result.Text == "[PERSON_1] habite à [LOCATION_1]."

Index

• Constants
• Variables
• type AnonymizePass
• type BrownClusters
• type Config
• type Entity
• type EntityFilter
• type EntityType
• type Gazetteer
• type Model
• type Recognizer
• type RecognizerOption
• type RegexPattern
• type ReplacerFunc
• type Result
• type Strategy

Constants

const (
	TypePER  = ner.TypePER
	TypeLOC  = ner.TypeLOC
	TypeORG  = ner.TypeORG
	TypeMISC = ner.TypeMISC

	TypeEMAIL = ner.TypeEMAIL
	TypeIPV4  = ner.TypeIPV4
	TypeIPV6  = ner.TypeIPV6
	TypeIBAN  = ner.TypeIBAN
	TypeSIRET = ner.TypeSIRET
	TypeSIREN = ner.TypeSIREN
	TypePHONE = ner.TypePHONE
)

const (
	TagReplace = anonymizer.TagReplace
	Redact     = anonymizer.Redact
	Hash       = anonymizer.Hash
	Consistent = anonymizer.Consistent
)

Variables

var BlocklistFilter = ner.BlocklistFilter

var BuiltinRegexPatterns = ner.BuiltinRegexPatterns

var ConsistencyPass = anonymizer.ConsistencyPass

var DefaultSentenceBoundaries = ner.DefaultSentenceBoundaries

var FirstNameDetectionFilter = ner.FirstNameDetectionFilter

var FirstNameReclassifyFilter = ner.FirstNameReclassifyFilter

var LoadBrownClusters = features.LoadBrownClusters

var LoadGazetteer = features.LoadGazetteer

var LoadModel = ner.LoadModel

LoadModel charge un modèle CRF sérialisé depuis r (format gob+gzip).

var MaxTokensFilter = ner.MaxTokensFilter

var MergePass = ner.MergePass

var MinConfidenceFilter = ner.MinConfidenceFilter

var NameCompletionPass = ner.NameCompletionPass

var NewAnonymizer = anonymizer.New

NewAnonymizer crée un Anonymizer qui s'appuie sur le Recognizer donné.

var NewRecognizer = ner.New

NewRecognizer construit un Recognizer NER avec le modèle m et les options fournies. Voir WithLanguage, WithGazetteers, WithBrownClusters, WithPostFilters.

var RegexEntityFilter = ner.RegexEntityFilter

var SurnameCompletionPass = anonymizer.SurnameCompletionPass

var WithBrownClusters = ner.WithBrownClusters

var WithBuiltinRegexPatterns = ner.WithBuiltinRegexPatterns

var WithFirstNameDetectionPass = ner.WithFirstNameDetectionPass

var WithFirstNameReclassify = ner.WithFirstNameReclassify

var WithGazetteers = ner.WithGazetteers

var WithLanguage = ner.WithLanguage

var WithMergePass = ner.WithMergePass

var WithNameCompletionPass = ner.WithNameCompletionPass

var WithPostFilters = ner.WithPostFilters

var WithRegexPatterns = ner.WithRegexPatterns

var WithSentenceBoundaries = ner.WithSentenceBoundaries

Types

type AnonymizePass

type AnonymizePass = anonymizer.AnonymizePass

type BrownClusters

type BrownClusters = features.BrownClusters

type Config

type Config = anonymizer.Config

type Entity

type Entity = ner.Entity

type EntityFilter

type EntityFilter = ner.EntityFilter

type EntityType

type EntityType = ner.EntityType

type Gazetteer

type Gazetteer = features.Gazetteer

type Model

type Model = ner.Model

type Recognizer

type Recognizer = anonymizer.Recognizer

type RecognizerOption

type RecognizerOption = ner.RecognizerOption

type RegexPattern

type RegexPattern = ner.RegexPattern

RegexPattern associe une expression régulière à un type d'entité.

type ReplacerFunc

type ReplacerFunc = anonymizer.ReplacerFunc

type Result

type Result = anonymizer.Result

type Strategy

type Strategy = anonymizer.Strategy