New on the blog: why AI belongs in the feed →
View Categories

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".