Entity System

The Entity System enables dynamic definition and management of custom data structures without code changes, with automatic schema validation and relationship tracking.

Overview

The Entity System provides flexible data modeling:

Custom Entity Types: Define any entity your business needs (Customer, Order, Product, etc.)
Schema Validation: Enforce data quality with automatic validation
Relationships: Track how entities connect to each other
Natural Language Queries: Ask questions in plain English, get answers
Automatic Discovery: Extract entities from documents automatically

Core Concepts

What are Entities?

Entities represent real-world objects in your business:

Entity Type	Example Properties	Example Relationships
Customer	name, email, tier	has_orders, located_in
Order	order_date, total, status	placed_by, contains_products
Product	name, price, category	included_in, related_to
Project	name, status, budget	owned_by, involves_customers

Entity Structure

Each entity type has:

Name: Human-readable label (e.g., "Customer")
Properties: Fields and their data types (e.g., name: string, tier: enum)
Relationships: Connections to other entities (e.g., Customer → Order)
Validation Rules: Constraints on data values

Entity Sources

Entities come from:

Source	Description	Example
User-Defined	Manually created by users	Custom business entities
Auto-Discovered	Extracted from documents	AI finds entities in text
Pre-Built	Common system entities	User, Workspace, Project
Imported	Merged from multiple sources	Consolidated entity types

How Entities Work

Creating Entity Types

Define custom entities without coding:

1. Specify Entity Name (e.g., "Customer")
2. Define Properties (name, email, tier, etc.)
3. Set Data Types (string, number, enum, etc.)
4. Add Validation Rules (required fields, formats, etc.)
5. Publish Entity Type

Working with Entities

Once defined, entities can be:

Created: Add new entity instances
Queried: Search and filter with natural language
Updated: Modify entity properties
Related: Connect to other entities
Analyzed: Track patterns and trends

Automatic Discovery

The system can discover entities from documents:

Upload Document
    ↓
AI Analyzes Content
    ↓
Extracts Potential Entities
    ↓
Suggests Entity Types
    ↓
User Approves/Merges
    ↓
Entities Added to System

Natural Language Queries

Ask questions in plain English:

Examples

"Find all customers with tier=enterprise"
"Show orders placed in the last 30 days"
"What products are frequently bought together?"
"Which customers have placed orders over $10,000?"

Query Processing

Natural Language Question
    ↓
Understands Intent
    ↓
Maps to Entity Types
    ↓
Generates Query
    ↓
Returns Results with Context

Smart Results

Queries return not just matching entities, but:

Related Entities: Connected data points
Relationships: How entities connect
Patterns: Trends and insights
Recommendations: Suggestions based on data

Entity Relationships

Relationship Types

Entities connect through relationships:

Has-A: Customer has orders
Belongs-To: Order belongs to customer
Related-To: Product related to product
Located-In: Customer located in region

Relationship Traversal

Follow connections to discover insights:

Customer → Orders → Products → Categories
    ↓
  "What do enterprise customers buy?"

Entity Governance

Access Control

Entity operations respect agent maturity:

Maturity	Allowed Operations
Student	Read-only access
Intern	Read + propose changes
Supervised	Read + write with monitoring
Autonomous	Full access

Entity Skills

Specialized operations for entities:

Query: Search and filter entities
Create: Add new entity instances
Update: Modify existing entities
Delete: Remove entities (with governance)
Analyze: Generate insights and reports

Usage Patterns

Creating Custom Entities

Use Case: Track customer support tickets

1. Create Entity Type "Ticket"
2. Define Properties:
   - title (string, required)
   - status (enum: open, in_progress, closed)
   - priority (enum: low, medium, high)
   - customer (relationship to Customer)
3. Add Validation:
   - title must not be empty
   - status must be one of the enum values
4. Publish Entity Type
5. Start Creating Tickets

Auto-Discovery Workflow

1. Upload Contract Document
2. System Extracts:
   - Parties (Customer, Vendor)
   - Dates (start, end, renewal)
   - Terms (payment, delivery)
3. Suggests Entity Types:
   - Contract
   - Contract Party
   - Contract Term
4. User Reviews and Approves
5. Entities Available for Querying

Natural Language Analysis

Question: "What is the average order value for enterprise customers?"

System:
1. Identifies: Order entity, Customer entity
2. Filters: Customer tier=enterprise
3. Calculates: Average order total
4. Returns: "$5,234 average order value"

Follow-up Questions:
- "Show trend over time"
- "Break down by region"
- "Compare to other customer tiers"

API Overview

Entity Type Management

List all entity types
Create custom entity type
Get entity type details
Update entity type schema
Delete entity type

Entity Operations

Create entity instance
Get entity by ID
Update entity
Delete entity
List entities of type

Query

Natural language query
Generate SQL from natural language
Advanced search and filtering
Relationship traversal

Schema Management

Validate entity data
Get schema suggestions
Merge entity types
View entity relationships

Best Practices

Plan Your Schema: Think about properties and relationships upfront
Start Simple: Begin with core properties, expand as needed
Use Relationships: Connect entities for richer insights
Validate Data: Enforce data quality with validation rules
Review Discoveries: Check auto-discovered entities before approving

Common Scenarios

Customer 360 Dashboard

Entity Types: Customer, Order, SupportTicket, Interaction

Natural Queries:
- "Show complete customer profile"
- "What is customer's order history?"
- "Any support issues?"
- "Last interaction date?"

Results:
- Unified customer view
- All related entities
- Interaction timeline
- Recommendations

Inventory Management

Entity Types: Product, Supplier, Warehouse, StockMovement

Natural Queries:
- "Which products are low stock?"
- "Show suppliers for product X"
- "What's the inventory turnover?"
- "Predict stockouts"

Results:
- Inventory status
- Supplier information
- Trend analysis
- Alerts and recommendations

ATOM Documentation