---
title: Constants And Runtime Reference
description: "## Credentials ``` define( 'GOAIF_ANTHROPIC_API_KEY', '...' ); define( 'GOAIF_OPENAI_API_KEY', '...' ); ``` Matching environment variables are also recognized. PHP constants take precedence. These values are provider secrets and are never database-encrypted by the plugin. ``` define( 'GOAIF_CREDENTIAL_ENCRYPTION_KEY', 'def00000...' ); ```…"
url: "https://brightleafdigital.io/docs/constants-and-runtime-reference/"
updated: "2026-11-18"
category: GravityOps AI Feed / Developer Reference
---

# Constants And Runtime Reference

## Credentials

```
define( 'GOAIF_ANTHROPIC_API_KEY', '...' );
define( 'GOAIF_OPENAI_API_KEY', '...' );
```

Matching environment variables are also recognized. PHP constants take precedence. These values are provider secrets and are never database-encrypted by the plugin.

```
define( 'GOAIF_CREDENTIAL_ENCRYPTION_KEY', 'def00000...' );
```

Optional Defuse Crypto ASCII-safe key used only for credentials saved through WordPress. Choose the encryption method before saving credentials; changing it requires re-entering saved values.

## Private Provider Hosts

```
define( 'GOAIF_ALLOW_PRIVATE_PROVIDER_HOSTS', true );
```

Allows provider profile base URLs that use plain HTTP or point to a private, loopback or link-local address, for a local server such as Ollama. Without it, a custom base URL must use HTTPS and resolve only to public addresses; this is checked on save and on every request. The constant applies to every profile on the site.

## Trusted Proxies

```
define( 'GOAIF_TRUSTED_PROXIES', '192.0.2.0/24, 2001:db8::/32' );
```

Entries are merged with Controls values. Invalid entries are ignored. Use only official ranges for the service directly in front of WordPress.

## Provider Timeouts

```
define( 'GOAIF_PROVIDER_TIMEOUT', 60 );
define( 'GOAIF_ASYNC_WALL_CLOCK_LIMIT', 120 );
```

`GOAIF_PROVIDER_TIMEOUT` overrides the source-aware provider HTTP timeout. Without it, frontend text, streamed text, and frontend image requests use 60 seconds; other synchronous requests use 45 seconds. Async and workflow runs use the async wall-clock value as their provider ceiling.

## Public Limits

The default visitor limit is 10 requests in 3,600 seconds. The configured limit is constrained to 1–100 and the window to 60–86,400 seconds. The network ceiling is three times the visitor limit, capped at 100.

## Filters

```
add_filter( 'goaif_openai_image_request_body', function ( $body, $request ) {
    $body['background'] = 'opaque';

    return $body;
}, 10, 2 );
```

Adjusts the OpenAI image request body immediately before it is sent. The body has already been validated against the reviewed provider contract, so anything added here is sent as-is and is your responsibility to keep valid for the selected model. Always return the array; a non-array return is discarded and the unfiltered body is sent.

```
add_filter( 'goaif_image_moderation_message', function ( $message, $context ) {
    return $context['base'];
}, 10, 2 );
```

The message shown when OpenAI declines an image prompt on content grounds. `$context` carries `base`, `lines` (the sentences appended to it), `stage`, `categories`, `prompt`, and the three attribution buckets: `visitor_suggestions` (traced to the visitor's answers), `feed_level_rules` (traced to the feed's own prompt) and `unattributed_topics` (named by OpenAI, matched in neither). The example above keeps the opening sentence and drops everything appended. Return a string; anything else is discarded. The per-feed Content Refusal Message setting supplies `base`, and this filter runs after it.

`feed_level_rules` is deliberately absent from the default message: those causes are the administrator's to fix, so exposing them here would tell a visitor to change text they cannot reach. Add them only for an audience that can act on them.

```
add_filter( 'goaif_image_moderation_rules', function ( $rules ) {
    unset( $rules['distress'] );

    return $rules;
} );
```

The table mapping refusals onto suggestions. Each entry accepts:

- `categories` — labels OpenAI reports in `moderation_details`. Each reported category selects at most one rule, preferring an exact match, so `sexual/minors` uses the rule listing it rather than also repeating the general `sexual` rule.
- `patterns` — whole-word, case-insensitive keywords, a trailing "s" tolerated. Serve two purposes: they decide *whose* wording it was by testing the sent prompt against the feed template, and they select the rule outright when no reported category maps to one. OpenAI frequently answers with the catch-all `other`, so that second path is the common case, not the exception; results reached that way are flagged `inferred` in the filter context and labelled as such in the admin table.
- `suggestion` — the sentence shown when the wording is the visitor's.
- `topic` — a short noun phrase ("weapons, injuries, or conflict") used when ownership cannot be established: "This was declined for {topic}. Check your answers…".

At most three suggestions are appended to any message. Return the array; anything else is discarded. Write both `suggestion` and `topic` in the visitor's voice, about their own answers.

```
add_filter( 'goaif_generated_value_is_html', function ( $is_html, $value, $field ) {
    return $is_html;
}, 10, 3 );
```

