---
title: CustomStage
framework: corespotlight
role: symbol
role_heading: Protocol
path: corespotlight/customstage
---

# CustomStage

A custom processing stage in a Spotlight search pipeline.

## Declaration

```swift
protocol CustomStage : Generable, Decodable, Encodable, Sendable
```

## Mentioned in

Making your indexed content available to Foundation Models

## Overview

Overview Conform your struct to this protocol to add a processing stage that the pipeline can select and execute. Declare the payload types your stage handles via inputTypes, then implement only the typed execute overload(s) that match. The framework routes each incoming payload to the correct overload; unimplemented overloads throw fatalError by default. Stages may run in parallel — do not depend on execution order. Use the static member lookup pattern so stages can be configured with leading dot syntax: struct SentimentStage: CustomStage {     static var name: String { "sentiment" }     static var description: String { "Scores search results by sentiment" }     static var inputTypes: [SearchPipelineDataType] { [.items] }     static var outputTypes: [SearchPipelineDataType] { [.scoredItems] }

var mode: String

func execute(items: [CSSearchableItem]) async throws -> SearchPipelineData {         let scored = items.map { item in             ScoredSearchableItem(item: item,                                  score: SentimentAnalyzer.score(item, mode: mode))         }         return .scoredItems(scored)     } }

extension CustomStage where Self == SentimentStage {     static func sentiment(mode: String = "all") -> Self {         SentimentStage(mode: mode)     } }

// Usage: let tool = SpotlightSearchTool(configuration: .init(     customStages: [.sentiment(), .sentiment(mode: "positive")] ))

## Topics

### Getting the stage metadata

- [name](corespotlight/customstage/name.md)
- [description](corespotlight/customstage/description.md)
- [inputTypes](corespotlight/customstage/inputtypes.md)
- [outputTypes](corespotlight/customstage/outputtypes.md)

### Performing the stage behavior

- [execute(items:)](corespotlight/customstage/execute(items:).md)
- [execute(scoredItems:)](corespotlight/customstage/execute(scoreditems:).md)
- [execute(text:)](corespotlight/customstage/execute(text:).md)
- [execute(count:)](corespotlight/customstage/execute(count:).md)
- [execute(groupedItems:)](corespotlight/customstage/execute(groupeditems:).md)
- [execute(statisticName:value:)](corespotlight/customstage/execute(statisticname:value:).md)
- [execute(table:)](corespotlight/customstage/execute(table:).md)

## Relationships

### Inherits From

- [ConvertibleFromGeneratedContent](foundationmodels/convertiblefromgeneratedcontent.md)
- [ConvertibleToGeneratedContent](foundationmodels/convertibletogeneratedcontent.md)
- [Decodable](swift/decodable.md)
- [Encodable](swift/encodable.md)
- [Generable](foundationmodels/generable.md)
- [InstructionsRepresentable](foundationmodels/instructionsrepresentable.md)
- [PromptRepresentable](foundationmodels/promptrepresentable.md)
- [Sendable](swift/sendable.md)
- [SendableMetatype](swift/sendablemetatype.md)

## See Also

### Tool customization

- [SearchPipelineData](corespotlight/searchpipelinedata.md)
- [SearchPipelineDataType](corespotlight/searchpipelinedatatype.md)
- [ScoredSearchableItem](corespotlight/scoredsearchableitem.md)