> ## Documentation Index
> Fetch the complete documentation index at: https://docs.graphext.com/llms.txt
> Use this file to discover all available pages before exploring further.

# infer_aspect_polarity

> Extract aspect-based polarity from texts using OpenAI. Identifies entities mentioned in texts and separates them into positive and negative aspects based on expressed polarity. Returns two columns: one containing positively-mentioned entities and another containing negatively-mentioned entities. Optionally returns two additional columns with the reasons for the positive and negative classifications. 

## Usage

The following examples show how the step can be used in a recipe.

<Accordion title="Examples" icon="code" defaultOpen="true">
  <Tabs>
    <Tab title="Example 1">
      Extract positive and negative aspects from a text column

      ```stan theme={null}
      infer_aspect_polarity(ds.texts, {
          "integration": "open-ai-1",
          "model": "openai/gpt-4.1",
      }) -> (ds.positive_aspects, ds.negative_aspects)
      ```
    </Tab>

    <Tab title="Example 2">
      Extract aspects with their reasons

      ```stan theme={null}
      infer_aspect_polarity(ds.texts, {
          "integration": "open-ai-1",
          "model": "openai/gpt-4.1",
      }) -> (ds.positive_aspects, ds.negative_aspects, ds.positive_reasons, ds.negative_reasons)
      ```
    </Tab>

    <Tab title="Example 3">
      Extract aspects with reasons and categories

      ```stan theme={null}
      infer_aspect_polarity(ds.texts, {
          "integration": "open-ai-1",
          "model": "openai/gpt-4.1",
          "aspect_categories": ["food", "service", "pricing"],
      }) -> (ds.positive_aspects, ds.negative_aspects, ds.positive_reasons, ds.negative_reasons, ds.categories)
      ```
    </Tab>

    <Tab title="Signature">
      General syntax for using the step in a recipe. Shows the inputs and outputs the step is expected to receive and will produce respectively. For futher details see sections below.

      ```stan theme={null}
      infer_aspect_polarity(texts: category|text, {
          "param": value,
          ...
      }) -> (*aspects: column)
      ```
    </Tab>
  </Tabs>
</Accordion>

## Inputs & Outputs

The following are the inputs expected by the step and the outputs it produces. These are generally
columns (`ds.first_name`), datasets (`ds` or `ds[["first_name", "last_name"]]`) or models (referenced
by name e.g. `"churn-clf"`).

<Accordion title="Inputs" icon="right-to-bracket">
  <ParamField path="texts" type="column[category|text]" required>
    Column containing the texts to extract aspect polarity from.
  </ParamField>
</Accordion>

<Accordion title="Outputs" icon="right-from-bracket">
  <ParamField path="*aspects" type="column">
    Output columns for aspect polarity results. If two column names are provided, returns
    positive and negative aspects. If four column names are provided, additionally returns
    the reasons for the positive and negative classifications. If five column names are
    provided and aspect\_categories is set, additionally returns the aggregated categories.
  </ParamField>
</Accordion>

## Configuration

The following parameters can be used to configure the behaviour of the step by including them in
a json object as the last "input" to the step, i.e. `step(..., {"param": "value", ...}) -> (output)`.

<Accordion title="Parameters" defaultOpen="true" icon="sliders">
  <ParamField path="integration" type="string" required>
    Associated integration.
  </ParamField>

  <ParamField path="model" type="string" default="openai/gpt-4.1">
    AI Model.
    AI model used for aspect-based polarity extraction. Each text is processed individually
    to identify entities and classify them as positive or negative.

    Values must be one of the following:

    `openai/gpt-4.1` `openai/gpt-4.1-mini` `openai/gpt-4.1-nano` `openai/gpt-5` `openai/gpt-5-mini` `openai/gpt-5-nano` `openai/gpt-5.1` `openai/gpt-5.2`
  </ParamField>

  <ParamField path="instructions" type="string" default="">
    Additional Instructions.
    Additional instructions to guide the polarity extraction process. Use this to provide
    domain-specific guidance or to focus on particular types of entities.
  </ParamField>

  <ParamField path="aspect_categories" type="array[string]">
    Aspect Categories.
    Optional list of aspect categories to focus on during extraction. When provided, the model
    will classify each extracted entity into one of these categories, and an additional
    categories output column will be available. For example:
    \["food", "service", "pricing", "cleanliness", "wait times"].

    <Accordion title="Array items">
      <ParamField path="Item" type="string">
        Each item in array.
      </ParamField>
    </Accordion>
  </ParamField>

  <ParamField path="deduplicate" type="[boolean, array[string]]" default="['entities', 'reasons']">
    Deduplicate Results.
    Whether to deduplicate extracted entities and/or reasons. Can be false (no deduplication),
    true (deduplicate reasons only), or a list specifying which fields to deduplicate
    (e.g., \["entities", "reasons"]).

    <Accordion title="Array items">
      <ParamField path="Item" type="string">
        Each item in array.

        Values must be one of the following:

        * `entities`
        * `reasons`
      </ParamField>
    </Accordion>
  </ParamField>

  <ParamField path="dedupe_model" type="string" default="openai/gpt-4.1">
    Deduplication Model.
    AI model used for deduplication when deduplicate is enabled.

    Values must be one of the following:

    `openai/gpt-4.1` `openai/gpt-4.1-mini` `openai/gpt-4.1-nano` `openai/gpt-5` `openai/gpt-5-mini` `openai/gpt-5-nano` `openai/gpt-5.1` `openai/gpt-5.2`
  </ParamField>

  <ParamField path="dedupe_batch_size" type="integer" default="2000">
    Deduplication Batch Size.
    Maximum number of entities per deduplication LLM call. Increase for larger datasets,
    decrease if hitting context limits.

    Values must be in the following range:

    ```javascript theme={null}
    100 ≤ dedupe_batch_size ≤ 10000
    ```
  </ParamField>

  <ParamField path="dedupe_instructions" type="string" default="">
    Deduplication Instructions.
    Additional instructions to guide the deduplication clustering process. Use this to
    specify domain-specific clustering rules, e.g., "Keep ride-related complaints separate
    from food-related complaints" or "Treat pricing complaints for different items as distinct".
  </ParamField>

  <ParamField path="consolidate" type="boolean" default="true">
    Consolidate Clusters.
    Whether to run an extra merge pass to consolidate similar clusters. This helps reduce
    near-duplicate clusters even within a single batch.
  </ParamField>

  <ParamField path="params" type="object">
    API Parameters.
    Additional parameters passed to the responses API.
  </ParamField>
</Accordion>