Whether generated output bound for a rich-text destination is already HTML. When it is, the value is saved as written; when it is not, the supported Markdown subset is converted first. The default decision looks for the tags the converter itself emits (`p`, `br`, `h1`–`h6`, `ul`, `ol`, `li`, `blockquote`, `strong`, `em`, `b`, `i`, `a`). Return `true` to keep output that uses other tags, or `false` to force Markdown conversion and escape any tags in it. `wp_kses_post()` runs on both paths, so this filter cannot be used to save unsafe markup.

### Field Output Adapters

```
use GravityOps\AIFeed\Runtime\Fields\FieldOutputAdapterRegistration;

add_filter( 'goaif_field_output_adapter_registrations', function ( $registrations ) {
    $registrations[] = FieldOutputAdapterRegistration::exact_type(
        'my_custom_field',
        new My_Custom_Field_Output_Adapter()
    );

    return $registrations;
} );
```

Adds explicit field-output adapters. The adapter must implement `FieldOutputAdapterInterface`; frontend use additionally requires `FrontendFieldOutputAdapterInterface`. Register one exact declared type, effective input type, or effective field class. There is no catch-all selector, and extension-provided destinations require Premium or Agency. Replacing an intentional protected denial is available only through the third argument of `exact_type()` and should be reserved for a reviewed adapter that owns that exact custom field type.

```
add_filter( 'goaif_field_output_adapter_support', function ( $supported, $field, $target_id, $adapter, $support ) {
    if ( 'my_custom_field' === $field->type && ! my_site_allows_ai_output( $field, $target_id ) ) {
        return false;
    }

    return $supported;
}, 10, 5 );
```

Vetoes an exactly resolved adapter for one live field configuration. It cannot enable an unregistered or intentionally denied field. Return a Boolean; invalid values and exceptions fail closed before a provider request.

### Active Output Plan

```
use GravityOps\AIFeed\Runtime\Output\OutputPlan;

add_filter( 'goaif_active_output_plan', function ( $plan, $context ) {
    $items = array_values(
        array_filter(
            $plan->get_items(),
            static fn( $item ) => 'internal_notes' !== $item->get_response_name()
        )
    );

    return new OutputPlan(
        $items,
        $plan->get_existing_values(),
        $plan->requires_structured_output()
    );
}, 10, 2 );
```

Can remove or reorder the exact immutable items already approved for the current provider request. It cannot add a destination, duplicate an item, change Existing Values policy, or weaken the structured-output requirement. Return a non-empty `OutputPlan`; invalid plans and exceptions fail closed. `$context` contains only `feed_id`, `form_id`, `entry_id`, and `source`.

### Normalized Values And Terminal Events

```
add_filter( 'goaif_normalized_field_output', function ( $value, $item, $context ) {
    return $value;
}, 10, 3 );
```

Filters one canonical semantic value before persistence or frontend delivery. The same adapter normalizes the returned value again, so this filter cannot bypass the current field contract. `$item` is the active `OutputPlanItem`; `$context` contains only the safe request identifiers.

```
add_action( 'goaif_field_persistence_result', function ( $outcome, $context ) {
    // Observe one field's persisted or skipped status without receiving its generated value.
}, 10, 2 );

add_action( 'goaif_text_feed_terminal', function ( $context ) {
    // Observe the final feed status without receiving prompts, entry values, or provider output.
} );
```

The per-field action supplies `field_id`, `status`, and `reason_code`, followed by the safe request context. The terminal action supplies those request identifiers plus `status`, `outcome`, `error_code`, `persistence_status`, `persisted_field_ids`, and `skipped_field_ids`. These payloads deliberately exclude prompts, provider output, and entry values.

```
add_filter( 'goaif_entry_note_enabled', function ( $enabled, $entry, $feed ) {
    return $enabled;
}, 10, 3 );

add_filter( 'goaif_entry_note_content', function ( $content, $entry, $feed ) {
    return $content;
}, 10, 3 );
```

Control the AI-output entry note of a text feed whose Entry Note setting is on. Return `false` from the first to skip a note; a note-only feed then fails, because the note is its only output. The second receives the rendered, sanitized note text, and its return value is sanitized to plain text again. Output notes use the note type `goaif` with the sub-type `ai_output`, or `ai_output_rerun` for an administrator rerun.

```
add_filter( 'goaif_text_generation_clients', function ( $clients ) {
    return $clients;
} );
```

Provider-keyed text clients. Each must implement `TextGenerationClientInterface`; entries that do not are dropped. The built-in keys are `anthropic`, `openai` and, in paid builds, `openai_compatible`.

A run that used a fallback model writes two ledger rows: the failed first attempt with the outcome `provider_failed_fallback`, then the final row, whose provider and model are the ones that answered. The `goaif_feed_processed` result's usage then includes `fallback_used`, `served_provider` and `served_model`.

## Abilities

