What's new in CoreSpotlight

public protocol ContactResolver : Sendable {

    /// Returns the current user's contact information.
    func userIdentity() -> ResolvedContact
}

public struct CoreSpotlightSource : @unchecked Sendable {

    /// The attributes to fetch for each item and provide to the model.
    ///
    /// Use this property to minimize the number of round trips between the Spotlight search tool and
    /// your content. When you index your app’s content, you create a ``CSSearchableItemAttributeSet``
    /// for each item and fill it with metadata about that item. For example, retrieve the display name,
    /// author, and subject attributes by setting this property to `[.displayName, .authors, .subject]`.
    /// For each item, the tool retrieves the attributes you specify and delivers them to the model.
    ///
    /// The default value of this property is an empty set, which delivers only the item’s identifier to the model.
    public var fetchAttributes: [SearchableItemAttribute]

    /// The maximum number of results to retrieve from this source.
    ///
    /// Use this property to limit the number of results the Spotlight search tool returns to the model.
    /// If you specify `nil`, the tool returns all results that match the model’s query. This maximum
    /// applies only to the current source, and doesn’t include results from other sources, which have
    /// their own maximum values. The default value of this property is `nil`.
    public var maximumResultCount: Int?

    /// Options you use to specify access to restricted content.
    ///
    /// Use this property to specify access to sensitive items like email.
    public var sourceOptions: CSSearchQueryContext.SourceOptions

    /// An optional delegate object you use to provide additional data about items in search results.
    ///
    /// Use this delegate object to provide detailed information about your searchable items to the model. Some
    /// information in the Spotlight index is searchable, but not recoverable. For example, Spotlight
    /// can’t recover the original text or HTML content you supply for an item. When it needs this information,
    /// the search tool asks your delegate to provide a new ``CSSearchableItem`` object with the same
    /// content as the original one.
    ///
    /// If you configure the Spotlight search tool to use the ``SpotlightSearchTool/GuidanceLevel/dynamic(_:)``
    /// guidance level, you can also use this delegate to fill in any missing attributes. Dynamic profiles cause
    /// the tool to search specific attributes of each item. If those attributes aren’t available in the index,
    /// the tool uses your delegate to recreate the item.
    ///
    /// If you don't provide a delegate object, the tool uses only the information it retrieves from the source.
    public var searchableIndexDelegate: (any CSSearchableIndexDelegate)?

    public init(searchableIndexDelegate: (any CSSearchableIndexDelegate)? = nil, fetchAttributes: [SearchableItemAttribute] = [])

    public init(fetchAttributes: [SearchableItemAttribute] = [])
}

public protocol CustomStage : Generable, Decodable, Encodable, Sendable {

    /// The stage type name as it appears in the pipeline (e.g., "sentiment").
    static var name: String { get }

    /// A human-readable description of what this stage does.
    static var description: String { get }

    /// The data types this stage accepts as input.
    static var inputTypes: [SearchPipelineDataType] { get }

    /// The data types this stage produces as output.
    static var outputTypes: [SearchPipelineDataType] { get }

    nonisolated(nonsending) func execute(items: [CSSearchableItem]) async throws -> SearchPipelineData

    nonisolated(nonsending) func execute(scoredItems: [ScoredSearchableItem]) async throws -> SearchPipelineData

    nonisolated(nonsending) func execute(groupedItems: [SearchableItemAttribute : [CSSearchableItem]]) async throws -> SearchPipelineData

    nonisolated(nonsending) func execute(count: Int) async throws -> SearchPipelineData

    nonisolated(nonsending) func execute(table: SearchResultsTable) async throws -> SearchPipelineData

    nonisolated(nonsending) func execute(statisticName: String, value: Double) async throws -> SearchPipelineData

    nonisolated(nonsending) func execute(text: String) async throws -> SearchPipelineData
}

public struct FileSource : Sendable {

    /// The attributes to fetch for each file or directory and provide to the model.
    ///
    /// Use this property to minimize the number of round trips between the Spotlight search tool and
    /// your content. When you index your app’s content, you create a ``CSSearchableItemAttributeSet``
    /// for each item and fill it with metadata about that item. For example, you might specify the
    /// title of a document and the number of pages it contains. For each item the Spotlight search
    /// tool identifies as a result, the tool retrieves the attributes you specify in this property.
    /// The tool delivers these attributes together with the item’s identifier to the model so it
    /// doesn’t have to request them later.
    ///
    /// The default value of this property is an empty set, which delivers only the item’s identifier to the model.
    public var fetchAttributes: [SearchableItemAttribute]

    /// The maximum number of results to retrieve from this source.
    ///
    /// Use this property to limit the number of results the Spotlight search tool returns to the model.
    /// If you specify `nil`, the tool returns all results that match the model’s query. This maximum
    /// applies only to the current source, and doesn’t include results from other sources, which have
    /// their own maximum values. The default value of this property is `nil`.
    public var maximumResultCount: Int?

    /// The directories to search.
    ///
    /// Specify one or more directory URLs to scope the search to those directories and their subdirectories.
    /// The default value of this property is an empty array, which searches all indexed volumes.
    public var scopes: [URL]

