ModelVerbalizer

relationalai.agent.cortex.verbalize

ModelVerbalizer(
    model: relationalai.semantics.Model, include_source_columns: bool = False
)

Default verbalizer that returns relationship readings from a RAI Model.

Extracts relationship readings from a RAI Model and returns them as sorted, newline-separated text. This provides a concise overview of the model’s semantic relationships.

Parameters

• model

  (relationalai.semantics.Model) - RAI Model to verbalize.

• include_source_columns

  (bool, default: False) - When False (default), readings for auto-generated source-table column properties are filtered out and only readings attached to user-declared concepts are emitted. Source-bound readings double the line count without adding semantic value to the agent and routinely push real models past the 16KB tool-result ceiling. Set True to restore the legacy behavior.

Examples

model = rai.Model("jaffle")
verbalizer = ModelVerbalizer(model)
print(verbalizer.explain_model())
# Customer has many Orders
# Order has one Customer

Methods

.explain_model()

ModelVerbalizer.explain_model() -> str

Return sorted, newline-separated relationship readings from the model.

By default, readings backed by source-table column bindings are filtered out (see include_source_columns). Additionally, the output is restricted to the model’s traversal graph: identifier readings per concept plus readings whose rightmost field targets another entity concept. Property readings whose target is a primitive (String, Integer, Date, Float, …), a value-type alias (e.g. ContractId(extends String)), or an enum are dropped — the same information is available through ConceptInfo and the per-concept :py[`ModelVerbalizer.explain_concept`](/api/python/v1.6/agent/cortex/verbalize/modelverbalizer_class#method-explain_concept) output.

Returns:

• str - Sorted relationship readings, one per line.

.explain_concept()

ModelVerbalizer.explain_concept(concept: str) -> str

Return a structured per-concept summary derived from the model.

Two dispatch shapes:

• "Concept" — concept-level summary with sections (each omitted when empty):

  • Concept: <name> (extends ...) header
  • Identifiers:, Properties:, Relationships:
  • Data sources:
  • Computed: — one signature line per rule-defined relationship owned by the concept (E1). Source-table data-loading rules and FK-bridge rules (target type is an entity) are filtered out via the metamodel; the head’s owning concept must match (primary-concept filter, [[cortex_verbalize_explain_overflow_options.md]]).

• "Concept.member" — drill-down view (E3) for a computed relationship. Returns a Prolog-style rendering of every rule body defining that relationship: Owner.rel :- body1, body2.

Parameters:

• concept

  (str) - The concept name or "Concept.member" drill-down id.

Returns:

• str - Natural-language explanation derived from rai_inspect.schema(model) plus rule attribution from model.defines.

Inheritance Hierarchy

Subclassed By

 agent > cortex > verbalize
└──  SourceCodeVerbalizer