AI Mediators

How Mediators Fit into Verification

FinalTX supports a three-tier verification model. Mediators are tier two — they run when deterministic checks are inconclusive or when the deliverable requires qualitative evaluation.

Mediator Outcomes

A mediator always returns one of five outcomes along with a confidence score (0–100) and a reasoning trace.

Registering a Mediator Module

Mediators are registered via the Modules API. The definition field must be a valid OpenAPI 3.1 document with a single POST /evaluate operation.

{
  "id": "content-quality-rubric-v1",
  "name": "Content Quality Rubric",
  "version": "1.0.0",
  "description": "Evaluates written content against a quality rubric using an LLM.",
  "category": "content",
  "scope": "official",
  "definition": {
    "openapi": "3.1.0",
    "paths": {
      "/evaluate": {
        "post": {
          "operationId": "evaluate",
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contract_terms": { "type": "object" },
                    "delivery_payload": { "type": "object" },
                    "verification_report": { "type": "object" }
                  },
                  "required": ["contract_terms", "delivery_payload"]
                }
              }
            }
          },
          "responses": {
            "200": {
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "outcome": {
                        "type": "string",
                        "enum": ["release", "refund", "split", "retry", "escalate"]
                      },
                      "confidence": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 100
                      },
                      "reasoning": { "type": "string" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Decision Artifact

Every mediator execution produces a decision artifact stored in the audit trail. The artifact is attached to the contract's receipt bundle for compliance purposes.

{
  "mediator_id": "content-quality-rubric-v1",
  "outcome": "release",
  "confidence": 91,
  "reasoning": "The article meets all rubric criteria: word count exceeds minimum (1,240 words), all required sections are present, readability score is within acceptable range (Flesch-Kincaid 62), and the tone is consistent with the brief.",
  "was_escalated": false,
  "artifact_id": "med_01jk9x2..."
}

Using Mediators in Workflows

Add a mediator step to any workflow. If the confidence score falls below escalation_threshold, the workflow branches to the step specified in on_escalate — typically a human_approval step.

{
  "name": "AI Content Review",
  "steps": [
    {
      "id": "fetch_delivery",
      "type": "http_request",
      "config": {
        "method": "GET",
        "url": "{{delivery_url}}"
      }
    },
    {
      "id": "ai_review",
      "type": "mediator",
      "depends_on": ["fetch_delivery"],
      "config": {
        "mediator_id": "content-quality-rubric-v1",
        "input_mapping": {
          "contract_terms": "contract",
          "delivery_payload": "steps.fetch_delivery.http_response.body"
        },
        "escalation_threshold": 70,
        "on_escalate": "human_review"
      }
    },
    {
      "id": "human_review",
      "type": "human_approval",
      "config": {
        "prompt": "AI confidence was below threshold. Please review.",
        "reviewer_role": "buyer",
        "timeout_hours": 48,
        "timeout_action": "escalate"
      }
    }
  ]
}

Escalation Threshold

The escalation_threshold controls when a mediator outcome is treated as inconclusive and routed to the next tier. The default is 70.