Ontology Evolution

rag.set_entity_description(label, description)
rag.set_relation_description(label, description)
rag.set_attribute_description(owner_label, attribute_name, description)
rag.add_entity(entity: Entity)                    # declaration only
rag.add_relation_pattern(rel_label, source, target)  # declaration only

rag.rename_entity(old, new)
rag.rename_attribute(owner_label, old_name, new_name)
rag.rename_relation(old, new)
rag.drop_entity(label)                            # cascades to relation patterns
rag.drop_relation(label)
rag.drop_relation_pattern(rel_label, source, target)

rag.add_attribute(owner_label, attribute, *, concurrency=4, dry_run=False)
# Atomic: LLM extracts values from every chunk mentioning the owner
# type, sets them on matching entities (null where the LLM doesn't
# know), then commits the new :Property to the ontology graph.
# Pass dry_run=True to preview cost without invoking the LLM.

rag.drop_attribute(owner_label, name)
# Atomic: REMOVE n.<name> on every instance, then delete the :Property
# declaration. Cheap, no LLM.

rag.backfill_entity(label, *, scope="all" | list[chunk_id], dry_run=False)
# "Re-scan chunks for any entities of this type I might have missed."

rag.backfill_relation_pattern(rel_label, source, target, *, dry_run=False)
# "Re-scan candidate co-mention chunks for any edges of this pattern."

add_attribute("Person", Attribute(name="role", type="STRING"))
        │
        ▼
  ┌─────────────────────────────┐
  │ 1. LLM-extract role from    │
  │    every chunk mentioning   │
  │    a Person.                │
  │                             │
  │ 2. SET p.role on matching   │
  │    entities (null where     │
  │    the LLM doesn't know).   │
  │                             │
  │ 3. Commit :Property node    │
  │    to ontology graph.       │   ← commit point
  └─────────────────────────────┘
        │
        ▼
   EvolutionResult

from graphrag_sdk import OntologyEvolutionError

try:
    result = await rag.add_attribute("Person", Attribute(name="role"))
except OntologyEvolutionError as e:
    print(f"Failed on {len(e.failed_chunks)} chunks: {e.failed_chunks[:5]}")
    # ...investigate and fix...
    result = await rag.add_attribute("Person", Attribute(name="role"))  # idempotent retry

# Person.age is STRING. We want INTEGER.
await rag.drop_attribute("Person", "age")
result = await rag.add_attribute("Person", Attribute(name="age", type="INTEGER"))

preview = await rag.add_attribute(
    "Person", Attribute(name="role", type="STRING"),
    dry_run=True,
)
print(f"Would scan {preview.chunks_in_scope} chunks "
      f"(~{preview.chunks_in_scope} LLM calls)")
# Decide whether to proceed.
if preview.chunks_in_scope < 1000:
    result = await rag.add_attribute("Person", Attribute(name="role", type="STRING"))

import asyncio
from graphrag_sdk import (
    Attribute, ConnectionConfig, Entity, EvolutionResult, GraphRAG,
    LiteLLM, LiteLLMEmbedder, Ontology, Relation,
)


async def main():
    starter = Ontology(
        entities=[
            Entity(label="Person", description="A human"),
            Entity(label="Company", description="A business"),
        ],
        relations=[
            Relation(
                label="WORKS_AT",
                patterns=[("Person", "Company")],
            ),
        ],
    )

    async with GraphRAG(
        connection=ConnectionConfig(host="localhost", graph_name="evolve_demo"),
        llm=LiteLLM(model="openai/gpt-4o-mini"),
        embedder=LiteLLMEmbedder(model="openai/text-embedding-3-small"),
        ontology=starter,
    ) as rag:
        # 1. Ingest with the starter ontology.
        await rag.ingest(
            text="Alice Liddell is a software engineer at Acme Corp.",
            document_id="doc1",
        )

        # 2. Atomic attribute add: declare + LLM backfill + commit.
        result: EvolutionResult = await rag.add_attribute(
            "Person", Attribute(name="role", type="STRING"),
        )
        print(f"role filled on {result.values_filled} entities, "
              f"{result.chunks_scanned} chunks scanned, "
              f"{result.llm_calls} LLM calls")

        # 3. Type change via drop + add.
        await rag.drop_attribute("Person", "role")
        result = await rag.add_attribute(
            "Person", Attribute(name="role", type="STRING",
                                description="Their job title"),
        )

        # 4. Declare a new entity type — cheap, no LLM.
        await rag.add_entity(Entity(label="City"))

        # 5. Opportunistic: scan corpus for any Cities we missed.
        discovery = await rag.backfill_entity("City", scope="all")
        print(f"discovered {discovery.values_filled} City instances")

        # 6. Inspect the final ontology.
        ontology = await rag.get_ontology()
        for e in ontology.entities:
            attrs = ", ".join(f"{p.name}:{p.type}" for p in e.properties) or "—"
            print(f"  {e.label:<10} {attrs}")


asyncio.run(main())