# AI Agent Integration (/docs/architecture/legacy-drafts/06-ai-integration)



# AI Agent Integration [#ai-agent-integration]

This document describes how the domain definition format is designed for AI agent consumption and generation.

## Design for AI [#design-for-ai]

### Predictable Grammar [#predictable-grammar]

AI agents work best with consistent, predictable structures:

```
// Every entity follows the same pattern
entity [Name]
    "[Description]"

    attributes
        [FieldName]: [DataType] "[Description]"
        [FieldName]: [DataType]? "[Optional field description]"

    has_one [EntityName] "[Description]"
    has_many [EntityName] as [CollectionName] "[Description]"

    belongs_to [ParentEntity]
end
```

> Note: What can be done with an entity is defined in separate behaviour files (commands, queries).

### Semantic Keywords [#semantic-keywords]

Keywords convey meaning that AI can understand:

| Keyword                     | Semantic Meaning                      |
| --------------------------- | ------------------------------------- |
| `entity`, `value`, `shared` | Type of domain concept                |
| `attributes`                | Data the type holds                   |
| `belongs_to`                | Parent relationship                   |
| `has_one`                   | Single relationship                   |
| `has_many`                  | Collection relationship               |
| `involves`                  | Entities participating in a behaviour |
| `uses`                      | Reference data fields                 |
| `publishes`                 | Events produced                       |
| `changes`                   | State mutations                       |
| `?` suffix                  | Optional/nullable                     |

### Self-Documenting [#self-documenting]

Every element can have a description (in quotes), enabling AI to:

* Explain what concepts mean
* Generate appropriate implementations
* Answer questions about the domain

***

## AI Capabilities [#ai-capabilities]

### 1. Domain Understanding [#1-domain-understanding]

AI can answer questions about the domain:

```
Q: "What is a Booking?"
A: Parse entity.description → "Planned attendance for a child..."

Q: "What can you do with a Booking?"
A: Parse related commands → "PlaceBooking, CancelBooking, RecordAttendance, RecordAbsence"

Q: "What does a Booking contain?"
A: Parse entity.attributes → "Date, Status, Session times..."
```

### 2. Definition Generation [#2-definition-generation]

AI can generate definitions from natural language:

```
User: "I need to track vehicle maintenance. A vehicle belongs to a
       depot and can have scheduled services. Each service has a
       date, type, and cost."

AI generates:
- vehicle.entity
- maintenance-service.entity
- service-type.enum
- schedule-service.command
- get-vehicle-services.query
```

### 3. Validation [#3-validation]

AI can validate definitions for:

* Required fields present
* Relationship consistency
* Naming conventions
* Description completeness

### 4. Code Generation Guidance [#4-code-generation-guidance]

AI understands what code to generate from behaviours:

```
command CancelBooking
    "Cancels a booking before attendance is recorded"
    owner Booking

    // Generates:
    //   → CancelBooking command handler
    //   → BookingCancelled event
    //   → Booking.Cancel() domain method
end
```

***

## Query Interface [#query-interface]

Structured queries AI can execute against definitions:

```
// List all entities in a service
query
    type entities
    service Scheduling

// Find commands that affect an entity
query
    type commands
    affects Booking

// Get relationships for an entity
    type relationships
    entity Booking

// Find all events in domain
query
    type events

// Search by description
query
    type search
    text "attendance"
```

***

## Conversation Patterns [#conversation-patterns]

### Exploring the Domain [#exploring-the-domain]

```
User: "Describe the scheduling domain"
AI: [Reads scheduling.service]
    "The Scheduling service manages bookings, attendance, and sessions.
     It owns entities: Booking, Attendance, Absence, Session, Room.
     Key operations include placing bookings and recording attendance."

User: "How does attendance work?"
AI: [Reads booking.entity, record-attendance.command]
    "When a child arrives, the RecordAttendance command is used.
     It requires the booking, arrival time, and the adult who signed in.
     This changes the booking status to 'Attending' and creates an
     Attendance record."
```

### Modifying the Domain [#modifying-the-domain]

```
User: "Add a notes field to Booking"
AI: [Modifies booking.entity]
    "I've added an optional Notes attribute to Booking:
     Notes: text(500)? 'Additional notes about the booking'"

User: "Bookings should be able to be rescheduled"
AI: [Creates reschedule-booking.command]
    "I've created a RescheduleBooking command with:
     - Input: Booking, NewDate, NewSession, Reason
     - Changes: Booking.Date, Booking.Session
     - Publishes: BookingRescheduled"
```

***

## Tooling Support [#tooling-support]

The DSL is parsed using [Pidgin](https://github.com/benjamin-hodgson/Pidgin) parser combinators, which provides:

* Precise error messages with line/column information
* Consistent parsing across all definition types
* Easy extension for new syntax

The VS Code extension provides:

* Syntax highlighting for all file types
* Custom file icons for visual identification
* Language configuration for comments and brackets

> Note: Behaviours (what can be done with an entity) are defined in separate command/query files, not in the entity definition.

This enables:

* IDE syntax highlighting
* Parser-based validation
* AI-assisted editing