    public init(fetchAttributes: [SearchableItemAttribute] = [])
}

public struct ResolvedContact : Sendable {

    /// Display name (e.g., "John Appleseed" or "Acme Corp").
    public var displayName: String

    /// Alternate name strings the contact may be known by.
    public var names: [String]

    /// Structured name components for locale-aware matching.
    public var nameComponents: [PersonNameComponents]

    /// Email addresses associated with this contact.
    public var emailAddresses: [String]

    /// Phone numbers associated with this contact.
    public var phoneNumbers: [String]

    public init(displayName: String)
}

public struct ScoredSearchableItem : Sendable {

    /// The underlying searchable item.
    public let item: CSSearchableItem

    /// A relevance score assigned by the pipeline stage; higher values indicate
    /// greater relevance. The scale is stage-defined.
    public let score: Double

    public init(item: CSSearchableItem, score: Double)
}

public struct SearchableItemAttribute : Hashable, Sendable, RawRepresentable {

    /// The corresponding value of the raw type.
    ///
    /// A new instance initialized with `rawValue` will be equivalent to this
    /// instance. For example:
    ///
    ///     enum PaperSize: String {
    ///         case A4, A5, Letter, Legal
    ///     }
    ///
    ///     let selectedSize = PaperSize.Letter
    ///     print(selectedSize.rawValue)
    ///     // Prints "Letter"
    ///
    ///     print(selectedSize == PaperSize(rawValue: selectedSize.rawValue)!)
    ///     // Prints "true"
    public let rawValue: String

    /// Creates a new instance with the specified raw value.
    ///
    /// If there is no value of the type that corresponds with the specified raw
    /// value, this initializer returns `nil`. For example:
    ///
    ///     enum PaperSize: String {
    ///         case A4, A5, Letter, Legal
    ///     }
    ///
    ///     print(PaperSize(rawValue: "Legal"))
    ///     // Prints "Optional(PaperSize.Legal)"
    ///
    ///     print(PaperSize(rawValue: "Tabloid"))
    ///     // Prints "nil"
    ///
    /// - Parameter rawValue: The raw value to use for the new instance.
    public init(rawValue: String)

    /// The raw type that can be used to represent all values of the conforming
    /// type.
    ///
    /// Every distinct value of the conforming type has a corresponding unique
    /// value of the `RawValue` type, but there may be values of the `RawValue`
    /// type that don't have a corresponding value of the conforming type.
    @available(macOS 27.0, iOS 27.0, *)
    @available(tvOS, unavailable)
    @available(watchOS, unavailable)
    public typealias RawValue = String
}

extension SearchableItemAttribute {

    public static let displayName: SearchableItemAttribute

    public static let alternateNames: SearchableItemAttribute

    public static let path: SearchableItemAttribute

    public static let contentURL: SearchableItemAttribute

    public static let thumbnailURL: SearchableItemAttribute

    public static let thumbnailData: SearchableItemAttribute

    public static let darkThumbnailURL: SearchableItemAttribute

    public static let relatedUniqueIdentifier: SearchableItemAttribute

    public static let weakRelatedUniqueIdentifier: SearchableItemAttribute

    public static let metadataModificationDate: SearchableItemAttribute

    public static let contentType: SearchableItemAttribute

    public static let contentTypeTree: SearchableItemAttribute

    public static let keywords: SearchableItemAttribute

    public static let title: SearchableItemAttribute

    public static let textContent: SearchableItemAttribute

    public static let version: SearchableItemAttribute

    public static let userCreated: SearchableItemAttribute

    public static let userOwned: SearchableItemAttribute

    public static let userCurated: SearchableItemAttribute

    public static let rankingHint: SearchableItemAttribute

    public static let domainIdentifier: SearchableItemAttribute

    public static let supportsPhoneCall: SearchableItemAttribute

    public static let supportsNavigation: SearchableItemAttribute

    public static let containerTitle: SearchableItemAttribute

    public static let containerDisplayName: SearchableItemAttribute

    public static let containerIdentifier: SearchableItemAttribute

    public static let containerOrder: SearchableItemAttribute

    public static let subject: SearchableItemAttribute

    public static let theme: SearchableItemAttribute

    public static let contentDescription: SearchableItemAttribute

    public static let identifier: SearchableItemAttribute

    public static let audiences: SearchableItemAttribute

    public static let fileSize: SearchableItemAttribute

    public static let pageCount: SearchableItemAttribute

    public static let pageWidth: SearchableItemAttribute

    public static let pageHeight: SearchableItemAttribute

    public static let securityMethod: SearchableItemAttribute

    public static let creator: SearchableItemAttribute

    public static let encodingApplications: SearchableItemAttribute

Truncated.

public struct SearchCount : Sendable {

    /// The count value.
    public let value: Int

    /// A short description of what was counted (e.g., "Emails from John since 2003").
    public let header: String?

    public init(value: Int, header: String? = nil)
}

public struct SearchPipelineData : Sendable {

    /// The result payload produced by a stage.
    public let payload: SearchPipelineData.Payload

