Function _write_entity

openkb/agent/compiler.py:1024–1093

Write or update an entity page in entities/, managing frontmatter. Frontmatter fields: ``sources`` (list), ``type`` (one of the entity enum, capitalized on write), ``description`` (one-liner), and optional ``aliases`` (list, omitted when empty). On update the new source is prepended and

(
    wiki_dir: Path,
    name: str,
    content: str,
    source_file: str,
    is_update: bool,
    brief: str = "",
    type_: str = "other",
    aliases: list[str] | None = None,
)

def _write_entity(
    wiki_dir: Path,
    name: str,
    content: str,
    source_file: str,
    is_update: bool,
    brief: str = "",
    type_: str = "other",
    aliases: list[str] | None = None,
) -> None:
    """Write or update an entity page in entities/, managing frontmatter.

    Frontmatter fields: ``sources`` (list), ``type`` (one of the entity
    enum, capitalized on write), ``description`` (one-liner), and optional
    ``aliases`` (list, omitted when empty). On update the new source is prepended and the body replaced
    with the LLM rewrite; ``type`` is preserved from the new write.
    """
    entities_dir = wiki_dir / "entities"
    entities_dir.mkdir(parents=True, exist_ok=True)
    safe_name = _sanitize_concept_name(name)
    path = (entities_dir / f"{safe_name}.md").resolve()
    if not path.is_relative_to(entities_dir.resolve()):
        logger.warning("Entity name escapes entities dir: %s", name)
        return

    # Strip any frontmatter the LLM body may carry.
    clean_parts = frontmatter.split(content)
    clean = clean_parts[1].lstrip("\n") if clean_parts is not None else content

    def _build_entity_frontmatter(sources: list[str]) -> str:
        fm_lines = [_yaml_list_line("sources", sources)]
        fm_lines.append(_yaml_kv_line("type", (type_ or "other").title()))
        if brief:
            fm_lines.append(_yaml_kv_line("description", brief))
        if aliases:
            fm_lines.append(_yaml_list_line("aliases", aliases))
        return "---\n" + "\n".join(fm_lines) + "\n---\n\n"

    if is_update and path.exists():
        existing = path.read_text(encoding="utf-8")
        if source_file not in existing:
            existing = _prepend_source_to_frontmatter(existing, source_file)
        ex_parts = frontmatter.split(existing)
        if ex_parts is not None:
            fm_block, _ = ex_parts
            fm_block = _set_fm_line(fm_block, "description", brief) if brief else fm_block
            fm_block = _set_fm_line(fm_block, "type", type_.title()) if type_ else fm_block
            # Drop any legacy ``brief:`` key (migrated to ``description:``),
            # mirroring _write_concept's update path.
            fm_block = frontmatter.drop_line(fm_block, "brief")
            existing = fm_block + "\n" + clean
        else:
            # Malformed/absent frontmatter (opening ``---`` with no closing
            # delimiter, or no frontmatter at all): rebuild valid frontmatter
            # rather than writing a body-only page. Recover any sources already
            # listed in the broken block first — otherwise a multi-source
            # entity would be truncated to just this document.
            recovered: list[str] = []