fn_registry/python/functions/datascience/extract_relations_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_relations_llm	function	py	datascience	1.0.0	impure	def extract_relations_llm(text: str, entities: list, relation_types: list[str], llm_chat_json: Callablelist[dict, dict], language_instruction: str = 'Respond in English.') -> list	Extrae relaciones entre entidades de un chunk de texto usando un LLM inyectado. Valida que from_name y to_name correspondan a entidades existentes, y usa 'related_to' como fallback para tipos de relacion no permitidos.	extraction relation llm knowledge-graph nlp datascience fuzzygraph graph		entity_candidate_py_datascience relation_candidate_py_datascience	relation_candidate_py_datascience	false	error_go_core	logging sys os typing	name desc text texto fuente para extraccion de relaciones entre entidades (ej: documento OSINT, parrafo descriptivo) name desc entities lista de EntityCandidate ya extraidas (ej: output de extract_entities_llm). Valida que las relaciones refieran entidades reales. name desc relation_types lista de nombres de relacion permitidos (ej: ['employs', 'funds', 'owns']). No permitidas se remapean a 'related_to'. name desc llm_chat_json callable que toma list[dict] mensajes y retorna dict con clave 'relations'. Inyeccion de dependencia del LLM. name desc language_instruction instruccion de lenguaje para el LLM (defecto: 'Respond in English.')	lista de RelationCandidate con from_name, to_name, relation_type, description, confidence	true	texto con dos entidades relacionadas texto con entidades pero sin relacion menos de dos entidades retorna lista vacia llm inventa entidad que no existe se descarta	python/functions/datascience/extract_relations_llm_test.py	python/functions/datascience/extract_relations_llm.py

Ejemplo

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

# Stub de llm_chat_json (en produccion usar llm_completion_retry o similar)
def my_llm(messages: list[dict]) -> dict:
    # Llamar al LLM real aqui
    return {"relations": [...]}

entities = [
    EntityCandidate(name="Acme Corp", type_label="Organization", confidence=0.95),
    EntityCandidate(name="John Smith", type_label="Person", confidence=0.9),
]

relation_types = ["employs", "funds", "owns", "communicates_with", "related_to"]

relations = extract_relations_llm(
    text="Acme Corp employs John Smith as CEO and funds his research.",
    entities=entities,
    relation_types=relation_types,
    llm_chat_json=my_llm,
)

for rel in relations:
    print(f"{rel.from_name} --[{rel.relation_type}]--> {rel.to_name} ({rel.confidence:.2f})")
# Acme Corp --[employs]--> John Smith (0.90)
# Acme Corp --[funds]--> John Smith (0.85)

Notas

Inyeccion de dependencia del LLM: llm_chat_json recibe una lista de mensajes en formato OpenAI ([{"role": "system", "content": ...}, {"role": "user", "content": ...}]) y retorna un dict con la clave "relations". Esto desacopla la funcion de cualquier proveedor de LLM concreto.

Validacion de entidades: Solo se aceptan relaciones donde from_name y to_name aparecen exactamente en los nombres de las entidades proporcionadas. Relaciones con nombres inventados por el LLM se descartan silenciosamente (con debug log).

Fallback de tipo: Si el LLM propone un relation_type que no esta en la lista permitida, se reemplaza por "related_to". Si "related_to" tampoco esta en la lista, se incluye igualmente como catch-all seguro.

Menos de 2 entidades: La funcion retorna [] inmediatamente sin llamar al LLM, ya que no puede haber relaciones con menos de 2 participantes.

Error handling: Si llm_chat_json lanza una excepcion, se captura con warning y retorna []. Si la respuesta no contiene la clave "relations" o no es una lista, idem.

Confianza: Los valores de confianza del LLM se clampean al rango [0.0, 1.0]. Valores no numericos se convierten a 0.0.

Disenado para fuzzygraph — se compone con extract_entities_llm (paso anterior) y deduplicate_relations (paso siguiente en el pipeline de extraccion).