    public init(payload: SearchPipelineData.Payload)

    /// The typed variants of data a pipeline stage can produce or consume.
    ///
    /// `@unchecked Sendable` because `CSSearchableItem` is not `Sendable`.
    /// Pipeline stages must not mutate items received from prior stages.
    public enum Payload : @unchecked Sendable {

        /// Items from a Spotlight query.
        case items([CSSearchableItem])

        /// Items annotated with caller-assigned relevance scores.
        case scoredItems([ScoredSearchableItem])

        /// Items partitioned by an attribute value (e.g. content type).
        case groupedItems([SearchableItemAttribute : [CSSearchableItem]])

        /// A scalar count derived from items (e.g., 47).
        case count(Int)

        /// Tabulated data — rows of labeled values.
        case table(SearchResultsTable)

        /// A scalar statistic (sum, average, max, min, median, stddev).
        case statistic(name: String, value: Double)

        /// LLM-generated text summary or analysis.
        case text(String)
    }
}

extension SearchPipelineData {

    public static func items(_ items: [CSSearchableItem]) -> SearchPipelineData

    public static func scoredItems(_ items: [ScoredSearchableItem]) -> SearchPipelineData

    public static func groupedItems(_ groups: [SearchableItemAttribute : [CSSearchableItem]]) -> SearchPipelineData

    public static func count(_ n: Int) -> SearchPipelineData

    public static func table(_ t: SearchResultsTable) -> SearchPipelineData

    public static func statistic(name: String, value: Double) -> SearchPipelineData

    public static func text(_ s: String) -> SearchPipelineData
}

public enum SearchPipelineDataType : String, Codable, CaseIterable, Sendable {

    /// ``CSSearchableItem`` results.
    case items

    /// ``CSSearchableItem`` results with caller-assigned scores.
    case scoredItems

    /// Items partitioned into named groups.
    case groupedItems

    /// A scalar count (e.g., "47 emails from John").
    case count

    /// Tabulated data suitable for a table or chart.
    case table

    /// A scalar statistic (sum, average, max, min, median, stddev).
    case statistic

    /// LLM-generated text summary or analysis.
    case text

    /// Creates a new instance with the specified raw value.
    ///
    /// If there is no value of the type that corresponds with the specified raw
    /// value, this initializer returns `nil`. For example:
    ///
    ///     enum PaperSize: String {
    ///         case A4, A5, Letter, Legal
    ///     }
    ///
    ///     print(PaperSize(rawValue: "Legal"))
    ///     // Prints "Optional(PaperSize.Legal)"
    ///
    ///     print(PaperSize(rawValue: "Tabloid"))
    ///     // Prints "nil"
    ///
    /// - Parameter rawValue: The raw value to use for the new instance.
    public init?(rawValue: String)

    /// A type that can represent a collection of all values of this type.
    @available(macOS 27.0, iOS 27.0, *)
    @available(tvOS, unavailable)
    @available(watchOS, unavailable)
    public typealias AllCases = [SearchPipelineDataType]

    /// The raw type that can be used to represent all values of the conforming
    /// type.
    ///
    /// Every distinct value of the conforming type has a corresponding unique
    /// value of the `RawValue` type, but there may be values of the `RawValue`
    /// type that don't have a corresponding value of the conforming type.
    @available(macOS 27.0, iOS 27.0, *)
    @available(tvOS, unavailable)
    @available(watchOS, unavailable)
    public typealias RawValue = String

    /// A collection of all values of this type.
    nonisolated public static var allCases: [SearchPipelineDataType] { get }

    /// The corresponding value of the raw type.
    ///
    /// A new instance initialized with `rawValue` will be equivalent to this
    /// instance. For example:
    ///
    ///     enum PaperSize: String {
    ///         case A4, A5, Letter, Legal
    ///     }
    ///
    ///     let selectedSize = PaperSize.Letter
    ///     print(selectedSize.rawValue)
    ///     // Prints "Letter"
    ///
    ///     print(selectedSize == PaperSize(rawValue: selectedSize.rawValue)!)
    ///     // Prints "true"
    public var rawValue: String { get }
}

extension SearchPipelineDataType : Equatable {
}

extension SearchPipelineDataType : Hashable {
}

extension SearchPipelineDataType : RawRepresentable {
}

public struct SearchResultsTable : Sendable {

    /// What this table represents (e.g., "Emails per month from John").
    public let header: String?

    /// Column definitions with name and type hint.
    public let columns: [SearchResultsTable.Column]

    /// Data rows — each row's values array matches `columns` by index.
    public let rows: [SearchResultsTable.Row]

    public init(header: String? = nil, columns: [SearchResultsTable.Column], rows: [SearchResultsTable.Row])

    public struct Column : Sendable {

        public let name: String

        public let type: SearchResultsTable.ValueType

        public init(name: String, type: SearchResultsTable.ValueType)
    }

    public enum ValueType : Sendable {

        case string

        case integer

        case double

        case date

        case boolean

