=== GravityAgent — AI Spam Filtering for Gravity Forms ===
Contributors: gravityagent
Tags: spam, antispam, gravity forms, forms, ai
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Spam filtering for Gravity Forms that learns from your corrections, needs no API key, and fails open so a problem never costs a lead. Free, no card.

== Description ==

GravityAgent scores every Gravity Forms submission for spam before notifications
fire, learns from the corrections you already make, and needs nothing set up: no API
key, no provider account, no CAPTCHA for your visitors. The free tier covers 250
scored submissions a month on one site, with no card.

**It learns from your corrections.** When you mark an entry as spam or not-spam with
Gravity Forms' own buttons, GravityAgent records the correction and sends the
relevant past corrections along as examples on that form's future submissions. No
training, no model tuning, no waiting: the next submission on that form already knows.

**There is nothing to set up.** Install, press Activate, and switch scoring on for a
form. GravityAgent reads your site's public pages itself and builds a profile of what
your business does, so an enquiry about your actual services is recognised as one
from the first submission. Write a sentence about your business in the notes field if
you like; it is optional.

**It fails open, on purpose.** Only a clean, well-formed verdict from the scoring
service can mark an entry as spam. A timeout, an outage, a quota, an expired plan, a
malformed response, a bug in our own code — every one of those admits the entry and
flags it "Not scored" with the reason. A spam filter that eats a real enquiry costs
more than one that misses a spam. That rule is the product. On our benchmark of 220
reviewed submissions across six synthetic sites it produced 0 false positives on 95
genuine submissions and caught 87.2% of the spam.

**It judges meaning, not keywords.** GravityAgent reads each submission the way a
person would and decides whether it is spam — using the meaning of what was written,
not a keyword list, a reputation score, or a CAPTCHA your visitors have to solve.

**It scores before the side-effects.** GravityAgent runs on Gravity Forms' own spam
filter, so an entry judged spam is spam natively: notifications, feeds and
confirmations are suppressed by Gravity Forms itself, exactly as they are for any
other spam entry.

**It never overrules your other filters.** If something has already judged a
submission spam — Gravity Forms' honeypot, Akismet, your own code — GravityAgent
leaves that judgment alone and makes no call at all.

= What you see =

* A **GravityAgent column** on the Entries table: the verdict, the spam likelihood,
  and a link to the reasoning.
* A **decision panel** on the entry detail screen: the reasoning in plain language,
  what informed the decision, and — when a submission was not scored — exactly why.
* A **settings page** under Forms → Settings → GravityAgent: your plan and usage,
  the site profile, and a notes field for anything about your business the scorer
  should know ("we are a dental practice; enquiries about implants are real").
* **Per-form and per-field control**: turn scoring on per form, and exclude any field
  from ever leaving your site.

= Requirements =

Gravity Forms 2.6 or later, WordPress 6.0 or later, PHP 7.4 or later, and a
GravityAgent account. The free tier needs no credit card.

= Plans =

Free: 250 scored submissions a month on one site, no card. Paid plans bill annually:
Starter $99 a year (1 site, 2,000 a month), Growth $249 a year (5 sites, 10,000 a
month), Agency $599 a year (25 sites, 50,000 a month). A 14-day Growth trial needs no
card. If a month runs past its limit, scoring pauses after a small grace allowance
and submissions come through unscored; nothing is ever charged as overage.

== External services ==

GravityAgent is a hosted scoring service. The plugin cannot score anything on its
own, so using it means sending form submissions to us. Exactly what is sent, when,
and why:

= 1. The GravityAgent Decision Engine (https://api.gravityagent.io) =

**On every submission of a form you have enabled**, the plugin sends one request
containing:

* **The submitted field values** of that entry — the same text your notification
  email would contain — **minus any field you have excluded** on the form's
  GravityAgent tab. Excluded field values are stripped before the request is built
  and never leave your site.
* **File uploads as metadata only**: the file name and field label. File contents
  and file URLs are never sent.
* **Ambient submission metadata**: the submitter's IP address, the browser user
  agent, the submission timestamp, and the URL of the page the form was on.
* **Past corrections you have made on that form**, as examples. An example carries
  the same field content the original entry holds (read live from that entry, minus
  your exclusions) plus the label you corrected it to. If you delete the entry, the
  example disappears with it.

**When you correct a verdict**, the plugin sends the decision id, the label you
corrected it to, and the direction of the correction — no submission content.

**When you activate the site**, the plugin sends your site's domain and, on a paid
plan, your licence key and merchant identifiers, in exchange for an API token. The
service then **crawls your site's public pages** — the same pages any search engine
reads — to build a profile of what your business does, so that a genuine enquiry
about your actual services is recognised as one. Nothing behind a login and no form
entries are read by the crawl.

**On the settings page**, the plugin sends and retrieves the notes you type into the
Admin Context field, and reads the crawl's status.

**Once a day**, an activated site asks the service for its current plan, usage and
renewal date, so the settings page stays accurate on a site that has had nothing to
score. That request carries six counts of what happened to submissions since the last
successful one: how many were scored, and how many were not scored because the request
timed out, the service could not be reached, your monthly limit was reached, your
subscription was inactive, or the site was not activated. They are counts and nothing
else — no form content, no field values, no entry or form identifiers, no page URLs.
They exist so we can measure how often the plugin has to fail open and admit an entry
unscored, which is the promise it is built on. There is no third-party analytics in
this plugin, and nothing else is sent in the background.

Submissions are processed to return a verdict and are not used to train any model.
The service is operated by GravityAgent.

* Terms: https://gravityagent.io/terms
* Privacy policy: https://gravityagent.io/privacy
* Data Processing Addendum: https://gravityagent.io/dpa
* Subprocessors: https://gravityagent.io/subprocessors

= 2. Freemius (https://freemius.com) =

Licence activation, checkout, the trial and plugin updates are handled by Freemius,
our merchant of record. Freemius receives your site URL, WordPress and PHP versions
and, if you opt in, your administrator email address and a plugin usage profile. It
is opt-in: the plugin works fully if you decline.

* Terms: https://freemius.com/terms/
* Privacy policy: https://freemius.com/privacy/

== Installation ==

1. Install and activate Gravity Forms 2.6 or later.
2. Install GravityAgent and activate it.
3. Go to **Forms → Settings → GravityAgent** and press **Activate on the Free plan**.
   The free tier needs no licence key and no card. Enter a licence key first and the
   same button reads **Activate this site**.
4. Open a form's **Settings → GravityAgent** tab and switch scoring on. Repeat for
   each form you want scored — nothing is scored until you say so.
5. Optional, and worth two minutes: on the settings page, describe your business in
   the notes field; and on a form's GravityAgent tab, under **Fields to keep on this
   site**, tick any field whose contents should never leave your site.

== Frequently Asked Questions ==

= What happens if GravityAgent is down, or my plan lapses? =

The submission is admitted and flagged "Not scored", with the reason recorded on the
entry. Nothing is ever marked spam because of a failure on our side. This is the one
behaviour the plugin will never trade away.

= Does it replace my CAPTCHA or honeypot? =

It can. GravityAgent judges what was written rather than whether a human wrote it, so
it asks nothing of your visitors. It also composes with whatever you already run:
anything another filter has already marked spam is left exactly as it is, with no
call made.

= Can one licence cover several client sites? =

Yes. Growth covers 5 sites and Agency covers 25, each activated separately from its
own settings page and each learning from its own corrections. The settings page lists
the sites using the licence and lets you free a slot.

= Which fields are sent? =

Every mapped field on a scored form, except the ones you exclude on that form's
GravityAgent tab. Passwords and pure presentation fields are never offered or sent.
File uploads are sent as a file name only.

= Can I stop a specific field ever leaving my site? =

Yes. On the form's GravityAgent tab, tick it under **Fields to keep on this site** — a
ticked field is the one that is kept back. Exclusion is applied when the request is
built, so an excluded value stays on the entry in WordPress and never reaches us —
including in the correction examples sent later.

= How do I teach it about my business? =

Two ways, both already in front of you. Mark a wrong verdict with Gravity Forms' own
"Spam" / "Not Spam" buttons — that correction feeds into that form's future
decisions. And write a sentence or two into the notes field on the settings page.

= Where is my data stored? =

Entries stay in WordPress; the entry is the authoritative record. GravityAgent stores
the non-content record of a decision and your corrections' labels — never the field
values. Deleting an entry in WordPress deletes its content everywhere it matters,
including the example it would otherwise have provided.

= What does uninstalling remove? =

Deleting the plugin removes every option it created, its corrections table, and its
activation, and hands your licence slot back. Giving the activation back deletes the
site profile and your notes from the service right away, the same as pressing
Deactivate on the settings page. **Your entries and their decision history are left
untouched** — they are your record, and deleting them is your call, made with Gravity
Forms' own delete.

= Does it work on multisite? =

Each site activates separately and is metered separately. The uninstall sweep runs
for the site the plugin is deleted from.

= Does it slow down my forms? =

One request with a three-second ceiling and no retries. If the answer has not arrived
by then the submission goes through unscored. Forms you have not enabled make no call
at all.

== Screenshots ==

1. The GravityAgent column on the Entries table: the verdict, the spam likelihood, and a link to the reasoning.
2. The decision panel on an entry: the reasoning in plain language, what informed the decision, and the decision details.
3. A corrected verdict. Your correction informs future decisions for this site.
4. Settings → GravityAgent: your plan and usage, and the profile GravityAgent built from your public pages.
5. A form's GravityAgent tab: switch scoring on, and keep any field on this site.
6. The onboarding checklist: two steps to your first scored submission.

== Changelog ==

= 0.1.0 =
* First release.
* Scores Gravity Forms submissions against the GravityAgent Decision Engine on the
  native `gform_entry_is_spam` filter, before notifications, feeds or confirmations.
* Fail-open in every failure mode, with the reason recorded on the entry.
* Per-form enable and per-field exclusion.
* Corrections captured from Gravity Forms' own mark-as-spam / not-spam actions and
  fed back as examples on that form's later submissions.
* GravityAgent column on the Entries list and a decision panel on the entry detail
  screen.
* Settings page: plan and usage, site profile crawl, Admin Context notes.
* Licensing, checkout, the 14-day trial and updates via Freemius.

== Upgrade Notice ==

= 0.1.0 =
First release.
