fn_registry/python/functions/datascience/extract_entities_llm.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, params, output, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params	output	tested	tests	test_file_path	file_path
extract_entities_llm	function	py	datascience	1.0.0	impure	def extract_entities_llm(text: str, entity_schema: list[dict], llm_chat_json: Callablelist[dict, dict], language_instruction: str = 'Respond in English.') -> list[EntityCandidate]	Extrae entidades de un chunk de texto usando un LLM inyectado. Construye el system prompt con el schema, llama al LLM y valida la respuesta retornando EntityCandidate. JSON invalido o type_ref fuera del schema se descartan con warning.	llm extraction entity nlp osint graph fuzzygraph datascience prompt		entity_candidate_py_datascience		false	error_go_core	warnings typing.Callable	name desc text texto fuente para extraccion (ej: documento, parrafo, chunk de OSINT). Puede contener multiples entidades. name desc entity_schema lista de dicts describiendo tipos validos (ej: [{'type_ref': 'osint_person_go_cybersecurity', 'label': 'Person'}]) name desc llm_chat_json callable que toma list[dict] con messages OpenAI-format y retorna dict con clave 'entities'. Inyeccion de dependencia del LLM. name desc language_instruction instruccion de lenguaje para el LLM (defecto: 'Respond in English.'). Ej: 'Responde en Español.'	lista de EntityCandidate extraidas, cada una con name, type_ref, confidence, atributos	true	texto con entidades claras retorna EntityCandidate texto sin entidades retorna lista vacia llm retorna json mal formado retorna lista vacia con warning type_ref invalido en respuesta se descarta con warning confidence se propaga correctamente schema vacio lanza ValueError	python/functions/datascience/extract_entities_llm_test.py	python/functions/datascience/extract_entities_llm.py

Ejemplo

import json
from extract_entities_llm import extract_entities_llm

# LLM stub para tests — en produccion usar litellm o similar
def mock_llm(messages: list[dict]) -> dict:
    return {
        "entities": [
            {
                "name": "John Smith",
                "type_ref": "osint_person_go_cybersecurity",
                "attributes": {"full_name": "John Smith", "nationality": "US"},
                "confidence": 0.95,
            },
            {
                "name": "evil-corp.com",
                "type_ref": "osint_domain_go_cybersecurity",
                "attributes": {"fqdn": "evil-corp.com"},
                "confidence": 0.88,
            },
        ]
    }

schema = [
    {
        "type_ref": "osint_person_go_cybersecurity",
        "label": "Person",
        "metadata_fields": ["full_name", "alias", "nationality", "dob", "risk_score"],
    },
    {
        "type_ref": "osint_domain_go_cybersecurity",
        "label": "Domain",
        "metadata_fields": ["fqdn", "registrar", "created_date"],
    },
]

text = "John Smith, a US citizen, was linked to the domain evil-corp.com."
candidates = extract_entities_llm(text, schema, mock_llm)
# [EntityCandidate(name='John Smith', type_ref='osint_person_go_cybersecurity', confidence=0.95),
#  EntityCandidate(name='evil-corp.com', type_ref='osint_domain_go_cybersecurity', confidence=0.88)]

Notas

Inyeccion de dependencia del LLM: llm_chat_json recibe mensajes en formato OpenAI ([{"role": "system", "content": "..."}, ...]) y retorna un dict con la respuesta ya parseada como JSON. Esto desacopla la funcion de cualquier cliente especifico — puede usarse con OpenAI, Anthropic via litellm, o cualquier mock.

Validacion de type_ref: Solo se aceptan entidades cuyo type_ref aparece en el entity_schema. Entidades con type_ref desconocido se descartan con warnings.warn (no lanzan excepcion) para ser resiliente ante alucinaciones del LLM.

Manejo de JSON invalido: Si llm_chat_json lanza una excepcion o retorna un dict sin la clave entities, se retorna lista vacia y se emite un warning. El llamador puede decidir si reintentar.

Confidence clamping: El valor de confidence se clampea al rango [0.0, 1.0] automaticamente.

Atributos null: Los atributos con valor None se filtran del dict de atributos para mantener el output limpio.

source_chunk_indices: Esta funcion no setea source_chunk_indices — ese campo lo llena el pipeline exterior que conoce el indice del chunk actual.

Esta funcion es el bloque atomico de extraccion. El pipeline completo de grafos la llama por cada chunk del documento y luego deduplica los candidatos resultantes.