        /// Returns a Boolean value indicating whether two values are equal.
        ///
        /// Equality is the inverse of inequality. For any values `a` and `b`,
        /// `a == b` implies that `a != b` is `false`.
        ///
        /// - Parameters:
        ///   - lhs: A value to compare.
        ///   - rhs: Another value to compare.
        public static func == (a: SearchResultsTable.ValueType, b: SearchResultsTable.ValueType) -> Bool

        /// Hashes the essential components of this value by feeding them into the
        /// given hasher.
        ///
        /// Implement this method to conform to the `Hashable` protocol. The
        /// components used for hashing must be the same as the components compared
        /// in your type's `==` operator implementation. Call `hasher.combine(_:)`
        /// with each of these components.
        ///
        /// - Important: In your implementation of `hash(into:)`,
        ///   don't call `finalize()` on the `hasher` instance provided,
        ///   or replace it with a different instance.
        ///   Doing so may become a compile-time error in the future.
        ///
        /// - Parameter hasher: The hasher to use when combining the components
        ///   of this instance.
        public func hash(into hasher: inout Hasher)

        /// The hash value.
        ///
        /// Hash values are not guaranteed to be equal across different executions of
        /// your program. Do not save hash values to use during a future execution.
        ///
        /// - Important: `hashValue` is deprecated as a `Hashable` requirement. To
        ///   conform to `Hashable`, implement the `hash(into:)` requirement instead.
        ///   The compiler provides an implementation for `hashValue` for you.
        public var hashValue: Int { get }
    }

    public struct Row : Sendable {

        public let values: [SearchResultsTable.Value]

        public init(values: [SearchResultsTable.Value])
    }

    /// A cell value — typed so the host app can format, sort, or export correctly.

Truncated.

extension SearchResultsTable.ValueType : Equatable {
}

extension SearchResultsTable.ValueType : Hashable {
}

public struct SearchSource : Sendable {

    /// A source that retrieves data from the app’s Spotlight index.
    public static var coreSpotlight: SearchSource { get }

    /// Returns a source that retrieves data from the app’s Spotlight index.
    public static func coreSpotlight(_ source: CoreSpotlightSource) -> SearchSource

    /// A source that retrieves data from the files and directories you specify.
    public static var files: SearchSource { get }

    /// Returns a source that retrieves data from the files and directories you specify.
    public static func files(_ source: FileSource) -> SearchSource
}

public struct SearchStatistic : Sendable {

    /// The statistic name (e.g., "average", "max", "total").
    public let name: String

    /// The computed value.
    public let value: Double

    /// A short description of what was computed (e.g., "Average file size").
    public let header: String?

    public init(name: String, value: Double, header: String? = nil)
}

public struct SearchTextResult : Sendable {

    /// The text body.
    public let body: String

    /// A short description of what this text represents.
    public let header: String?

    public init(body: String, header: String? = nil)
}

public struct SpotlightSearchTool : Tool, Sendable {

    /// A unique name for the tool, such as "get_weather", "toggleDarkMode", or "search contacts".
    public var name: String

    /// A natural language description of when and how to use the tool.
    public var description: String { get }

    /// Dynamic schema: use the native tool's schema based on capabilities.
    public var parameters: GenerationSchema { get }

    /// On-device uses includesSchemaInInstructions: true;
    /// .dynamic uses false (schema in compact notation prose instead).
    public var includesSchemaInInstructions: Bool { get }

    /// A set of search results with routing metadata for host app consumption.
    public struct SearchReply : Sendable {

        /// What this set of results represents — determines display strategy.
        public enum Content : @unchecked Sendable {

            /// Ssearch result items (emails, files, etc.) — display as a list.
            case items([CSSearchableItem])

            /// Items partitioned by an attribute value (e.g. content type).
            case groupedItems([SearchableItemAttribute : [CSSearchableItem]])

            /// Items annotated with caller-assigned relevance scores.
            case scoredItems([ScoredSearchableItem])

            /// A scalar count answer (e.g., "How many emails from John?" → 47).
            case count(SearchCount)

            /// Tabulated data — rows of labeled values, suitable for a table or chart.
            case table(SearchResultsTable)

            /// A scalar statistic (sum, average, max, min, median, stddev).
            case statistic(SearchStatistic)

            /// LLM-generated text summary or analysis.
            case text(SearchTextResult)
        }

        /// The result content — determines what to display and how.
        public let content: SpotlightSearchTool.SearchReply.Content

        /// A short, LLM-generated description of what the result represents.
        ///
        /// Use this property to determine what information the model requested. For complex requests,
        /// the tool provides the simplest string that describes the current portion of the task. For
        /// example, the string might contain a value like "Attachments from John" or "Documents about the deadline."
        /// You can display the string in your app’s interface or use it as an accessibility label.
        public let label: String?

        /// An opaque value you use to identify the query that generated the reply.
        ///
        /// When processing a request, a model might create multiple queries to find and refine search
        /// results. Use this property to associate replies with a specific query. The token itself is
        /// an opaque value you save and compare against tokens in other search replies. You might use
        /// this value to partition the data you receive.
        public let queryToken: SpotlightSearchTool.SearchReply.QueryToken

