anon-lib 0.1.0__tar.gz

anon_lib-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+
+# distribuicao
+build/
+dist/
+*.egg-info/
+
+# ambiente e cache
+.venv/
+venv/
+.pytest_cache/
+config/.env
+*/.env

anon_lib-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wyctor Fogos da Rocha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

anon_lib-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: anon-lib
+Version: 0.1.0
+Summary: PII detection and masking for Brazilian Portuguese and English
+Project-URL: Homepage, https://github.com/wyctorfogos/anon-lib
+Project-URL: Issues, https://github.com/wyctorfogos/anon-lib/issues
+Author: Wyctor Fogos da Rocha
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anonymization,lgpd,ner,pii,portuguese
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Natural Language :: Portuguese (Brazilian)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.8.13
+Requires-Dist: langchain-text-splitters>=0.2
+Provides-Extra: dev
+Requires-Dist: ollama>=0.3; extra == 'dev'
+Requires-Dist: pydantic>=2; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: python-dotenv; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: ollama>=0.3; extra == 'llm'
+Requires-Dist: pydantic>=2; extra == 'llm'
+Description-Content-Type: text/markdown
+
+# Sentence-anonimizer
+
+Detects and masks personally identifiable information (PII) in free text, replacing
+each value with a stable tag and returning the tag → original value mapping.
+
+Supports Brazilian Portuguese (`pt-br`) and English (`en`).
+
+## How it works
+
+Two layers, and the split matters:
+
+| Layer | Finds | Guarantees |
+| --- | --- | --- |
+| **Regex** (always on) | Formatted data: CPF, CNPJ, e-mail, phone, credit card, CEP… | Deterministic. Same input, same output, no network. |
+| **LLM via Ollama** (opt-in) | Context-dependent data regex cannot express: names, places, organizations | Best effort. Recall varies between runs. |
+
+The LLM only **identifies** entities and returns them as structured JSON. The masking
+itself is always done in code, reusing the same tagging machinery as the regex layer.
+The model never rewrites your text, so it cannot silently drop or alter passages.
+
+## Install
+
+```bash
+pip install anon-lib            # regex layer only
+pip install "anon-lib[llm]"     # adds the optional LLM layer
+```
+
+The base install has a single dependency and never touches the network. `ollama` and
+`pydantic` come only with the `llm` extra and are imported lazily, so calling
+`use_llm=True` without them raises an actionable `ImportError` instead of a bare
+`ModuleNotFoundError`.
+
+The LLM layer also needs a running [Ollama](https://ollama.com) server with a model
+pulled:
+
+```bash
+ollama pull qwen3:0.6b
+```
+
+Point the library at it with the `llm_model_name` argument, or read it from your own
+config:
+
+```python
+Anonymizer(llm_model_name="qwen3:0.6b")
+```
+
+## Usage
+
+`anonimize_text` returns a `(masked_text, tags)` tuple. Every tag in the mapping is
+guaranteed to appear in the masked text.
+
+### Regex only (default)
+
+```python
+from anon_lib import Anonymizer
+
+anon = Anonymizer(language="pt-br")
+masked, tags = anon.anonimize_text(
+    "Contato: joao.silva@empresa.com.br, CPF 123.456.789-00, "
+    "CNPJ 12.345.678/0001-99, cel (11) 98765-4321."
+)
+```
+
+```
+Contato: [EMAIL_0], CPF [CPF_0], CNPJ [CNPJ_NUMERICO_FORMATADO_0], cel [TELEFONE_BR_0].
+
+{'[EMAIL_0]': 'joao.silva@empresa.com.br',
+ '[CPF_0]': '123.456.789-00',
+ '[CNPJ_NUMERICO_FORMATADO_0]': '12.345.678/0001-99',
+ '[TELEFONE_BR_0]': '(11) 98765-4321'}
+```
+
+### Regex + LLM
+
+```python
+masked, tags = anon.anonimize_text(
+    "Meu nome é Maria, moro na Rua das Flores, 123 e meu CPF é 111.222.333-44.",
+    use_llm=True,
+)
+```
+
+```
+Meu nome é [PERSON_NAME_0], moro na [LOCATION_0], 123 e meu CPF é [CPF_0].
+
+{'[CPF_0]': '111.222.333-44',
+ '[PERSON_NAME_0]': 'Maria',
+ '[LOCATION_0]': 'Rua das Flores'}
+```
+
+Note the house number `123` left unmasked: that is real output, and it illustrates why
+the regex layer is the one you rely on for guarantees.
+
+Run both layers end to end with `python examples/demo.py`.
+
+## Detected patterns
+
+**pt-br** — `CPF`, `CNPJ_NUMERICO_FORMATADO`, `CNPJ_ALFANUMERICO`, `CNPJ_NUMERICO`,
+`CNPJ_ALFANUMERICO_SEM_PONTUACAO`, `RG`, `PIS_PASEP`, `TITULO_ELEITOR`, `CNH`, `EMAIL`,
+`TELEFONE_BR`, `CEP`, `DATA`, `PLACA_VEICULO`, `PLACA_VEICULO_MERCOSUL`,
+`CARTAO_CREDITO`, `CARTAO_CREDITO_AMEX`, `CHAVE_PIX_ALEATORIA`, `AGENCIA`,
+`CONTA_BANCARIA`, `IP`
+
+**en** — `EMAIL`, `SSN`, `CREDIT_CARD`, `CREDIT_CARD_AMEX`, `US_PHONE`, `US_ZIP`, `IP`
+
+**LLM entity types** — `PERSON_NAME`, `LOCATION`, `ORGANIZATION`, `DATE`, `AGE`,
+`TIME`, `MONEY`, `PERCENT`, `FACILITY`, `GPE` (configurable via
+`list_of_undeterministics_entities`; the list is injected into the response schema as an
+enum, so the model cannot return a type outside it).
+
+## Design notes
+
+**Declaration order is priority.** Some values match several patterns — 11 bare digits
+are both a CPF and a mobile number. The first pattern declared wins, so formatted
+patterns come first and ambiguous bare numerics last.
+
+**Longest value is replaced first.** The leading 12 digits of a spaced credit card also
+match a voter ID. Replacing the shorter value first would corrupt the longer one.
+
+**Label-anchored patterns include the label.** `CNH`, `AGENCIA` and `CONTA_BANCARIA` mask
+the label too (`CNH: 12345678901` → `[CNH_0]`), because the bare number is
+indistinguishable from a CPF without it.
+
+**LLM values absent from the text are discarded.** A paraphrased or invented value would
+produce a no-op substitution while making the output *look* anonymized.
+
+## Known limitations
+
+- **No check-digit validation.** A well-formed but arithmetically invalid CPF is still
+  masked. For anonymization, over-detection is the safe side.
+- **`DATA` matches any `dd/mm/aaaa` date**, with no way to tell a birth date from any
+  other. Distinguishing them requires context, which is the LLM layer's job.
+- **`US_ZIP` matches any 5-digit number**, and bare 11-digit runs are inherently
+  ambiguous between CPF, CNH and mobile numbers.
+- **`MONEY`, `PERCENT` and `TIME` are not PII** and only add noise. Adjust
+  `list_of_undeterministics_entities` for your use case — the list is injected into the
+  response schema as an enum, so it is the effective control over what the model may
+  return.
+- **Tag numbering may skip an index.** When a short value is also a substring of a longer
+  masked one, it stays registered to catch standalone occurrences elsewhere. Dropping it
+  would leak PII.
+
+## Tests
+
+```bash
+pip install -e ".[dev]"   # needs Python 3.9+, as declared in pyproject.toml
+pytest        # 53 tests, hermetic: no server, no network (~2s)
+pytest -m llm # 3 prompt-regression tests against a real Ollama
+```
+
+The default suite stubs every LLM response, so it needs no server. The `llm` marker is
+deselected by default and holds the tests that call the model for real — they verify the
+prompt rules still take effect, which a stub cannot do, and skip themselves when Ollama
+or the model is unavailable.
+
+## Layout
+
+```text
+src/anon_lib/__init__.py                 public API: Anonymizer, __version__
+src/anon_lib/anonymizer.py               Anonymizer
+src/anon_lib/patterns/patterns.py        regex pattern tables, per language
+src/anon_lib/schemas/models_schemas.py   AnonOutput / PIIEntity (LLM response schema)
+examples/demo.py                         runnable demo of both layers
+tests/test_anonymizer.py                 test suite
+```

anon_lib-0.1.0/README.md

@@ -0,0 +1,164 @@
+# Sentence-anonimizer
+
+Detects and masks personally identifiable information (PII) in free text, replacing
+each value with a stable tag and returning the tag → original value mapping.
+
+Supports Brazilian Portuguese (`pt-br`) and English (`en`).
+
+## How it works
+
+Two layers, and the split matters:
+
+| Layer | Finds | Guarantees |
+| --- | --- | --- |
+| **Regex** (always on) | Formatted data: CPF, CNPJ, e-mail, phone, credit card, CEP… | Deterministic. Same input, same output, no network. |
+| **LLM via Ollama** (opt-in) | Context-dependent data regex cannot express: names, places, organizations | Best effort. Recall varies between runs. |
+
+The LLM only **identifies** entities and returns them as structured JSON. The masking
+itself is always done in code, reusing the same tagging machinery as the regex layer.
+The model never rewrites your text, so it cannot silently drop or alter passages.
+
+## Install
+
+```bash
+pip install anon-lib            # regex layer only
+pip install "anon-lib[llm]"     # adds the optional LLM layer
+```
+
+The base install has a single dependency and never touches the network. `ollama` and
+`pydantic` come only with the `llm` extra and are imported lazily, so calling
+`use_llm=True` without them raises an actionable `ImportError` instead of a bare
+`ModuleNotFoundError`.
+
+The LLM layer also needs a running [Ollama](https://ollama.com) server with a model
+pulled:
+
+```bash
+ollama pull qwen3:0.6b
+```
+
+Point the library at it with the `llm_model_name` argument, or read it from your own
+config:
+
+```python
+Anonymizer(llm_model_name="qwen3:0.6b")
+```
+
+## Usage
+
+`anonimize_text` returns a `(masked_text, tags)` tuple. Every tag in the mapping is
+guaranteed to appear in the masked text.
+
+### Regex only (default)
+
+```python
+from anon_lib import Anonymizer
+
+anon = Anonymizer(language="pt-br")
+masked, tags = anon.anonimize_text(
+    "Contato: joao.silva@empresa.com.br, CPF 123.456.789-00, "
+    "CNPJ 12.345.678/0001-99, cel (11) 98765-4321."
+)
+```
+
+```
+Contato: [EMAIL_0], CPF [CPF_0], CNPJ [CNPJ_NUMERICO_FORMATADO_0], cel [TELEFONE_BR_0].
+
+{'[EMAIL_0]': 'joao.silva@empresa.com.br',
+ '[CPF_0]': '123.456.789-00',
+ '[CNPJ_NUMERICO_FORMATADO_0]': '12.345.678/0001-99',
+ '[TELEFONE_BR_0]': '(11) 98765-4321'}
+```
+
+### Regex + LLM
+
+```python
+masked, tags = anon.anonimize_text(
+    "Meu nome é Maria, moro na Rua das Flores, 123 e meu CPF é 111.222.333-44.",
+    use_llm=True,
+)
+```
+
+```
+Meu nome é [PERSON_NAME_0], moro na [LOCATION_0], 123 e meu CPF é [CPF_0].
+
+{'[CPF_0]': '111.222.333-44',
+ '[PERSON_NAME_0]': 'Maria',
+ '[LOCATION_0]': 'Rua das Flores'}
+```
+
+Note the house number `123` left unmasked: that is real output, and it illustrates why
+the regex layer is the one you rely on for guarantees.
+
+Run both layers end to end with `python examples/demo.py`.
+
+## Detected patterns
+
+**pt-br** — `CPF`, `CNPJ_NUMERICO_FORMATADO`, `CNPJ_ALFANUMERICO`, `CNPJ_NUMERICO`,
+`CNPJ_ALFANUMERICO_SEM_PONTUACAO`, `RG`, `PIS_PASEP`, `TITULO_ELEITOR`, `CNH`, `EMAIL`,
+`TELEFONE_BR`, `CEP`, `DATA`, `PLACA_VEICULO`, `PLACA_VEICULO_MERCOSUL`,
+`CARTAO_CREDITO`, `CARTAO_CREDITO_AMEX`, `CHAVE_PIX_ALEATORIA`, `AGENCIA`,
+`CONTA_BANCARIA`, `IP`
+
+**en** — `EMAIL`, `SSN`, `CREDIT_CARD`, `CREDIT_CARD_AMEX`, `US_PHONE`, `US_ZIP`, `IP`
+
+**LLM entity types** — `PERSON_NAME`, `LOCATION`, `ORGANIZATION`, `DATE`, `AGE`,
+`TIME`, `MONEY`, `PERCENT`, `FACILITY`, `GPE` (configurable via
+`list_of_undeterministics_entities`; the list is injected into the response schema as an
+enum, so the model cannot return a type outside it).
+
+## Design notes
+
+**Declaration order is priority.** Some values match several patterns — 11 bare digits
+are both a CPF and a mobile number. The first pattern declared wins, so formatted
+patterns come first and ambiguous bare numerics last.
+
+**Longest value is replaced first.** The leading 12 digits of a spaced credit card also
+match a voter ID. Replacing the shorter value first would corrupt the longer one.
+
+**Label-anchored patterns include the label.** `CNH`, `AGENCIA` and `CONTA_BANCARIA` mask
+the label too (`CNH: 12345678901` → `[CNH_0]`), because the bare number is
+indistinguishable from a CPF without it.
+
+**LLM values absent from the text are discarded.** A paraphrased or invented value would
+produce a no-op substitution while making the output *look* anonymized.
+
+## Known limitations
+
+- **No check-digit validation.** A well-formed but arithmetically invalid CPF is still
+  masked. For anonymization, over-detection is the safe side.
+- **`DATA` matches any `dd/mm/aaaa` date**, with no way to tell a birth date from any
+  other. Distinguishing them requires context, which is the LLM layer's job.
+- **`US_ZIP` matches any 5-digit number**, and bare 11-digit runs are inherently
+  ambiguous between CPF, CNH and mobile numbers.
+- **`MONEY`, `PERCENT` and `TIME` are not PII** and only add noise. Adjust
+  `list_of_undeterministics_entities` for your use case — the list is injected into the
+  response schema as an enum, so it is the effective control over what the model may
+  return.
+- **Tag numbering may skip an index.** When a short value is also a substring of a longer
+  masked one, it stays registered to catch standalone occurrences elsewhere. Dropping it
+  would leak PII.
+
+## Tests
+
+```bash
+pip install -e ".[dev]"   # needs Python 3.9+, as declared in pyproject.toml
+pytest        # 53 tests, hermetic: no server, no network (~2s)
+pytest -m llm # 3 prompt-regression tests against a real Ollama
+```
+
+The default suite stubs every LLM response, so it needs no server. The `llm` marker is
+deselected by default and holds the tests that call the model for real — they verify the
+prompt rules still take effect, which a stub cannot do, and skip themselves when Ollama
+or the model is unavailable.
+
+## Layout
+
+```text
+src/anon_lib/__init__.py                 public API: Anonymizer, __version__
+src/anon_lib/anonymizer.py               Anonymizer
+src/anon_lib/patterns/patterns.py        regex pattern tables, per language
+src/anon_lib/schemas/models_schemas.py   AnonOutput / PIIEntity (LLM response schema)
+examples/demo.py                         runnable demo of both layers
+tests/test_anonymizer.py                 test suite
+```

anon_lib-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "anon-lib"
+dynamic = ["version"]                 # fonte unica: __version__ em src/anon_lib/__init__.py
+description = "PII detection and masking for Brazilian Portuguese and English"
+readme = "README.md"
+requires-python = ">=3.8.13"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Wyctor Fogos da Rocha"}]
+keywords = ["pii", "anonymization", "lgpd", "portuguese", "ner"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Natural Language :: Portuguese (Brazilian)",
+    "Natural Language :: English",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Text Processing :: Linguistic",
+    "Topic :: Security",
+]
+
+# Importado no topo de anonymizer.py, entao e obrigatorio: sem ele o
+# pacote instala e quebra no import.
+dependencies = ["langchain-text-splitters>=0.2"]
+
+[project.optional-dependencies]
+# Carregados sob demanda em Anonymizer._require_llm(), so no modo use_llm=True.
+llm = ["ollama>=0.3", "pydantic>=2"]
+dev = ["pytest>=7", "python-dotenv", "anon-lib[llm]"]
+
+[project.urls]
+Homepage = "https://github.com/wyctorfogos/anon-lib"
+Issues = "https://github.com/wyctorfogos/anon-lib/issues"
+
+[tool.hatch.version]
+path = "src/anon_lib/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/anon_lib"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src/anon_lib", "/tests", "/README.md", "/LICENSE", "/pytest.ini"]

anon_lib-0.1.0/pytest.ini

@@ -0,0 +1,11 @@
+[pytest]
+testpaths = tests
+pythonpath = src
+markers =
+    llm: exercita o Ollama de verdade (regressao de prompt). Rode com: pytest -m llm
+# Os plugins pytest do faker e do hypothesis instalados neste ambiente quebram
+# na importação sob Python 3.8 (typing não-subscriptável / pydantic._hypothesis_plugin
+# ausente). Nenhum dos dois é usado pelos testes, então desligamos o autoload deles.
+# -m "not llm": a suíte padrão fica hermética e sem rede; veja o bloco de
+# regressão de prompt no fim do arquivo de testes.
+addopts = -p no:faker -p no:hypothesispytest -m "not llm"

anon_lib-0.1.0/src/anon_lib/__init__.py

@@ -0,0 +1,10 @@
+"""Deteccao e mascaramento de PII em texto livre (pt-br e en).
+
+Camada regex, deterministica e sem rede, opcionalmente somada a uma camada LLM
+via Ollama para entidades que dependem de contexto (nomes, lugares, idades).
+"""
+
+from anon_lib.anonymizer import Anonymizer
+
+__version__ = "0.1.0"
+__all__ = ["Anonymizer", "__version__"]

anon_lib-0.1.0/src/anon_lib/anonymizer.py

@@ -0,0 +1,160 @@
+import re
+import os
+import copy
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+from anon_lib.patterns.patterns import _patterns_by_language
+
+class Anonymizer:
+    def __init__(self,
+            llm_model_name:str="hf.co/empero-ai/Qwen3.8-4B-Distill-GGUF:Q4_K_M",
+            llm_ipaddress_service:str="http://localhost:11434",
+            language="pt-br"
+        ):
+        self.llm_model_name=llm_model_name
+        self.llm_ipaddress_service=llm_ipaddress_service
+        self._llm_client=None  # criado sob demanda; veja _require_llm()
+        self.language=language
+        self._patterns_by_language=_patterns_by_language
+        self.list_of_undeterministics_entities = [
+            "PERSON_NAME", "LOCATION", "ORGANIZATION", 
+            "DATE", "AGE",
+            "TIME", "MONEY", "PERCENT", "FACILITY", "GPE"
+        ]
+
+        self.prompt = (
+            "Você é um detector de dados pessoais (PII). Devolva as entidades "
+            "encontradas no texto em JSON, seguindo o schema pedido.\n"
+            "Regras:\n"
+            "- Copie cada valor exatamente como aparece no texto, sem reescrever.\n"
+            "- Não devolva o texto mascarado: quem mascara é o código.\n"
+            "- Se não houver nenhuma entidade, devolva uma lista vazia.\n"
+            "- Capture TODOS os nomes de pessoas, incluindo terceiros mencionados "
+            "por vínculo familiar, profissional ou social "
+            "(ex: 'pai de', 'filha de', 'cônjuge de', 'advogado de').\n"
+            "- Capture idades expressas como número seguido de 'anos' "
+            "(ex: '35 anos', 'com 12 anos') como entidade do tipo AGE."
+        )
+
+    def _require_llm(self):
+        """Carrega as dependencias opcionais do modo LLM e devolve (client, schema).
+
+        Erro de import vira mensagem acionavel: sem isso o usuario receberia um
+        ModuleNotFoundError cru, sem pista de que existe um extra a instalar.
+        """
+        try:
+            import ollama
+            from anon_lib.schemas.models_schemas import AnonOutput
+        except ImportError as e:
+            raise ImportError(
+                "use_llm=True requer as dependencias opcionais do modo LLM: "
+                "pip install anon-lib[llm]"
+            ) from e
+        if self._llm_client is None:
+            self._llm_client = ollama.Client(host=self.llm_ipaddress_service)
+        return self._llm_client, AnonOutput
+
+    @property
+    def list_of_words_patterns(self):
+        try:
+            # Obtém a lista de padrões a serem procurados
+            lista_por_idioma=self._patterns_by_language.get(self.language)
+            if lista_por_idioma is None:
+                raise ValueError(f"Idioma '{self.language}' não suportado.")
+            return lista_por_idioma
+        except Exception as e:
+            raise ValueError(f"Erro ao obter a lista de padrões: {e}")
+        
+    def split_setences(self, sentence_text:str):
+        try:
+            text_splitter = RecursiveCharacterTextSplitter(
+                separators=["\n\n", "\n", ".", " ", ""],
+                chunk_size=1000,
+                chunk_overlap=100
+            )
+            return text_splitter.split_text(sentence_text)
+        except Exception as e:
+            raise ValueError(f"Erro ao realizar o split das sentenças textuais: {e}") from e
+
+    def find_keywords_and_replace(self, chunks_of_sentence_text:str=None):
+        if not chunks_of_sentence_text:
+            raise ValueError(f"Sem sentença a análisar.")
+
+        dict_found_keywords={}
+        valores_ja_capturados=set()
+        for chunk in chunks_of_sentence_text:
+            for pii_type, pattern in self.list_of_words_patterns.items():
+                for match in re.finditer(pattern, chunk):
+                    valor=match.group(0)
+                    if valor in valores_ja_capturados:
+                        continue
+                    valores_ja_capturados.add(valor)
+                    dict_found_keywords.setdefault(pii_type, set()).add(valor)
+        return dict_found_keywords
+    
+    def get_llm_response(self, prompt:str, format_schema:dict=None):
+        client, AnonOutput = self._require_llm()
+        try:
+            response = client.chat(
+                model=self.llm_model_name,
+                messages=[{"role": "user", "content": prompt}],
+                format=format_schema or AnonOutput.model_json_schema(),
+                options={"temperature": 0}
+            )
+            return response
+        except Exception as e:
+            raise ValueError(f"Erro ao obter resposta do LLM: {e}") from e
+        
+    def find_undeterministic_entities(self, sentence_text:str):
+        prompt = (
+            f"{self.prompt}\n\n"
+            f"Tipos de entidade a procurar:\n"
+            f"{', '.join(self.list_of_undeterministics_entities)}\n\n"
+            f"Ignore estes tipos, já tratados por regex:\n"
+            f"{', '.join(self.list_of_words_patterns)}\n\n"
+            f"Texto:\n{sentence_text.strip()}"
+        )
+
+        _, AnonOutput = self._require_llm()
+        schema = copy.deepcopy(AnonOutput.model_json_schema())
+        schema["$defs"]["PIIEntity"]["properties"]["tipo"]["enum"] = list(
+            self.list_of_undeterministics_entities
+        )
+        response = self.get_llm_response(prompt=prompt, format_schema=schema)
+
+        conteudo = getattr(response.message, "content", None)
+        if not conteudo:
+            raise ValueError("Resposta do LLM veio vazia.")
+        try:
+            resultado = AnonOutput.model_validate_json(conteudo)
+        except Exception as e:
+            raise ValueError(f"Resposta do LLM não bate com o schema: {e}") from e
+
+        entidades = {}
+        for entidade in resultado.anon_model_output:
+            if entidade.valor and entidade.valor in sentence_text:
+                entidades.setdefault(entidade.tipo, set()).add(entidade.valor)
+        return entidades
+            
+    def anonimize_text(self, sentence_text: str, use_llm: bool = False):
+        chunks = self.split_setences(sentence_text=sentence_text)
+        pii_words = self.find_keywords_and_replace(chunks_of_sentence_text=chunks)
+
+        if use_llm:
+            ja_capturados = {v for valores in pii_words.values() for v in valores}
+            for tipo, valores in self.find_undeterministic_entities(sentence_text).items():
+                novos = {v for v in valores
+                        if not any(v in j or j in v for j in ja_capturados)}
+                if novos:
+                    pii_words.setdefault(tipo, set()).update(novos)
+
+        tags = {
+            f"[{tipo}_{i}]": valor
+            for tipo, valores in pii_words.items()
+            for i, valor in enumerate(sorted(valores))
+        }
+
+        masked_text = sentence_text
+        for tag, valor in sorted(tags.items(), key=lambda kv: len(kv[1]), reverse=True):
+            masked_text = masked_text.replace(valor, tag)
+
+        return masked_text, {t: v for t, v in tags.items() if t in masked_text}

anon_lib-0.1.0/src/anon_lib/patterns/patterns.py

@@ -0,0 +1,36 @@
+_patterns_by_language={
+            "pt-br" : {
+                "EMAIL": r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b",
+                "CHAVE_PIX_ALEATORIA": r"\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b",
+                "CNPJ_NUMERICO_FORMATADO": r"\b\d{2}\.\d{3}\.\d{3}/\d{4}-\d{2}\b",
+                "CNPJ_ALFANUMERICO": r"\b[A-Z0-9]{2}\.[A-Z0-9]{3}\.[A-Z0-9]{3}/[A-Z0-9]{4}-\d{2}\b",
+                "RG": r"\b\d{2}\.\d{3}\.\d{3}-[0-9Xx]\b",
+                "PIS_PASEP": r"\b\d{3}\.\d{5}\.\d{2}-\d\b",
+                "CEP": r"(?<!\d)\d{5}-\d{3}(?!\d)",
+                "DATA": r"\b\d{2}/\d{2}/\d{4}\b",
+                "PLACA_VEICULO_MERCOSUL": r"\b[A-Z]{3}\d[A-Z]\d{2}\b",
+                "PLACA_VEICULO": r"\b[A-Z]{3}[- ]?\d{4}\b",
+                # --- Financeiro ---
+                "CARTAO_CREDITO_AMEX": r"(?<!\d)3[47]\d{2}[ .-]?\d{6}[ .-]?\d{5}(?!\d)",
+                "CARTAO_CREDITO": r"(?<!\d)(?:\d{4}[ .-]?){3}\d{4}(?!\d)",
+                "IP": r"(?<!\d)(?:(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)\.){3}(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(?!\d)",
+                "CNH": r"(?i)\bCNH\s*n?[º°]?\s*:?\s*\d{11}\b",
+                "AGENCIA": r"(?i)\bag(?:[êe]ncia)?\.?\s*n?[º°]?\s*:?\s*\d{4}(?:-\d)?\b",
+                "CONTA_BANCARIA": r"(?i)\b(?:c\/c|cc|conta)\.?\s*n?[º°]?\s*:?\s*\d{4,12}-?\d?\b",
+                # --- Numéricos crus (mais ambíguos, por último) ---
+                "TELEFONE_BR": r"(?<!\d)(?:\+55[-. ]?)?\(?\d{2}\)?[-. ]?9?\d{4}[-. ]?\d{4}(?!\d)",
+                "TITULO_ELEITOR": r"(?<!\d)\d{4}[ .]?\d{4}[ .]?\d{4}(?!\d)",
+                "CNPJ_NUMERICO": r"\b\d{14}\b",
+                "CNPJ_ALFANUMERICO_SEM_PONTUACAO": r"\b[A-Z0-9]{12}\d{2}\b",
+                "CPF": r"\b\d{3}\.\d{3}\.\d{3}[.-]\d{2}\b|(?<!\d)\d{11}(?!\d)",
+            },
+            "en": {
+                "EMAIL": r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b",
+                "SSN": r"(?<!\d)\d{3}-\d{2}-\d{4}(?!\d)",
+                "CREDIT_CARD_AMEX": r"(?<!\d)3[47]\d{2}[ .-]?\d{6}[ .-]?\d{5}(?!\d)",
+                "CREDIT_CARD": r"(?<!\d)(?:\d{4}[ .-]?){3}\d{4}(?!\d)",
+                "IP": r"(?<!\d)(?:(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)\.){3}(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(?!\d)",
+                "US_PHONE": r"(?<!\d)(?:\+?1[-.]?)?\(?([0-9]{3})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})(?!\d)",
+                "US_ZIP": r"\b\d{5}(?:-\d{4})?\b"
+            }
+        }

anon_lib-0.1.0/src/anon_lib/schemas/models_schemas.py

@@ -0,0 +1,21 @@
+from typing import List
+
+from pydantic import BaseModel, Field
+
+
+class PIIEntity(BaseModel):
+    """Uma entidade PII localizada pelo LLM no texto."""
+
+    tipo: str = Field(description="Tipo da entidade: PERSON, AGE, ADDRESS, ...")
+    valor: str = Field(description="Trecho exato copiado do texto, sem reescrever")
+
+
+class AnonOutput(BaseModel):
+    """Saída estruturada esperada do LLM.
+
+    É uma lista de objetos, e não um dict {tipo: valor}, porque um dict não pode
+    repetir a mesma chave: um texto com duas pessoas perderia uma delas em
+    silêncio (é o mesmo defeito do exemplo de saída que está no README).
+    """
+
+    anon_model_output: List[PIIEntity]

anon_lib-0.1.0/tests/test_anonymizer.py

@@ -0,0 +1,407 @@
+import json
+import os
+import subprocess
+import sys
+from types import SimpleNamespace
+
+import pytest
+
+# src entra no sys.path via `pythonpath` no pytest.ini; este bloco cobre a
+# execucao direta do arquivo, em que sys.path[0] seria tests/.
+_RAIZ = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+_SRC = os.path.join(_RAIZ, "src")
+if _SRC not in sys.path:
+    sys.path.insert(0, _SRC)
+
+from anon_lib import Anonymizer
+
+@pytest.fixture(scope="module")
+def anon_ptbr():
+    return Anonymizer(language="pt-br")
+
+
+@pytest.fixture(scope="module")
+def anon_en():
+    return Anonymizer(language="en")
+
+
+def mascarar(anon, texto, **kwargs):
+    """anonimize_text devolve (texto_mascarado, tags); aqui interessa so o texto."""
+    return anon.anonimize_text(texto, **kwargs)[0]
+
+
+# --------------------------------------------------------------------------
+# Um caso por padrão declarado em pt-br
+# --------------------------------------------------------------------------
+CASOS_PTBR = [
+    ("Contato: joao.silva@empresa.com.br", "Contato: [EMAIL_0]"),
+    ("Pix: 550e8400-e29b-41d4-a716-446655440000", "Pix: [CHAVE_PIX_ALEATORIA_0]"),
+    ("CPF 123.345.123-45", "CPF [CPF_0]"),
+    ("CNPJ 12.345.678/0001-99", "CNPJ [CNPJ_NUMERICO_FORMATADO_0]"),
+    ("CNPJ 12.ABC.345/01DE-35", "CNPJ [CNPJ_ALFANUMERICO_0]"),
+    ("RG 12.345.678-9", "RG [RG_0]"),
+    ("PIS 123.45678.90-1", "PIS [PIS_PASEP_0]"),
+    ("CEP 01310-100", "CEP [CEP_0]"),
+    ("Nasceu em 05/09/1990", "Nasceu em [DATA_0]"),
+    ("Placa ABC1D23", "Placa [PLACA_VEICULO_MERCOSUL_0]"),
+    ("Placa ABC-1234", "Placa [PLACA_VEICULO_0]"),
+    ("Cartao 4111 1111 1111 1111", "Cartao [CARTAO_CREDITO_0]"),
+    ("Amex 3782 822463 10005", "Amex [CARTAO_CREDITO_AMEX_0]"),
+    ("Servidor 192.168.0.14", "Servidor [IP_0]"),
+    ("Ligue (11) 98765-4321", "Ligue [TELEFONE_BR_0]"),
+    ("Ligue +55 11 98765-4321", "Ligue [TELEFONE_BR_0]"),
+    ("Ligue 1134567890", "Ligue [TELEFONE_BR_0]"),
+    ("Titulo 1234 5678 9012", "Titulo [TITULO_ELEITOR_0]"),
+    ("CNPJ 12345678000199", "CNPJ [CNPJ_NUMERICO_0]"),
+    ("CPF 12345678901", "CPF [CPF_0]"),
+]
+
+
+@pytest.mark.parametrize("texto,esperado", CASOS_PTBR)
+def test_padroes_ptbr(anon_ptbr, texto, esperado):
+    assert mascarar(anon_ptbr, texto) == esperado
+
+
+CASOS_EN = [
+    ("Email me at jane.doe@example.com", "Email me at [EMAIL_0]"),
+    ("SSN 123-45-6789", "SSN [SSN_0]"),
+    ("Card 4111-1111-1111-1111", "Card [CREDIT_CARD_0]"),
+    ("Amex 3782 822463 10005", "Amex [CREDIT_CARD_AMEX_0]"),
+    ("Server 192.168.0.14", "Server [IP_0]"),
+    ("ZIP 90210", "ZIP [US_ZIP_0]"),
+    ("ZIP 90210-1234", "ZIP [US_ZIP_0]"),
+]
+
+
+@pytest.mark.parametrize("texto,esperado", CASOS_EN)
+def test_padroes_en(anon_en, texto, esperado):
+    assert mascarar(anon_en, texto) == esperado
+
+
+def test_telefone_en_preserva_pontuacao_de_abertura(anon_en):
+    """O \\b inicial fazia o '(' e o '+' ficarem de fora do match."""
+    assert mascarar(anon_en, "Call (415) 555-2671 now") == "Call [US_PHONE_0] now"
+    assert mascarar(anon_en, "Call +1-415-555-2671 now") == "Call [US_PHONE_0] now"
+
+
+# --------------------------------------------------------------------------
+# Padrões ancorados por rótulo: o rótulo entra no trecho mascarado
+# --------------------------------------------------------------------------
+CASOS_COM_ROTULO = [
+    ("CNH: 12345678901", "[CNH_0]"),
+    ("Agencia 0001-2", "[AGENCIA_0]"),
+    ("conta 123456-7", "[CONTA_BANCARIA_0]"),
+]
+
+
+@pytest.mark.parametrize("texto,esperado", CASOS_COM_ROTULO)
+def test_padroes_ancorados_por_rotulo(anon_ptbr, texto, esperado):
+    assert mascarar(anon_ptbr, texto) == esperado
+
+
+# --------------------------------------------------------------------------
+# Resolução de conflito entre padrões
+# --------------------------------------------------------------------------
+def test_cartao_vence_titulo_de_eleitor(anon_ptbr):
+    """Os 12 primeiros dígitos de um cartão espaçado casam com TITULO_ELEITOR.
+
+    Se o valor curto fosse substituído primeiro, o cartão seria corrompido.
+    """
+    saida = mascarar(anon_ptbr, "Cartao 1234 5678 9012 3456 pago hoje")
+    assert saida == "Cartao [CARTAO_CREDITO_0] pago hoje"
+
+
+def test_cnpj_numerico_tem_prioridade_sobre_alfanumerico(anon_ptbr):
+    """[A-Z0-9] também casa dígitos: o padrão numérico precisa vir antes."""
+    assert "[CNPJ_NUMERICO_FORMATADO_0]" in mascarar(anon_ptbr, "12.345.678/0001-99")
+    assert "[CNPJ_NUMERICO_0]" in mascarar(anon_ptbr, "12345678000199")
+
+
+def test_sem_chaves_duplicadas_no_dicionario_de_padroes():
+    """Chave repetida num dict literal é sobrescrita em silêncio.
+
+    Não dá para detectar em runtime: o Python já descartou a duplicata na análise
+    sintática. Por isso lemos a AST do fonte. Este bug já apagou padrões duas
+    vezes (as 4 chaves "CNPJ", depois um segundo "CPF" que matou o formatado).
+    """
+    import ast
+
+    from anon_lib import anonymizer
+    from anon_lib.patterns import patterns
+
+    # Varre os dois: o dicionário de padrões mora em patterns/patterns.py e a
+    # lógica em anonymizer.py. Olhar só um deixaria o outro desprotegido.
+    duplicadas = []
+    for modulo in (patterns, anonymizer):
+        with open(modulo.__file__, encoding="utf-8") as arquivo:
+            arvore = ast.parse(arquivo.read())
+        for no in ast.walk(arvore):
+            if not isinstance(no, ast.Dict):
+                continue
+            chaves = [
+                k.value for k in no.keys
+                if isinstance(k, ast.Constant) and isinstance(k.value, str)
+            ]
+            duplicadas += sorted({
+                f"{os.path.basename(modulo.__file__)}:{c}"
+                for c in chaves if chaves.count(c) > 1
+            })
+
+    assert duplicadas == [], f"chaves duplicadas apagam padroes: {duplicadas}"
+
+
+def test_cpf_cobre_as_duas_formas_com_a_mesma_tag(anon_ptbr):
+    assert mascarar(anon_ptbr, "CPF 123.456.789-00") == "CPF [CPF_0]"
+    assert mascarar(anon_ptbr, "CPF 12345678901") == "CPF [CPF_0]"
+
+
+def test_telefone_tem_prioridade_sobre_cpf_sem_pontuacao(anon_ptbr):
+    """11 dígitos crus são ambíguos; o padrão de celular é o mais específico."""
+    assert mascarar(anon_ptbr, "Ligue 11987654321") == "Ligue [TELEFONE_BR_0]"
+
+
+def test_dotted_quad_invalido_como_ip_cai_em_cpf(anon_ptbr):
+    """345 > 255, então não é IP; o CPF com separador tolerante pega."""
+    assert mascarar(anon_ptbr, "Doc 123.345.123.45") == "Doc [CPF_0]"
+
+
+def test_valor_curto_contido_em_valor_longo_nao_vaza_isolado(anon_ptbr):
+    """O número da CNH rotulada também aparece solto: as duas ocorrências somem."""
+    saida = mascarar(anon_ptbr, "CNH: 12345678901 e de novo 12345678901 aqui")
+    assert "12345678901" not in saida
+
+
+# --------------------------------------------------------------------------
+# Fronteira de chunk (chunk_overlap)
+# --------------------------------------------------------------------------
+@pytest.mark.parametrize("alvo", ["joao.silva@empresa.com.br", "123.345.123-45"])
+def test_pii_na_fronteira_entre_chunks(anon_ptbr, alvo):
+    """Com chunk_overlap=0 o dado partido na fronteira dos 1000 chars vazava."""
+    vazamentos = []
+    for n in range(940, 1060):
+        filler = ("palavra teste do documento. " * 200)[:n]
+        texto = f"{filler} {alvo} fim do documento."
+        if alvo in mascarar(anon_ptbr, texto):
+            vazamentos.append(n)
+    assert vazamentos == []
+
+
+# --------------------------------------------------------------------------
+# Comportamento geral
+# --------------------------------------------------------------------------
+def test_texto_sem_pii_fica_intacto(anon_ptbr):
+    texto = "Reuniao marcada para a sala 3 do predio azul."
+    assert mascarar(anon_ptbr, texto) == texto
+
+
+def test_multiplos_valores_do_mesmo_tipo_recebem_tags_distintas(anon_ptbr):
+    saida = mascarar(anon_ptbr, "CPF 111.222.333-44 e CPF 555.666.777-88")
+    assert saida == "CPF [CPF_0] e CPF [CPF_1]"
+
+
+def test_idioma_nao_suportado(anon_ptbr):
+    anon = Anonymizer(language="fr")
+    with pytest.raises(ValueError, match="não suportado"):
+        mascarar(anon, "texto qualquer")
+
+
+@pytest.mark.parametrize("entrada", [None, []])
+def test_find_keywords_sem_conteudo(anon_ptbr, entrada):
+    with pytest.raises(ValueError, match="Sem sentença"):
+        anon_ptbr.find_keywords_and_replace(chunks_of_sentence_text=entrada)
+
+
+def test_numeracao_de_tags_estavel_entre_processos():
+    """Iterar um set de strings varia com o PYTHONHASHSEED; sorted() estabiliza."""
+    script = (
+        "from anon_lib import Anonymizer;"
+        "print(Anonymizer(language='pt-br').anonimize_text("
+        "'CPF 111.222.333-44, CPF 555.666.777-88, CPF 999.888.777-66'))"
+    )
+    # Herda o sys.path deste processo em vez de embutir um caminho relativo,
+    # para o teste não depender de onde o pytest foi chamado nem do layout.
+    saidas = set()
+    for seed in ("0", "1", "42", "12345"):
+        env = {
+            **os.environ,
+            "PYTHONHASHSEED": seed,
+            "PYTHONPATH": os.pathsep.join(p for p in sys.path if p),
+        }
+        resultado = subprocess.run(
+            [sys.executable, "-c", script],
+            env=env, capture_output=True, text=True, check=True,
+        )
+        saidas.add(resultado.stdout.strip())
+    assert len(saidas) == 1, f"numeracao instavel entre processos: {saidas}"
+
+
+# --------------------------------------------------------------------------
+# Caminho LLM (sem rede: a resposta do ollama é substituída por um stub)
+# --------------------------------------------------------------------------
+def _resposta_falsa(payload):
+    """Imita o ChatResponse do ollama: o conteúdo fica em message.content."""
+    return SimpleNamespace(message=SimpleNamespace(content=json.dumps(payload)))
+
+
+def test_llm_descarta_valor_que_nao_existe_no_texto(anon_ptbr, monkeypatch):
+    """Valor alucinado/parafraseado viraria um re.sub inócuo, fingindo anonimizar."""
+    texto = "Meu nome é Maria e moro em Vitoria."
+    monkeypatch.setattr(
+        anon_ptbr, "get_llm_response",
+        lambda prompt, format_schema=None: _resposta_falsa({"anon_model_output": [
+            {"tipo": "PERSON_NAME", "valor": "Maria"},
+            {"tipo": "PERSON_NAME", "valor": "Mariazinha"},   # não está no texto
+            {"tipo": "LOCATION", "valor": "Vitoria"},
+        ]}),
+    )
+    entidades = anon_ptbr.find_undeterministic_entities(texto)
+    assert entidades == {"PERSON_NAME": {"Maria"}, "LOCATION": {"Vitoria"}}
+
+
+def test_llm_preserva_duas_entidades_do_mesmo_tipo(anon_ptbr, monkeypatch):
+    """O motivo de a saída ser lista, e não dict: dict perderia um dos nomes."""
+    texto = "Maria é filha de Joshua Smith."
+    monkeypatch.setattr(
+        anon_ptbr, "get_llm_response",
+        lambda prompt, format_schema=None: _resposta_falsa({"anon_model_output": [
+            {"tipo": "PERSON_NAME", "valor": "Maria"},
+            {"tipo": "PERSON_NAME", "valor": "Joshua Smith"},
+        ]}),
+    )
+    saida = mascarar(anon_ptbr, texto, use_llm=True)
+    assert saida == "[PERSON_NAME_1] é filha de [PERSON_NAME_0]."
+
+
+def test_regex_tem_prioridade_sobre_o_llm(anon_ptbr, monkeypatch):
+    """Se os dois acharem o mesmo valor, ele não pode receber duas tags."""
+    texto = "O CPF 123.345.123-45 é da Maria."
+    monkeypatch.setattr(
+        anon_ptbr, "get_llm_response",
+        lambda prompt, format_schema=None: _resposta_falsa({"anon_model_output": [
+            {"tipo": "PERSON_NAME", "valor": "Maria"},
+            {"tipo": "MONEY", "valor": "123.345.123-45"},   # o regex já pegou
+        ]}),
+    )
+    saida = mascarar(anon_ptbr, texto, use_llm=True)
+    assert saida == "O CPF [CPF_0] é da [PERSON_NAME_0]."
+    assert "MONEY" not in saida
+
+
+def test_llm_nao_duplica_tag_de_valor_sobreposto_ao_regex(anon_ptbr, monkeypatch):
+    """O LLM devolve o telefone com o "+"; o regex capturou sem ele.
+
+    As strings diferem, então a deduplicação por igualdade deixava passar e o
+    mesmo telefone acabava com duas tags, uma delas órfã (no dict, fora do texto).
+    """
+    texto = "Meu celular é +2799778-5677."
+    monkeypatch.setattr(
+        anon_ptbr, "get_llm_response",
+        lambda prompt, format_schema=None: _resposta_falsa({"anon_model_output": [
+            {"tipo": "PERSON_NAME", "valor": "+2799778-5677"},
+        ]}),
+    )
+    masked, tags = anon_ptbr.anonimize_text(texto, use_llm=True)
+    assert list(tags) == ["[TELEFONE_BR_0]"]
+    assert "PERSON_NAME" not in masked
+
+
+def test_tags_devolvidas_existem_todas_no_texto(anon_ptbr, monkeypatch):
+    """Tag órfã no mapa inviabiliza desanonimizar depois."""
+    texto = "CNH: 12345678901 e Maria."
+    monkeypatch.setattr(
+        anon_ptbr, "get_llm_response",
+        lambda prompt, format_schema=None: _resposta_falsa({"anon_model_output": [
+            {"tipo": "PERSON_NAME", "valor": "Maria"},
+        ]}),
+    )
+    masked, tags = anon_ptbr.anonimize_text(texto, use_llm=True)
+    assert all(tag in masked for tag in tags), f"tags fora do texto: {tags}"
+
+
+def test_llm_rejeita_json_fora_do_schema(anon_ptbr, monkeypatch):
+    monkeypatch.setattr(
+        anon_ptbr, "get_llm_response",
+        lambda prompt, format_schema=None: _resposta_falsa({"resposta": "qualquer coisa"}),
+    )
+    with pytest.raises(ValueError, match="não bate com o schema"):
+        anon_ptbr.find_undeterministic_entities("Maria")
+
+
+def test_anonimize_text_sem_llm_nao_toca_a_rede(anon_ptbr, monkeypatch):
+    """use_llm=False é o default: a suíte inteira roda sem servidor."""
+    def explode(*args, **kwargs):
+        raise AssertionError("get_llm_response nao deveria ser chamado")
+
+    monkeypatch.setattr(anon_ptbr, "get_llm_response", explode)
+    assert mascarar(anon_ptbr, "CPF 123.345.123-45") == "CPF [CPF_0]"
+
+
+# --------------------------------------------------------------------------
+# Regressão de PROMPT — chamadas reais ao Ollama.
+#
+# Ficam fora da suíte padrão (pytest.ini desmarca "llm") porque dependem de
+# servidor e de um modelo, e porque a saída de um LLM não é garantida nem com
+# temperature=0. Rode-os de propósito ao mexer no prompt:
+#
+#     python3 -m pytest -m llm
+#
+# Stub não serviria aqui: o que se quer verificar é justamente se as regras do
+# prompt continuam surtindo efeito no modelo.
+# --------------------------------------------------------------------------
+@pytest.fixture(scope="module")
+def anon_llm():
+    from dotenv import load_dotenv
+
+    load_dotenv(os.path.join(_RAIZ, "config", ".env"))
+    modelo = os.getenv("LLM_MODEL_NAME")
+    anon = Anonymizer(**({"llm_model_name": modelo} if modelo else {}))
+    try:
+        client, _ = anon._require_llm()
+        client.show(anon.llm_model_name)
+    except Exception as e:
+        pytest.skip(f"Ollama indisponivel ou modelo ausente: {e}")
+    return anon
+
+
+@pytest.mark.llm
+def test_llm_captura_pessoa_citada_por_vinculo_familiar(anon_llm):
+    """Regra do prompt: terceiros mencionados por vínculo ('filha de X').
+
+    Antes da regra, o modelo devolvia só a pessoa que fala e o Joshua Smith
+    passava batido — ou vinha rotulado como ORGANIZATION.
+    """
+    texto = "Ele tinha 35 anos, sou filha de Joshua Smith e meu CPF é 111.222.333-44."
+    masked, tags = anon_llm.anonimize_text(texto, use_llm=True)
+    assert "Joshua Smith" not in masked
+    assert "Joshua Smith" in tags.values()
+
+
+@pytest.mark.llm
+def test_llm_captura_idade_como_age(anon_llm):
+    """Regra do prompt: '<numero> anos' é AGE.
+
+    Sem AGE na lista de entidades, '35 anos' caía em DATE.
+    """
+    masked, tags = anon_llm.anonimize_text("Ele tinha 35 anos.", use_llm=True)
+    assert "35 anos" not in masked
+    assert any(tag.startswith("[AGE_") for tag in tags), tags
+
+
+@pytest.mark.llm
+def test_llm_captura_nome_solto_sem_vinculo(anon_llm):
+    """Contraprova da regra de vínculo: nome sem parentesco declarado.
+
+    A regra fala em 'pai de', 'filha de'; era preciso confirmar que ela não
+    estreitou o modelo a ponto de ignorar um nome solto.
+    """
+    texto = "Meu cpf é 123.345.123-45, o Carlos é amigo de todos."
+    masked, tags = anon_llm.anonimize_text(texto, use_llm=True)
+    assert "Carlos" not in masked
+    assert "Carlos" in tags.values()
+
+
+
+if __name__ == "__main__":
+    # Sem isto, rodar o arquivo direto apenas definiria as funções e sairia sem
+    # executar nada: fixtures e parametrize só têm efeito sob o pytest.
+    raise SystemExit(pytest.main([__file__, "-v"]))