docs: migrate to v1.2 ontology vocabulary - #279
Open
galshubeli wants to merge 3 commits into
Open
Conversation
…ttribute) The docs still used the pre-v1.2 names (GraphSchema/EntityType/ RelationType/PropertyType) and the deprecated schema= kwarg, which now emit DeprecationWarnings when copy-pasted. Updated all examples, type hints, and prose to the current vocabulary; the graph-schema page URL is unchanged. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
📝 WalkthroughWalkthroughThe documentation and executable examples replace ChangesOntology documentation update
Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
The Attribute model on main has only name/type/description; the required field documented here does not exist in the code. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/api-reference.md`:
- Around line 524-535: Update the ontology example’s graphrag_sdk import
statement to include Attribute alongside Ontology, Entity, and Relation, so the
Entity.properties annotation references an imported symbol.
- Line 47: Update the constructor parameter table in docs/api-reference.md to
rename schema to ontology, matching the constructor and public attribute names
while preserving the existing type, default, and description.
- Around line 540-544: Update the Relation model documentation in the API
reference to include the missing properties field as a list of Attribute values,
matching the model definition and configuration documentation; leave the
existing label, description, and patterns entries unchanged.
In `@docs/configuration.md`:
- Around line 359-361: Complete the schema-to-ontology terminology migration
across the documented sites: in docs/configuration.md lines 359-361, rename
“Open Schema Mode” and “open-schema mode”; in docs/ingestion.md line 148, rename
“Open schema mode”; in docs/strategies.md lines 263-275, replace “schema types”
in the explanation and example comment; and in docs/getting-started.md lines
66-69, change “Define a Schema” to “Define an Ontology.”
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 81363f18-a962-4403-b3c5-f718eb97e2fe
📒 Files selected for processing (8)
README.mddocs/api-reference.mddocs/configuration.mddocs/extraction.mddocs/getting-started.mddocs/graph-schema.mddocs/ingestion.mddocs/strategies.md
| | `llm` | `LLMInterface` | required | LLM provider | | ||
| | `embedder` | `Embedder` | required | Embedding provider | | ||
| | `schema` | `GraphSchema \| None` | `None` | Schema constraints for extraction (empty = unconstrained) | | ||
| | `schema` | `Ontology \| None` | `None` | Schema constraints for extraction (empty = unconstrained) | |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Rename the constructor parameter in the parameter table.
The constructor and public attributes use ontology, but the table still documents schema. Copying this table would encourage use of the deprecated keyword and contradict the API signature.
Proposed fix
-| `schema` | `Ontology \| None` | `None` | Schema constraints for extraction (empty = unconstrained) |
+| `ontology` | `Ontology \| None` | `None` | Ontology constraints for extraction (empty = unconstrained) |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| | `schema` | `Ontology \| None` | `None` | Schema constraints for extraction (empty = unconstrained) | | |
| | `ontology` | `Ontology \| None` | `None` | Ontology constraints for extraction (empty = unconstrained) | |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/api-reference.md` at line 47, Update the constructor parameter table in
docs/api-reference.md to rename schema to ontology, matching the constructor and
public attribute names while preserving the existing type, default, and
description.
Comment on lines
524
to
535
| ```python | ||
| from graphrag_sdk import GraphSchema, EntityType, RelationType | ||
| from graphrag_sdk import Ontology, Entity, Relation | ||
| ``` | ||
|
|
||
| ### EntityType | ||
| ### Entity | ||
|
|
||
| ```python | ||
| class EntityType(DataModel): | ||
| class Entity(DataModel): | ||
| label: str # e.g. "Person" | ||
| description: str | None = None # Helps LLM understand what to extract | ||
| properties: list[PropertyType] = [] # Optional property definitions | ||
| properties: list[Attribute] = [] # Optional property definitions | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Import Attribute in the ontology example.
The snippet references Attribute in Entity.properties but does not import it, so a reader copying the example gets an undefined name.
Proposed fix
-from graphrag_sdk import Ontology, Entity, Relation
+from graphrag_sdk import Ontology, Entity, Relation, Attribute📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ```python | |
| from graphrag_sdk import GraphSchema, EntityType, RelationType | |
| from graphrag_sdk import Ontology, Entity, Relation | |
| ``` | |
| ### EntityType | |
| ### Entity | |
| ```python | |
| class EntityType(DataModel): | |
| class Entity(DataModel): | |
| label: str # e.g. "Person" | |
| description: str | None = None # Helps LLM understand what to extract | |
| properties: list[PropertyType] = [] # Optional property definitions | |
| properties: list[Attribute] = [] # Optional property definitions | |
| ``` |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/api-reference.md` around lines 524 - 535, Update the ontology example’s
graphrag_sdk import statement to include Attribute alongside Ontology, Entity,
and Relation, so the Entity.properties annotation references an imported symbol.
Comment on lines
+540
to
544
| class Relation(DataModel): | ||
| label: str # e.g. "WORKS_AT" | ||
| description: str | None = None | ||
| patterns: list[tuple[str, str]] = [] # Allowed (source_label, target_label) pairs | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n== Relevant docs snippets ==\n'
for f in docs/api-reference.md docs/configuration.md; do
echo "--- $f ---"
if [ -f "$f" ]; then
# show only the likely relevant area if present
rg -n -C 4 'Relation|properties|patterns|Attribute' "$f" || true
else
echo "missing"
fi
done
printf '\n== Search for Relation model definition/usages ==\n'
rg -n -C 3 'class Relation|Relation\(|properties: list\[Attribute\]|patterns: list\[tuple\[str, str\]\]' . || trueRepository: FalkorDB/GraphRAG-SDK
Length of output: 50379
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n -C 4 'class Relation\b|properties: list\[Attribute\]|patterns: list\[tuple\[str, str\]\]' graphrag_sdk/src docs --glob '!**/node_modules/**'Repository: FalkorDB/GraphRAG-SDK
Length of output: 6750
Document Relation.properties in the API reference
In docs/api-reference.md:540-544, add properties: list[Attribute] to match docs/configuration.md and graphrag_sdk/src/graphrag_sdk/core/models.py.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/api-reference.md` around lines 540 - 544, Update the Relation model
documentation in the API reference to include the missing properties field as a
list of Attribute values, matching the model definition and configuration
documentation; leave the existing label, description, and patterns entries
unchanged.
Comment on lines
359
to
+361
| ### Open Schema Mode | ||
|
|
||
| If no entity types or relation types are defined (empty `GraphSchema()`), the extraction operates in open-schema mode and the pruning step is skipped. This lets the LLM extract any entities and relationships it finds. | ||
| If no entity types or relation types are defined (empty `Ontology()`), the extraction operates in open-schema mode and the pruning step is skipped. This lets the LLM extract any entities and relationships it finds. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Complete the schema-to-ontology terminology migration.
Several ontology sections still retain deprecated “schema” wording, which makes the documentation inconsistent with the v1.2 API vocabulary.
docs/configuration.md#L359-L361: Rename “Open Schema Mode” and “open-schema mode” to ontology terminology.docs/ingestion.md#L148-L148: Rename “Open schema mode.”docs/strategies.md#L263-L275: Replace “schema types” in the explanation and example comment.docs/getting-started.md#L66-L69: Rename the section heading from “Define a Schema” to “Define an Ontology.”
📍 Affects 4 files
docs/configuration.md#L359-L361(this comment)docs/ingestion.md#L148-L148docs/strategies.md#L263-L275docs/getting-started.md#L66-L69
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/configuration.md` around lines 359 - 361, Complete the
schema-to-ontology terminology migration across the documented sites: in
docs/configuration.md lines 359-361, rename “Open Schema Mode” and “open-schema
mode”; in docs/ingestion.md line 148, rename “Open schema mode”; in
docs/strategies.md lines 263-275, replace “schema types” in the explanation and
example comment; and in docs/getting-started.md lines 66-69, change “Define a
Schema” to “Define an Ontology.”
08_ontology_lifecycle.py intentionally untouched — its step 8 demonstrates that the legacy names still work. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The documentation, README, and runnable examples still used the pre-v1.2 class names —
GraphSchema/EntityType/RelationType/PropertyType— and the deprecatedschema=kwarg. Copy-pasting any docs example on a current SDK emitsDeprecationWarnings, and the aliases are slated for removal.This PR migrates everything to the current vocabulary (
Ontology/Entity/Relation/Attribute,ontology=), matching the v1.2.x rename (commit 363a53d):docs/graph-schema.mdfilename (and its published URL) intentionally unchanged; api-reference## Schemasection renamed to## Ontology08_ontology_lifecycle.pyintentionally untouched — its step 8 demonstrates that the legacy names still workrequired: bool = FalseonAttribute, but that field does not exist incore/models.py— removedSchemaExtensionProposalwhich is a real class)Every renamed reference was verified against
graphrag_sdk/srcon main:GraphRAG(ontology=...)+ deprecatedschema=shim, public attributeself.ontology,extract(..., ontology, ...),ontology.entitiesprecedence, model fields ofEntity/Relation/Attribute/Ontology, the 11 default entity types list, and the__init__exports (old names exist only in_LEGACY_MODEL_ALIASES).Ruff on the touched example files: 5 findings on this branch vs 6 on main — all pre-existing, none introduced.
🤖 Generated with Claude Code
Summary by CodeRabbit
Ontology,Entity,Relation,Attribute) instead of the legacy schema terminology.ontologyinputs (including “open schema mode” using an emptyOntology()).Ontologyand pass it intoGraphRAGvia theontology=argument.