        /// An opaque value you use to identify the pipeline stage that generated the reply.
        ///
        /// The Spotlight search tool provides several ways to search content, and implements each technique
        /// as an independent stage. For a given query, a model can run multiple stages to generate the
        /// results of the query. Use this property to associate search reply structures with a specific
        /// stage. The token itself is an opaque value you save and compare against tokens in other
        /// search replies. You might use this value to partition the data you receive.
        public let stageToken: SpotlightSearchTool.SearchReply.StageToken

        /// An indicator of whether the current query is complete or still in progress.
        ///
        /// The of this property is ``SpotlightSearchTool/SearchReply/Status/partial`` when the system has
        /// more replies to deliver for the same ``queryToken`` value. When delivering the last reply for
        /// a query, the tool sets this value to ``SpotlightSearchTool/SearchReply/Status/complete``. Use
        /// this value to track changes to the current query. For example, you might choose to partition
        /// data for each query and display them separately in your interface.
        public let status: SpotlightSearchTool.SearchReply.Status

Truncated.

extension SpotlightSearchTool.FormatLevel : Equatable {
}

extension SpotlightSearchTool.FormatLevel : Hashable {
}

extension SpotlightSearchTool.SearchReply.Status : Equatable {
}

extension SpotlightSearchTool.SearchReply.Status : Hashable {
}

public struct UTTypeResolutionResult : @unchecked Sendable {

    /// The resolved UTType identifier (e.g., "public.message", "public.data")
    public let resolvedType: String

    /// Confidence level in the resolution [0.0, 1.0]
    ///
    /// - 0.0-0.5: Low confidence - may be incorrect
    /// - 0.5-0.8: Moderate confidence - probably correct
    /// - 0.8-1.0: High confidence - very likely correct
    public let confidence: Double

    /// Name of the resolution strategy that produced this result
    ///
    /// Examples: "hierarchy", "mapping", "fallback"
    public let strategyUsed: String

    /// Hierarchy path taken during resolution
    ///
    /// Ordered from specific to general, showing the UTType hierarchy traversal.
    /// Example: ["com.apple.mail.emlx", "public.message", "public.data"]
    public let resolutionPath: [String]

    /// Additional context and metadata about the resolution
    ///
    /// May contain strategy-specific information useful for debugging or validation.
    /// Common keys: "source", "fallback_reason", "hierarchy_depth"
    public let metadata: [String : Any]

    /// Create a UTType resolution result with full parameters
    ///
    /// - Parameters:
    ///   - resolvedType: The resolved UTType identifier (must not be empty)
    ///   - confidence: Confidence level (will be clamped to [0.0, 1.0])
    ///   - strategyUsed: Strategy name (must not be empty)
    ///   - resolutionPath: Hierarchy path taken during resolution
    ///   - metadata: Additional context (default: empty dictionary)
    ///
    /// - Note: Confidence values outside [0.0, 1.0] are automatically clamped
    /// - Note: Empty resolvedType or strategyUsed will trigger assertion in debug builds
    public init(resolvedType: String, confidence: Double, strategyUsed: String, resolutionPath: [String], metadata: [String : Any] = [:])

    /// Create a UTType resolution result with minimal parameters
    ///
    /// Convenience initializer for simple cases without path tracking or metadata.
    ///
    /// - Parameters:
    ///   - resolvedType: The resolved UTType identifier (must not be empty)
    ///   - confidence: Confidence level (will be clamped to [0.0, 1.0])
    ///   - strategyUsed: Strategy name (must not be empty)
    public init(resolvedType: String, confidence: Double, strategyUsed: String)
}

public protocol UTTypeResolutionStrategy {

    /// Unique identifier for this resolution strategy
    ///
    /// Used for debugging, logging, and identifying which strategy produced a result.
    /// Should be concise and descriptive (e.g., "hierarchy", "mapping", "fallback").
    var name: String { get }

    /// Attempt to resolve a UTType identifier
    ///
    /// - Parameter originalType: The UTType identifier to resolve (e.g., "com.apple.mail.emlx")
    /// - Returns: Resolution result if successful, `nil` if strategy cannot handle this type
    /// - Throws: Only for critical errors (network failure, invalid input format, etc.)
    ///
    /// **Implementation Guidelines:**
    /// - Validate input format before attempting resolution
    /// - Return `nil` for types outside strategy's domain
    /// - Populate resolution path for debugging
    /// - Set appropriate confidence based on resolution method
    /// - Include relevant metadata for downstream validation
    nonisolated(nonsending) func resolve(_ originalType: String) async throws -> UTTypeResolutionResult?
}

public struct Configuration : Sendable {

    /// The data sources and options to use during a search.
    ///
    /// Use this property to specify where you want ``SpotlightSearchTool`` to look for your app’s data.
    /// Fill this property with ``CoreSpotlightSource`` or ``FileSource`` types. If you specify multiple
    /// search sources, the tool searches all of them and delivers the merged results to the model. Each
    /// source object also has options about how much data to retrieve from the source, which you can use
    /// to control how much data you send to the model.
    ///
    /// If you don’t specify a value for this property, the search tool uses a default ``CoreSpotlightSource``
    /// to search your app’s Spotlight index.
    public var sources: [SearchSource]

