> ## Documentation Index
> Fetch the complete documentation index at: https://resources.athenaintel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ontology Builder

> A visual graph editor for designing and managing your workspace ontology.

The Ontology Builder is a visual workspace for defining, connecting, and managing your object types and relationships. It presents your entire data model as an interactive graph where nodes represent object types and edges represent relationships.

## Accessing the Builder

Navigate to **Ontology Builder** from the left sidebar. The builder opens to a full-screen graph canvas showing all object types and relationships in your workspace.

## The Graph Canvas

The canvas is the central workspace of the Ontology Builder. Each object type appears as a node, and each relationship appears as an edge connecting two nodes.

### Object Type Nodes

Each node displays:

* **Name and icon** — The object type name with its logo or initial letter
* **Field count** — Number of defined properties
* **Instance count** — Number of existing records of this type
* **Link count** — Number of relationships connected to this type
* **Connection handles** — Appear on hover at the edges of the node, used to create relationships

### Interaction

| Action                        | Result                                                        |
| ----------------------------- | ------------------------------------------------------------- |
| **Click a node**              | Select it and show the context actions (edit, delete, search) |
| **Double-click a node**       | Open the object type editor                                   |
| **Double-click the canvas**   | Create a new object type                                      |
| **Drag from a handle**        | Create a new relationship to another node                     |
| **Click an edge**             | Select the relationship and show its actions                  |
| **Scroll / pinch**            | Zoom in and out                                               |
| **Click and drag the canvas** | Pan the view                                                  |

### Toolbar

The top-right corner of the canvas includes controls for:

* **Fit to view** — Automatically zoom and pan to show all nodes
* **MiniMap** — A small overview of the entire graph for orientation in large ontologies

## Header Bar

The header bar at the top of the builder shows:

* **Title** — "Ontology Builder"
* **Summary stats** — Total object types, relationships, and instances
* **Delete All** — Remove the entire ontology (all types, relationships, and instances) with a single action
* **New Object Type** — Opens the object type editor to create a new type

## Creating Object Types

Click **New Object Type** or double-click the canvas to open the editor. The editor uses a split-pane layout:

<Tabs>
  <Tab title="Property Builder (Left)">
    The left panel provides a form-based interface:

    * **Name** and **Icon URL** — Identity fields at the top
    * **Description** — Explains what this object type represents
    * **Templates** — Quick-start buttons that pre-fill properties for common types (Person, Company, Deal, Client, Recruit, Place)
    * **Properties** — A drag-and-drop list where you define each property's name, type, description, and constraints
    * **Title Property** — A dropdown to select which required text property serves as the display name
  </Tab>

  <Tab title="Schema Preview (Right)">
    The right panel shows the live JSON Schema generated from your properties. It updates in real time as you make changes.

    You can also **edit the JSON directly** — changes are parsed and reflected back in the property builder. This is useful for power users who prefer working with raw schemas or want to paste in an existing schema.

    A validation indicator shows whether the current schema is **valid** or has errors.
  </Tab>
</Tabs>

## Creating Relationships

To create a relationship between two object types:

1. Hover over a node to reveal its **connection handles**
2. **Click and drag** from a handle on the source node to the target node
3. Release on the target node to open the **relationship dialog**
4. Fill in the link name, cardinality, directionality, and optional description
5. Click **Create**

The new relationship immediately appears as an edge in the graph.

## Alternative: Creating Relationships from the Context Menu

In addition to dragging between handles, you can right-click any object type node and select **New Relationship** to open the relationship dialog with that type pre-selected as the source.

## Creating Instances

You can create instances of your object types directly from the builder:

1. Right-click any object type node and select **New Instance**
2. Fill in the property fields in the creation dialog
3. Click **Create** to save the new instance

This lets you populate your ontology without switching to a separate interface.

## Using Athena to Build Your Ontology

In addition to the visual builder, you can build and manage your entire ontology conversationally using Athena's co-pilot. This is often the fastest way to bootstrap a complex ontology.

### Getting Started with the Co-Pilot

1. Open the ontology in **Spaces** by navigating with the ontology asset (or appending `?asset_ids=app_ontology` to a Spaces URL)
2. Enable the **Ontology Toolkit** in the co-pilot sidebar
3. Ask Athena to build your ontology — for example: *"Create a CRM ontology with Company, Person, and Deal types"*

### Ontology Toolkit Tools

The Ontology Toolkit provides four tools that the agent uses to manage your ontology:

<CardGroup cols={2}>
  <Card title="Create Ontology Object" icon="plus">
    Creates a new object type with a full JSON Schema definition, including properties, types, constraints, and a title property.

    **Example prompt:** *"Create a Company object type with name, domain, industry, and employee\_count fields"*
  </Card>

  <Card title="Edit Ontology Object" icon="pencil">
    Updates an existing object type — add, remove, or rename properties, change constraints, or update the description.

    **Example prompt:** *"Add a `contract_value` field to the Deal type"*
  </Card>

  <Card title="Create Ontology Link" icon="link">
    Creates a new relationship between two object types with cardinality and directionality settings.

    **Example prompt:** *"Create a many-to-one relationship from Deal to Company called belongs\_to"*
  </Card>

  <Card title="Edit Ontology Link" icon="pen-to-square">
    Updates an existing relationship — rename, change cardinality, directionality, or description.

    **Example prompt:** *"Change the Deal → Person relationship to many-to-many"*
  </Card>
</CardGroup>

### Example Prompts

Here are prompts that work well with the ontology toolkit:

| Task                      | Example Prompt                                                                                              |
| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Build a full ontology** | "Create a CRM ontology with Company, Person, and Deal types, then link them with appropriate relationships" |
| **Add a type**            | "Create a Candidate object type with name, email, resume\_url, years\_experience, and status fields"        |
| **Modify a type**         | "Add a `linkedin_url` property to the Person type"                                                          |
| **Add a relationship**    | "Create a many-to-one relationship from Deal to Company called `belongs_to`"                                |
| **Bulk operations**       | "Add 5 common properties to the Company type: website, phone, address, founded\_year, and annual\_revenue"  |

## Managing Your Ontology

### Editing

* **Object types**: Double-click a node or click edit from the context menu
* **Relationships**: Click an edge to view it in Spaces where you can edit its properties

### Searching Instances

Click the **search** action on any object type node to open a filtered search showing all instances of that type. This lets you quickly browse the records that exist for a given object type.

### Deleting

<Warning>All delete operations are permanent and cannot be undone.</Warning>

* **Single object type**: Delete from the node's context menu. This removes the type, all its instances, and all relationships that reference it.
* **Single relationship**: Delete from the edge's context menu. This removes only the link type — instances on either side are preserved.
* **Entire ontology**: Click **Delete All** in the header bar. A confirmation dialog shows exactly how many object types, relationships, and instances will be removed. Deletion proceeds sequentially with progress tracking.