On WordPress 6.9 and later the plugin registers abilities with the WordPress Abilities API, in the `gravityops` category. WordPress serves them over its REST API and to assistants through an MCP adapter, so the plugin can be inspected and operated without its admin screens. Authenticate REST calls as a user, for example with a WordPress application password.

Every ability requires Gravity Forms full access (`gform_full_access`), the same as the plugin's screens, and applies the same plan limits. None returns an API key or a provider's raw response.

| Ability | What it does | Changes anything? |
| --- | --- | --- |
| `goaif/list-feeds` | Lists AI text and image feeds: form, type, provider, model, model lifecycle, trigger, active, and the plan a paused feed needs. Optional `form_id`. | No |
| `goaif/get-feed` | One feed with its full settings, including prompts. Takes `id`. | No |
| `goaif/check-feed` | Lists what would stop a saved feed from running. Takes `id`. | No |
| `goaif/list-feeds-needing-attention` | Feeds on a deprecated or retired model, with the recommended replacement and what an update would change, and feeds whose settings would stop them from running. | No |
| `goaif/list-models` | The model catalog with lifecycle status, replacement and retirement date, plus the feeds on deprecated or retired models. | No |
| `goaif/create-feed` | Creates a text or image feed after checking its settings. Takes `form_id`, `name`, `settings`, optional `type` (`text` or `image`) and `active`. | Yes |
| `goaif/update-feed` | Merges `settings` over a feed's saved settings (a `null` value removes a setting) after checking the result. Takes `id`, optional `name`, `settings`, `active`. | Yes: the previous values are not kept |
| `goaif/update-feed-model` | Moves a feed to the recommended replacement of its model, or to a named `model`, and resets the settings tied to the old model. Takes `id`. Returns every change. | Yes: the previous values are not kept |
| `goaif/get-usage` | Ledger totals (runs, successful runs, input and output tokens) grouped by `source`, `provider`, `model`, `form_id` or `feed_id`. Optional `since`, `until` (UTC), `form_id`, `feed_id`. | No |
| `goaif/test-credential` | The Credentials tab's test for a `provider` and optional `profile_id`. Returns the per-step report. | Sends billed test requests |
| `goaif/run-feed` | Runs a feed for an existing entry, exactly like the entry screen's Rerun button. Takes `feed_id` and `entry_id`. Premium and higher. | Yes: a billed request that overwrites the feed's destination fields |

Notes:

- **Creating and editing feeds.** `goaif/create-feed` and `goaif/update-feed` check the complete settings with the rules a feed must pass to run, and save nothing when a check fails; the error lists every problem. Setting names are the ones `goaif/get-feed` returns. A setting whose name looks like a secret is refused, because a feed names a saved key by profile ID and never holds one.
- **Gravity Forms' own feed abilities** (`gravityforms/feeds-create`, `feeds-update`, `feeds-delete`, with the add-on slug `goaif_text` or `goaif_image`) also work, and are the way to delete a feed. Gravity Forms saves the settings without asking the add-on to validate them, so call `goaif/check-feed` afterwards. A feed with invalid settings is still safe: the same rules are enforced each time it runs, and it fails with a clear error instead of running.
- **Moving off a deprecated model.** `goaif/list-feeds-needing-attention` then `goaif/update-feed-model` for each feed does what the **Update to (model)** button does on the Feeds tab.
- **`goaif/run-feed` on a feed with MCP tools repeats the tools' actions**, like the Rerun button. It asks for no confirmation; the caller is responsible for checking the entry's notes first.
- **`goaif/run-feed`** does not return the generated text or image. The result is saved to the entry, where the usual entry permissions apply.
- **`goaif/test-credential`** shares the Credentials tab's limit of five tests of the same key in five minutes.
- **Gravity Forms' MCP server.** These abilities are not listed under Forms > Settings > MCP. They are available through WordPress's REST API and a site-wide MCP adapter.

## Storage

Plugin options use the `goaif_` prefix. Custom tables store usage events, generation tokens, rate limits, and image sessions. Uninstall removes plugin options, scheduled cleanup, tables, entry metadata, and lock transients.

## Runtime Sources

Internal source names include `submission_sync`, `submission_async`, `realtime_ajax`, `realtime_stream`, `image_stream`, `rerun`, and `workflow_step`. Trigger matching applies to normal submission/frontend sources; a rerun or workflow step is an explicit administrator/workflow action.

## Stuck? Ask in GravityOps Help

Search past answers or post your question, tagged "ai-feed".

- [GravityOps AI Feed: a feed did not run on submission](https://brightleafdigital.io/community/gravityops-help/4147/)GravityOps Help - 0 replies - 2 weeks ago
- [GravityOps AI Feed is live: Claude and OpenAI as Gravity Forms feeds](https://brightleafdigital.io/community/announcements/3931/)Announcements - 0 replies - 4 weeks ago

[Ask in GravityOps Help](https://brightleafdigital.io/community/gravityops-help/?gofrm_tag=ai-feed)[Open a support request](https://brightleafdigital.io/support/)

GravityOps Weekly

[This iframe contains the logic required to handle Ajax powered Gravity Forms.](about:blank)