    /// Options you use to guide the search process that the tool uses to retrieve results.
    ///
    /// The Spotlight search tool employs many techniques to look for results, but some techniques might
    /// not be relevant or necessary for your content. Use this property to offer guidance on how to search
    /// for your content, and to reduce the amount of data the tool delivers to the model. If you don’t
    /// specify custom guidance, the search tool uses all availble techniques, which can take extra time
    /// to run and consume additional resources.
    public var guide: SpotlightSearchTool.Guide?

    /// A custom type you use to identify the owner of your app’s data.
    ///
    /// Use this property to provide additional context about the person using your app. The model uses
    /// this information to help resolve first-person pronouns in prompts that indicate ownership of a
    /// particular data item. Provide any information about the person that makes sense for your app.
    /// For example, a communications app might include the person’s name and the phone number or email
    /// associated with their account.
    ///
    /// For information about how to create a contact resolver, see <doc:making-your-indexed-content-available-to-foundation-models>.
    public var contactResolver: (any ContactResolver)?

    /// Custom pipeline stages you use to help the Spotlight search tool generate results.
    ///
    /// Provide a custom stage if you have custom code for determining search results. For example, you might
    /// use a custom stage to provide the Spotlight search tool with app-managed relevance scores. The tool
    /// makes your custom stages available to the model, which determines whether to run them based on the prompt.
    ///
    /// For more information about creating a custom stage, see <doc:making-your-indexed-content-available-to-foundation-models>.
    public var customStages: [any CustomStage]

    public init(sources: [SearchSource] = [], guide: SpotlightSearchTool.Guide? = nil, contactResolver: (any ContactResolver)? = nil, customStages: [any CustomStage] = [])
}

public struct ContentDomain : Sendable {

    /// Music, podcasts, voice memos, and other audio content.
    public static var audio: SpotlightSearchTool.ContentDomain { get }

    /// Music, podcasts, voice memos, and other audio content with custom attribute mapping.
    public static func audio(_ config: SpotlightSearchTool.ContentDomain.Audio) -> SpotlightSearchTool.ContentDomain

    /// Calendar events, meetings, and scheduled items.
    public static var calendar: SpotlightSearchTool.ContentDomain { get }

    /// Calendar events, meetings, and scheduled items with custom attribute mapping.
    public static func calendar(_ config: SpotlightSearchTool.ContentDomain.Calendar) -> SpotlightSearchTool.ContentDomain

    /// Email, messaging, and other person-to-person communication.
    public static var communications: SpotlightSearchTool.ContentDomain { get }

    /// Email, messaging, and other person-to-person communication with custom attribute mapping.
    public static func communications(_ config: SpotlightSearchTool.ContentDomain.Communications) -> SpotlightSearchTool.ContentDomain

    /// Documents, notes, and text-heavy content.
    public static var documents: SpotlightSearchTool.ContentDomain { get }

    /// Documents, notes, and text-heavy content with custom attribute mapping.
    public static func documents(_ config: SpotlightSearchTool.ContentDomain.Documents) -> SpotlightSearchTool.ContentDomain

    /// Any items with title, text, and dates.
    public static var items: SpotlightSearchTool.ContentDomain { get }

    /// Any items with title, text, and dates with custom attribute mapping.
    public static func items(_ config: SpotlightSearchTool.ContentDomain.Items) -> SpotlightSearchTool.ContentDomain

    /// Photos, videos, and other visual content.
    public static var visualMedia: SpotlightSearchTool.ContentDomain { get }

    /// Photos, videos, and other visual content with custom attribute mapping.
    public static func visualMedia(_ config: SpotlightSearchTool.ContentDomain.VisualMedia) -> SpotlightSearchTool.ContentDomain
}

public enum FormatLevel : Sendable {

    /// Full, structured encoded
    case structured

    /// Compact encoding
    case compact

    /// Returns a Boolean value indicating whether two values are equal.
    ///
    /// Equality is the inverse of inequality. For any values `a` and `b`,
    /// `a == b` implies that `a != b` is `false`.
    ///
    /// - Parameters:
    ///   - lhs: A value to compare.
    ///   - rhs: Another value to compare.
    public static func == (a: SpotlightSearchTool.FormatLevel, b: SpotlightSearchTool.FormatLevel) -> Bool

    /// Hashes the essential components of this value by feeding them into the
    /// given hasher.
    ///
    /// Implement this method to conform to the `Hashable` protocol. The
    /// components used for hashing must be the same as the components compared
    /// in your type's `==` operator implementation. Call `hasher.combine(_:)`
    /// with each of these components.
    ///
    /// - Important: In your implementation of `hash(into:)`,
    ///   don't call `finalize()` on the `hasher` instance provided,
    ///   or replace it with a different instance.
    ///   Doing so may become a compile-time error in the future.
    ///
    /// - Parameter hasher: The hasher to use when combining the components
    ///   of this instance.
    public func hash(into hasher: inout Hasher)

