---
name: entity_candidate
lang: py
domain: datascience
version: "1.0.0"
algebraic: product
definition: |
  @dataclass
  class EntityCandidate:
      name: str
      name_normalized: str = ""
      type_ref: str = ""
      type_label: str = ""
      attributes: dict = field(default_factory=dict)
      confidence: float = 0.0
      source_chunk_indices: list[int] = field(default_factory=list)
      merged_from: list[str] = field(default_factory=list)
description: "Candidato de entidad extraido por el LLM. Puede venir de un solo chunk o ser el resultado de mergear multiples extracciones. merged_from rastrea los nombres originales para debugging."
tags: [extraction, entity, llm, knowledge-graph, nlp, datascience]
uses_types: []
file_path: "python/types/datascience/entity_candidate.py"
---

## Campos

- `name`: nombre crudo extraido del texto
- `name_normalized`: nombre normalizado para deduplicacion (se llena en la fase de dedup)
- `type_ref`: registry type ID del tipo de entidad (ej: `osint_person_go_cybersecurity`)
- `type_label`: label humano del tipo (ej: `"Person"`)
- `attributes`: metadata extraida del texto como diccionario libre
- `confidence`: score de confianza 0.0-1.0
- `source_chunk_indices`: indices de los chunks donde aparecio la entidad
- `merged_from`: nombres originales si el candidato fue creado por merge de varios

## Ejemplo

```python
from python.types.datascience.entity_candidate import EntityCandidate

candidate = EntityCandidate(
    name="John Smith",
    name_normalized="john smith",
    type_ref="osint_person_go_cybersecurity",
    type_label="Person",
    attributes={"role": "CEO", "company": "Acme Corp"},
    confidence=0.92,
    source_chunk_indices=[0, 3],
    merged_from=["John Smith", "Smith, John"],
)

print(candidate.to_dict())
```

## Notas

Tipo inmutable en su intencion pero declarado como dataclass mutable para permitir que las fases de deduplicacion rellenen `name_normalized` y que el pipeline complete los campos opcionales progresivamente. `merged_from` es la fuente de verdad para auditar que entidades se colapsaron juntas.
