Kyvos Business Relationships Graphs - Beta
This documentation is for Kyvos 2026.9.x. To view documentation for other Kyvos versions, click here. |
|---|
Overview
A Business Relationship Graph is a Kyvos entity (like datasets and semantic models) where in you can define the concepts that exists in the business and how those concepts are related. The graph is a collection of nodes (such as Business Entities, KPIs, External Entities, and Business Concepts) connected by relations. You can add one or more semantic models as sources of the graph and use these semantic models to create nodes. Nodes can come from the dimensions and measures (KPIs) of the semantic models, and from enterprise business knowledge bases such as a discount policy.
The Business Relationship Graph provides AI agents with business context to answer a wide range of business questions, such as “Show me the sales of premium customers,” as well as WHY-type questions, root cause analysis (RCA), and recommendation-related questions. The graph gives AI agents enterprise knowledge about how the different concepts of the business relate to each other; what drives a KPI, and how business rules, policies, or external events affect KPI performance.
For example:
Profits increase with sales but decrease with discounts.
Revenue might negatively influence with increase in discounts under certain conditions or rules like for premium products.
Discounts are driven by the promotional policy.
The promotional policy depends on the season.
Graph comprises of the following elements:
Nodes: A node is a business concept like Sales Performance, Profitability etc. You can define business friendly names, tags, business context, conditions or rules etc for a node. Various pre-defined node types are available in the system like Business Entities, KPIs, External Entities, and Business Concepts
Relation connects two nodes: You can define business context, conditions or rules, weights etc. Various types of pre-defined relations are available in the system like Segmented_By, Influences etc. and you can add any new/custom relation type as and when needed and provide their description as well. Descriptions help AI agents to make graph traversal related decisions during querying
You can add Business Relationship Graph to an AI Space (as assets), and enable/disable Lookup Business Relationship tool. Kyvos Dialogs and external AI agents can look up the relevant/driver nodes for a question through this tool, identify their relations to know the nodes which impacts the driver nodes and ground their reasoning as per your enterprise knowledge rather than the general knowledge of the AI agent.
Note
To create and use the Business Relationship Graphs, all you need to do it to deploy the Graph Server through Kyvos Manager as a post-deployment step. The Graph Server stores the graphs and use it for querying and traversals.
Dialog Agent service must be enabled. The Graph Server is available for post-deployment only when the Kyvos cluster is running with Dialog Agent service.
Adding the Graph Server from Kyvos Manager
The Graph Server stores the graphs and runs the queries that traverse them. You must add the Graph Server from Kyvos Manager.
Prerequisites
Dialog Agent must be enabled (ENABLE_DIALOG_AGENT=yes in the globals.properties file). The Graph Server is available for post-deployment only when this condition is met.
To add the Graph Server, perform the following steps.
In Kyvos Manager, navigate to Kyvos and Ecosystem > Nodes and Services > Node Usage and Configurations.
Click Add Service, and then select Graph Server.
Restart the Analytical Server and the Graph Server.
Note
The Graph Server is deployed on the Kyvos Manager node; this is not configurable. Only one Graph Server instance is allowed per cluster. Using an external or managed graph service is not supported.
Generating a Business Relationship Graph in Kyvos
To generate a BR Graph using Business Relationship Graph designer in Kyvos, perform the following steps.
In the Kyvos Web Portal, navigate to AI Context > Business Relationship Graphs.
Open the folder in which you want to create the Business Relationship Graph.
In the Relationship Graph workspace, click Add Semantic Models under Sources to add semantic models and create Business Entity and KPI nodes.
Select the relationship between the required nodes in the relationship graph.
In the Relationship Properties panel, verify the Source and Target nodes.
Under Relationship Type, select the required relationship type, such as Influences.
Under Context, enter the Business Context that describes the relationship.
Enter the applicable Rules for the relationship.
Specify the Weight, if required.
To add additional relationship-specific properties, click Add Custom Properties.
To define a new relationship type, click Add New Relationship Type.
Adding a Relationship Type
Use the Add Relationship Type dialog to create a custom relationship type for the Business Relationship Graph.
In the Relationship Properties panel, click Add New Relationship Type.
In the Name field, enter a name for the relationship type. This field is required.
In the Description field, enter a description of the relationship type.
Click Add to create the relationship type.
To close the dialog without creating a relationship type, click Cancel.
Using Relationship Graph Toolbar
The relationship graph toolbar provides the following options:
Search by Node Name: Search for a specific node in the graph.
Zoom In: Increase the graph view size.
Zoom Out: Decrease the graph view size.
Fit to View: Adjust the graph to fit within the available workspace.
Refresh/Reset View: Refresh or reset the graph view.
Settings: Open the Graph Properties panel.
More Options: Access additional graph actions.
Expand/Collapse: Expand or collapse the toolbar.
Configuring Embeddings Connection
You can configure the LLM connection used to build and enrich this business relationship graph.
Open the Business Relationship Graph.
Under Advanced, click Settings.
In the Graph Embeddings and Retrieval section, select the required Embedding Connection.
Click Save to apply the configuration.
Configuring Graph Properties
Click the Settings (gear) icon on the relationship graph toolbar.
Review the Graph Properties, including:
Total Nodes
Total Relationships
Node Name Character Length
To configure additional node options, click Advance Node Settings.
Node types
Every node has a type. The type decides where the node's properties can come from.
Node type | Description |
Business Entity | A node whose properties are derived from semantic model dimensions (levels or attributes). |
KPI | A node whose properties are derived from semantic model measures. |
External Entity | Anything external to the semantic model, such as a knowledge base tool. |
Business Concept | An abstract node that acts as a hub, grouping multiple nodes into a single logical cluster. For example, Profitability can be defined by High Value Customers (Business Entity), Company Sales and Revenue (KPIs), and Discount Policy (External Entity). |
Relation types
A relation connects a source node to a target node and describes how one affects or relates to the other. Kyvos provides the following relation types. You can also add your own relation types, with a description; they are added to the list of relation types for that graph.
Table 3. Relation types
Relation type | Meaning |
Is Defined By | From a Business Concept (source) to a KPI or Business Entity (target). |
Decomposes Into | A KPI (source) breaks down into a set of KPIs (targets). |
Segmented By | A KPI (source) can be segmented by a Business Entity (target). |
Sourced From | From a KPI, Business Entity, or Business Concept (source) to an External Entity (target). |
Positive Influences | Between two KPIs that move in the same direction: an increase in the source leads to an increase in the target, and a decrease leads to a decrease. |
Negative Influences | Between two KPIs that move in opposite directions: an increase in the source leads to a decrease in the target, and a decrease leads to an increase. |
Influences | Between two KPIs where the source affects the target, but the direction of the effect is unknown. |
Generating a Business Relationship Graph with an External AI Agent
A Business Relationship Graph is stored as a JSON file (BR.json) with a strict structure. To help you generate this file automatically, Kyvos lets you export artifacts that an external AI agent can use, and then import the generated BR.json back into Kyvos. These options are available on the web interface, the REST API, and the MCP Server tool.
Important points
Ensure that the semantic model name and folder name are valid and finalized before exporting artifacts for BR Graph auto-generation. If corrections are required, regenerate the artifacts before proceeding. Importing a BR JSON generated from outdated or incorrect metadata will result in an invalid BR. Using the Try Auto Correct option on such a BR will also remove all existing content from the BR space.
During BR Graph JSON auto-generation, each Dimension is interpreted as an individual Business Entity, while Measures are generated as independent KPIs, regardless of their Measure Group association. As a result, the number of Business Entities in the generated graph is directly influenced by the dimensions in the Semantic Model. A Business Entity can contain one or more attributes or levels as its source properties. Review the generated graph structure during the JSON generation process to ensure that it aligns with the intended business representation.
Exporting Business Relationship Graph Artifacts
Artifact | Description |
Agentic Skills (ZIP file) | A skill file that you use with an external AI agent to generate the Business Relationship Graph JSON. |
Semantic model definitions (JSON file) | Used by the skill file to generate BR.json. This file is required. |
Business Relationship Graph definitions (JSON file) | Used by the skill file to edit an existing Business Relationship graph. |
Elements in the Semantic Model JSON file
Source object | Qualified name |
Semantic model | Folder name / Semantic model name |
Semantic model level | Dimension name / Hierarchy name / Level name |
Semantic model attribute | Dimension name / Attribute name |
Semantic model measure | Measure name |
To export Business Relationship Graph Artifacts, perform the following steps.
Open the required Business Relationship Graph.
Click More Options (⋯) and select Export Artifacts.
In the Export Artifacts dialog, select the artifacts to export:
Agentic Skills
Semantic Model Definitions
Business Relationship Graph Definitions
Click Export to download the selected artifacts.
The skill uses the semantic model elements when generating the graph: calculated members, calculation-only dimensions and attributes, SQL-based expressions, and scripts.
Using Exported Business Relationship Graph Artifacts in AI
After exporting the Business Relationship Graph artifacts, perform the following steps:
The export provides a BR Builder file (br-builder.zip) and a Semantic Model JSON file (semanticModelDefinition.json).
Add the BR Builder skill using the br-builder.zip file to your AI tool, such as Claude.
Use the BR Builder skill to create your own Business Relationship Graph in the AI tool.
After creating the Business Relationship Graph, save the file to import in Business Relationship Graph designer in Kyvos
Importing a Business Relationship Graph
You can upload a BR.json file to a saved or unsaved Business Relationship Graph.
To import Business Relationship Graph Artifacts, perform the following steps.
Open the required Business Relationship Graph.
Click More Options (⋯) and select Import Relationship Graph.
Upload the BR.json file on the Business Relationship Graph designer.
Kyvos validates the file type, extension, and JSON syntax.
Kyvos adds the required IDs to the graph and plots it on the canvas.
Kyvos validates the graph and shows any warnings and errors.
Edit the imported graph if needed.
Save the graph.