    /// The hash value.
    ///
    /// Hash values are not guaranteed to be equal across different executions of
    /// your program. Do not save hash values to use during a future execution.
    ///
    /// - Important: `hashValue` is deprecated as a `Hashable` requirement. To
    ///   conform to `Hashable`, implement the `hash(into:)` requirement instead.
    ///   The compiler provides an implementation for `hashValue` for you.
    public var hashValue: Int { get }
}

public enum GuidanceLevel : Sendable {

    /// An option to use all available search techniques.
    case complete

    /// An option to search only specific types of content.
    ///
    /// Choose this option to search attributes only for the specified types of content. You can
    /// initialize this value with one or more domains, each of which specifies a particular type
    /// of content. During a search, the Spotlight search tool considers only the attributes in
    /// the specified domains. The tool also sends data back to the model in a compact format that’s
    /// more suitable for models with limited-size context windows.
    case focused(SpotlightSearchTool.ContentDomain = .items)

    /// An option to search using only the specified techniques.
    ///
    /// Choose this option to specify the subset of search techniques to use on your content. The
    /// ``SpotlightSearchTool/GuidanceProfile`` structure you specify contains properties with the
    /// available search techniques. Enable the ones that apply to your app’s content and disable
    /// any that don’t apply. For example, if you want to perform only literal searches on strings,
    /// enable the ``SpotlightSearchTool/GuidanceProfile/textMatch`` property and disable the
    /// ``SpotlightSearchTool/GuidanceProfile/similarityMatch`` property.
    case dynamic(SpotlightSearchTool.GuidanceProfile)
}

public struct GuidanceProfile : Sendable {

    /// A Boolean value that indicates whether to perform keyword-based text matching on your content.
    ///
    /// Set the value of this property is `true` to give the model the option to perform lexical matching on
    /// text content. If you don’t specify a value for this property, the default value is `false`.
    public var textMatch: Bool?

    /// A Boolean value that indicates whether to perform semantic similarity matching on your content.
    ///
    /// Set the value of this property true `true` to give the model the option to perform semantic searches of
    /// content. This approach allows the search to return results that match the intent of the provided string
    /// and not just the actual search term. For example, if model performs a semantic match against the word
    /// "star", the tool can match items that contain the text "star", "sun", or "Betelgeuse". If you don’t specify
    /// a value for this property, the default value is `false`.
    public var similarityMatch: Bool?

    /// A Boolean value that indicates whether to determine matches using numerical values.
    ///
    /// Set the value of this property to `true` to give the model the option to compare numerical values. For example,
    /// you might enable this option if your content contains Boolean attributes, star ratings, or any other
    /// attributes with numerical values. If you don’t specify a value for this property, the default value is `false`.
    public var numericMatch: Bool?

    /// A Boolean value that indicates whether to determine matches using date or time values.
    ///
    /// Set the value of this property to `true` to give the model the option to filter results based on date or time
    /// values. For example, you might enable this option if your items contain a start date or end date. If you
    /// don’t specify a value for this property, the default value is `false`.
    public var dates: Bool?

    /// A Boolean value that indicates whether to determine matches using the presence of specific people.
    ///
    /// Set the value of this property to `true` to give the model the option to match values based on references
    /// to people. For example, you might enable this option to match items with a specific creator or author
    /// value. If you don’t specify a value for this property, the default value is `false`.
    public var people: Bool?

    /// A Boolean value that indicates whether to determine matches using an item’s type.
    ///
    /// Set the value of this property to `true` to give the model the option to match items based on their
    /// ``CSSearchableItemAttributes/contentType`` attribute. If you don’t specify a value for this property,
    /// the default value is `false`.
    public var contentType: Bool?

    /// The relevant attributes from your content that you want to search.
    ///
    /// Use this property to specify only the attributes that are relevant for your content. If you
    /// provide a value for this property, the search tool considers only the attributes you specify.
    /// If you don’t specify a value for this property, or set the value to `nil`, all attributes
    /// are available during searches.
    public var attributes: [SearchableItemAttribute]?

    public init(textMatch: Bool? = nil, similarityMatch: Bool? = nil, numericMatch: Bool? = nil, dates: Bool? = nil, people: Bool? = nil, contentType: Bool? = nil, attributes: [SearchableItemAttribute]? = nil)
}

public struct Guide : Sendable {

    /// The guidance for the model to use during a session.
    ///
    /// Use this property to specify custom guidance for how to search your app’s content. The default
    /// value of this property is ``SpotlightSearchTool/GuidanceLevel/complete``, which uses all available
    /// search techniques and search all content types.
    public let level: SpotlightSearchTool.GuidanceLevel

    /// The representation format for tool responses returned to the model.
    ///
    /// Controls how search results are serialized in the model's context window.
    /// Use ``FormatLevel/compact`` to reduce token consumption when
    /// working with small-context models or long conversations.
    public let format: SpotlightSearchTool.FormatLevel

    public init(level: SpotlightSearchTool.GuidanceLevel = .complete, format: SpotlightSearchTool.FormatLevel = .structured)
}

public struct Audio : Sendable {

