LLM-Friendly Naming Conventions and Relationship Guidelines for MSOs and Properties

Intended audience: ANALYSTS DEVELOPERS ADMINISTRATORS

AO Platform: 4.3

Overview

This topic describes some best practices and guidance for creating an Ontology and enrichment of the same. It also proposes naming conventions for Managed Semantic Objects (MSOs) and their fields to ensure clarity, consistency, and ease of interpretation by users. The objective is to avoid the most common mistakes by creating names that are descriptive, meaningful, and aligned with business requirements, ensuring they are LLM-compliant and user-friendly, - and ultimately ensure the best possible outcome for using the Ontology as part of any solution created with the AO Platform.

General Naming Principles

Descriptiveness: Names should be clear, informative, and avoid abbreviations to ensure readability.
Semantic Richness: Include key details such as units, data types, or status indicators to add clarity.
Consistency: Use uniform patterns across all MSOs and fields for easy understanding.
Full Words: Avoid abbreviations to reduce ambiguity. For instance, instead of abbreviations like cust, use full words like Customer.
Hierarchy and Relationships: Indicate relationships or categories where relevant.

LLM-Compliant Ontology Guidelines

LLM-Friendly MSO and Property Names

Avoid database-style abbreviations. Use descriptive, business-friendly names.
Examples: Use Customer instead of cust, First Name instead of fName, and avoid complex relationship field names like i_cust by using descriptive names, such as customer.

Reusable MSOs

Identify reusable MSOs and consolidate them for consistency.
Example: If multiple tables have a product category column with the same values and no master data table, create a single Product Category MSO and use it across related MSOs.

Unique Property Naming

As much as possible, avoid using the same name for Ontology, MSOs, and any MSO Properties. Especially, do not name an MSO and any of its Properties the same. It will just make it much harder, sometimes impossible, for an LLM to interpret a question correctly due to the ambiguities created.
Example: In a Meter MSO, avoid naming a property meter.

Property Naming when Creating Relationships with Other MSO

Make sure to change the name of an ID property if used to create a relationship with another MSO
Example: If a customerID property in a Contract MSO is linked to a Customer MSO, then once linked, the customerID property gets the datatype of “Customer” (ie the relationship MSO). Now change the customerID property name to Customer, too. Subsequently, also rerun Statistics on this property.

Common MSOs

Use standardized MSOs for common entities such as `Address`, `Amount`, or `Percentage`, and map specific fields accordingly. Also, do not create domain-specific MSOs with the same name as the common MSOs to avoid ambiguity.

Singular Naming with Accurate Plural Forms

Use singular forms for MSO names and verify that plural names in the MSO properties are correct, as auto-generated plurals may sometimes be inaccurate.
Any linguistic terms for either MSO itself or associated properties should also be added on same MSO to remove any ambiguities, eg. add synonyms such as “errors”, “faults”, and “problems” to the Meter Issues MSO to ensure that no matter how the user expresses the question relating to problems with Meters, the correct MSO will be found and question correctly interpreted.

MSO Naming Conventions

Each MSO name should accurately reflect its purpose within the system.

Content Focus: Use names that describe the main entity or concept the MSO represents.
- Examples: customer_profile, order_transaction, product_inventory.
Relationship Indicators: For MSOs representing relationships, include the related entities.
- Examples: customer_order_relationship, user_account_linkage.

Property Naming Conventions

Context-Rich Names: Include the entity or category within the name.
- Examples: first_name, total_amount.
Units of Measurement: Specify units to avoid confusion.
- Examples: weight_kilograms, total_usd.
Data Type Indication: Specify data types IF they add clarity.
- Examples: sales_amount, creation_date, but it’s unnecessary to use is_open_boolean or balance_number.
Temporal Information: Clearly indicate if a field represents a specific time or duration.
- Examples: date_of_purchase, processing_duration_days, account_creation_datetime.
Calculated Fields: Use suffixes for derived or calculated fields IF they add clarity.
- Examples: total_spend_percentage - if there’s a total_spend_amount property.

Naming Convention Examples for Common Entities

Customer Information MSO

Product Catalog MSO

Order Processing MSO

MSO Name: customer_profile

MSO Name: product_inventory

MSO Name: order_transaction

Fields:

unique_identifier
first_name
last_name
email_address
date_of_birth
account_creation_datetime
total_lifetime_value_usd

Fields:

unique_identifier
name
description
category_id
price_usd
weight_kilograms
in_stock_quantity
reorder_threshold

Fields:

unique_identifier
associated_customer_id
date_of_purchase
total_amount_usd
status
payment_method
shipping_address
estimated_delivery_date

Relationships

