Contents

GenerableEntity

An interface that tells a model it can create an entity and fill in its properties directly.

Declaration

protocol GenerableEntity : TransientAppEntity

Mentioned in

Overview

The GenerableEntity protocol reduces the friction between a model’s output and your app’s custom types. The addition of this protocol to an entity type tells the model it can generate instances of the entity directly, and without using the entity’s query object. During the generation process, the model fills in the properties of the entity according to the descriptions you provide for each of its properties.

To support this protocol in one of your custom entity types, precede your type declaration with the @AppEntity macro and the generable trait, as shown in the following example. In addition to this macro, adopt the TransientAppEntity protocol to allow the system to create instances of your entity.

@AppEntity(.generable)
struct FlightSearch: TransientAppEntity {
    @Property(title: "Origin", description: "IATA code of the departure airport")
    var origin: String

    @Property(title: "Destination", description: "IATA code of the arrival airport")
    var destination: String

    @Property(title: "Date", description: "The day to depart")
    var date: Date
    // ...
}

For each declared property, include title and description parameters with values that the model can use to map its output to the required value. For example, in the preceding code, the descriptions of the origin and destination properties tell the model to fill in the property with an International Air Transport Association (IATA) code that identifies the airport.

Declare each property of a generable entity as one of the following types:

  • A plain value type, such as Int, String, or Date

  • An AppEnum type

  • Another GenerableEntity type

  • An array of one of these applicable types

Generable entities are useful as parameter types for a ToolIntent. In the following example, a person can invoke the tool with the phrase “Find a business class flight from SFO to JFK next Friday.” The tool’s one search parameter is a FlightSearch entity, which is a generable type. The model can create a FlightSearch entity instance directly and fill its properties with values it retrieves from the provided phrase. It can then call the intent’s perform() method to deliver the results.

@AppIntent(.tool)
struct SearchFlights: AppIntent {
    static let title: LocalizedStringResource = "Search Flights"
    static let description = IntentDescription("Finds flights for a route and date.")

    @Parameter(title: "Search", description: "The route and date to search")
    var search: FlightSearch

    func perform() async throws -> some ReturnsValue<[FlightEntity]> {
        .result(value: try await FlightService.search(search))
    }
}

See Also

Entity support