    /// Attributes queried for the artist. Default: ``SearchableItemAttribute/artist``
    public var artist: [SearchableItemAttribute]?

    /// Attributes queried for the album. Default: ``SearchableItemAttribute/album``
    public var album: [SearchableItemAttribute]?

    /// Attributes queried for transcribed text.
    public var transcription: [SearchableItemAttribute]?

    /// Attributes queried for the recording date. Default: ``SearchableItemAttribute/contentCreationDate``
    public var date: [SearchableItemAttribute]?

    public init(artist: [SearchableItemAttribute]? = nil, album: [SearchableItemAttribute]? = nil, transcription: [SearchableItemAttribute]? = nil, date: [SearchableItemAttribute]? = nil)
}

public struct Calendar : Sendable {

    /// Attributes queried for the event organizer/host.
    public var organizer: [SearchableItemAttribute]?

    /// Attributes queried for attendees/participants. Default: ``SearchableItemAttribute/participants``
    public var attendees: [SearchableItemAttribute]?

    /// Attributes queried for the event location. Default: ``SearchableItemAttribute/city``, ``SearchableItemAttribute/stateOrProvince``
    public var location: [SearchableItemAttribute]?

    /// Attributes queried for the event date. Default: ``SearchableItemAttribute/dueDate``
    public var date: [SearchableItemAttribute]?

    public init(organizer: [SearchableItemAttribute]? = nil, attendees: [SearchableItemAttribute]? = nil, location: [SearchableItemAttribute]? = nil, date: [SearchableItemAttribute]? = nil)
}

public struct Communications : Sendable {

    /// Attributes queried for the author field. Default: ``SearchableItemAttribute/authorNames``
    public var authors: [SearchableItemAttribute]?

    /// Attributes queried for the recipient field. Default: ``SearchableItemAttribute/recipientNames``
    public var recipients: [SearchableItemAttribute]?

    /// Attributes queried for the sent date field. Default: ``SearchableItemAttribute/contentCreationDate``
    public var sent: [SearchableItemAttribute]?

    /// Attributes queried for the received date field. Default: ``SearchableItemAttribute/contentCreationDate``
    public var received: [SearchableItemAttribute]?

    /// Attributes queried for the subject/body field. Default: ``SearchableItemAttribute/textContent``
    public var topic: [SearchableItemAttribute]?

    public init(authors: [SearchableItemAttribute]? = nil, recipients: [SearchableItemAttribute]? = nil, sent: [SearchableItemAttribute]? = nil, received: [SearchableItemAttribute]? = nil, topic: [SearchableItemAttribute]? = nil)
}

public struct Documents : Sendable {

    /// Attributes queried for document authors. Default: ``SearchableItemAttribute/authorNames``
    public var authors: [SearchableItemAttribute]?

    /// Attributes queried for content keywords. Default: ``SearchableItemAttribute/textContent``
    public var keywords: [SearchableItemAttribute]?

    /// Attributes queried for the creation date. Default: ``SearchableItemAttribute/contentCreationDate``
    public var created: [SearchableItemAttribute]?

    /// Attributes queried for the modified date. Default: ``SearchableItemAttribute/contentModificationDate``
    public var modified: [SearchableItemAttribute]?

    public init(authors: [SearchableItemAttribute]? = nil, keywords: [SearchableItemAttribute]? = nil, created: [SearchableItemAttribute]? = nil, modified: [SearchableItemAttribute]? = nil)
}

public struct Items : Sendable {

    /// Attributes queried for the item title. Default: ``SearchableItemAttribute/title``
    public var title: [SearchableItemAttribute]?

    /// Attributes queried for content keywords. Default: ``SearchableItemAttribute/textContent``
    public var text: [SearchableItemAttribute]?

    /// Attributes queried for the creation date. Default: ``SearchableItemAttribute/contentCreationDate``
    public var created: [SearchableItemAttribute]?

    /// Attributes queried for the modified date. Default: ``SearchableItemAttribute/contentModificationDate``
    public var modified: [SearchableItemAttribute]?

    public init(title: [SearchableItemAttribute]? = nil, text: [SearchableItemAttribute]? = nil, created: [SearchableItemAttribute]? = nil, modified: [SearchableItemAttribute]? = nil)
}

public struct VisualMedia : Sendable {

    /// Attributes queried for people appearing in images/video. Default: ``SearchableItemAttribute/identifier``
    public var people: [SearchableItemAttribute]?

    /// Attributes queried for visual content description.
    public var description: [SearchableItemAttribute]?

    /// Attributes queried for the location. Default: ``SearchableItemAttribute/city``
    public var location: [SearchableItemAttribute]?

    /// Attributes queried for the capture date. Default: ``SearchableItemAttribute/contentCreationDate``
    public var date: [SearchableItemAttribute]?

    public init(people: [SearchableItemAttribute]? = nil, description: [SearchableItemAttribute]? = nil, location: [SearchableItemAttribute]? = nil, date: [SearchableItemAttribute]? = nil)
}