Please follow these guidelines when creating relationships. If relationships are not automatically discovered during the Ontology Discovery process (the prerequisite is that relationships are already configured in the data source), then make sure to add them manually.

Inner Joins: Use inner join when there are no null values in your target MSO.
Left Joins: Use left join when there may be null values in your target MSO.
Consistent Data Types: If an MSO property (e.g., `propertyA`) in one MSO references an MSO property in another MSO, `propertyA` should adopt the data type of the referenced MSO. Adjustments must be made to the relationship and sourcing properties to maintain consistency.

Value-Based Synonyms

When adding value-based synonyms, follow these guidelines.

Low Cardinality: Only add value-based synonyms for fields with a limited number of unique values (eg., less than 100).
Avoid Long Phrases: Do not use value-based synonyms for text fields with long phrases (eg., product names or company names).
Single Characters: Avoid using value-based synonyms for single character-based fields (eg., `C`, `A`). Use rule-based synonyms instead.
No Numeric Fields: Avoid value-based synonyms for numeric fields.
Handle Duplicates: Review synonyms and delete duplicates. If cases vary (eg., `CA`, `California`, `california`), define one synonym (e.g., `CA`) and list alternates.
Unique Synonyms: Avoid using the same synonym across multiple values unless necessary with an OR condition. Ensure synonyms are unique across different fields.
Please refer to the MSOs section for guidelines on creating common MSOs.

Best Practices

High Cardinality - Don’t configure value synonyms for properties with high cardinality.
Collision - Don’t configure the same value synonym for more than one MSO Property from the same or different MSO.
Alternate Word & Synonym – An alternate word should be used in a criteria, a synonym should not.
Value Synonyms for Categorical – Value synonyms should only be configured for MSO properties which are categorical in nature or have a Categorical trait.
Avoid Single-Charactered Value Synonyms – As that may lead to lot of false positive matches with common English words like “a”, “i” and some other determinants as well.
6 Gram Value Synonyms – Value synonyms spanning up to 6 words are supported as of now.
Configure Appropriate Way – Ideally, we should configure things to where they belong, eg. “meters” should be configured as the plural for Meter MSO not as synonyms even though functionally it won’t make a difference. The same is true for abbreviations.
Use Double Quotes For Text Matching – It’s a good practice to always wrap the text phrase with which matching needs to be done within “”.
Don’t Add Reserved Words - Avoid reserved words for the naming of objects, especially Common MSO names and logical operators.
- AO Reserve Words: Operators, eg. greater_than)
- Temporal Reserve Words: Q1, Q2 … FY.
- Spatial Reserve Words: miles, kilometer.
- Stopwords: “Or”, “And” “The”.
Display Names - never have 2 MSOs with the same Display Name.
Non-meaningful names, typos, or short forms - LLMs gets confused and tend to auto-correct them. (For example, “Customer Information” instead of “Custmer Infomation”, “Cust Info”).
Ignore Case - use if data values are mixed case.

Prompts

See Guide to Creating and Managing LLM Prompt Instructions for Query Generation.

LLM Descriptions for Ontology, MSOs, and MSO Properties

Ontology Description

Once you have defined the naming conventions, enter a high-level Ontology description to provide context to the MSO and MSO Property LLM descriptions. The key components of this description are:

Business Model Summary: A concise description of the business model.
MSO Descriptions: A description of the MSOs within the ontology.

Example Ontology Description:
[company_name] designs, manufactures, and sells premium [product_name] to [customer_target] globally. This ontology includes [company_name] Actual Sales, Sales Forecasting, Product Inventory, Sales Rep Performance, [other_key_MSO_names], Customer Demographics, and Subscription Management details.

Generate LLM Content

Use the Generate LLM Content in the Options > Advanced menu to generate LLM Descriptions for both MSOs and MSO Properties. Options to auto-generate for all MSOs or only for MSOs with missing LLM Descriptions.

The same process will automatically set the MSO Priority to “low” by default (same as MSO Settings configuration). Once MSO Priority has been automatically configured via the Generate LLM Content process, the user can manually set the MSO Priority according to the following options:

Low/Medium/High - no difference in 4.1.x.
None - apply to “meter_installation”, but use “low” for connected MSOs, like “meter” and “premise”.
Never - only use for stale/backup MSOs, or MSOs not yet used.

Conclusion

By adhering to these naming conventions and relationship guidelines, you create a structured, intuitive framework that enhances clarity, consistency, and LLM compliance. This systematic approach not only facilitates user understanding and reduces ambiguity but also strengthens alignment with business requirements. Furthermore, the incorporation of the LLM Ontology descriptions allows for a deeper, context-driven interpretation of MSOs and their properties, optimizing the utility and relevance of generated responses.

Contact App Orchid | Disclaimer